S6S Weapon Integration Tutorial

S6S Modding Tutorials

 

Prerequisites:

You'll need to have installed:

New Vegas

JohnnyGuitar NVSE

JIP LN NVSE

GECK

GECK Extender

-The GECK must be set up to run NVSE. You do this by creating an NVSE shortcut, then putting -editor in it's launch argument.

-Example: https://i.imgur.com/AlxrSO7.png

FNVEdit

Notepad++

 

Optional, but highly recommended:

Hot Reload (Allows you to reload your script and check updates while the game is loaded, saving *tons* of debug time)

Improved Console (It's usually pretty quick to use a console command to test things, but sometimes the useful info is too long for you to scroll back up to in the in game console, and Improved Console will print the console log in your base game folder, so that you can check it there)

 

 

WEAPON INTEGRATION

Starting Criteria:

This weapon integration tutorial covers the scripted integration of a mod, and some other secondary things. This does not cover making your weapon, or it's animations, or sounds work.

For this tutorial, you need to already have an existing, fully functional weapon entry in a plugin.

 

To start things off, open your plugin. I prefer doing pretty much all non-script work in FNVEdit, because it lets me see overwrites, and provides a much clearer UI that I find more comprehensible, but the GECK can of course do just about everything you need, other than plugin cleaning.

 

STEP 1: What is a leveled item, and what do it's flags do?

A leveled item (hereafter referred to as a lvli) is an "item" that will provide the game world one of a selection of the possible items included inside of it.

Take a look at a base game lvli whose editor id contains "cond" in it. You'll see a set of entries of all the same weapon, at different health values. Health values are a percentage out of 1: 0.35 equals 35% health, .71 means 71% health, etc.

 

The "level" of a lvli entry dictates at what level the player/npc has to be for that item entry to potentially be spawned.

In loot and vendor lists, the *player's* level is checked. For NPCs, the NPC holding the leveled item's level is checked.

Some condition lists (mostly NPC condition lists) have all their entries at the same level.

However, some set their higher condition entries to higher levels. This means that generally, at lower levels, since the NPCs' level scaling hasn't taken much effect, their weapons will be low health, making it more difficult for enemies to kill you incredibly quickly, and preventing you from getting rich too quickly by finding high health weapons to resell.

 

NPC condition lists generally have higher overall condition, and are mostly given to non-hostile NPCs, so that their weapons deal enough damage for them to have a fighting chance when attacked, Since the player is generally disincentivized from killing many non hostile npcs, this doesn't affect economy balance nearly as much as high condition weapons in raider lists tend to.

Brotherhood/Enclave/other faction condition lists often have higher or lower overall condition levels, to represent the quality of weapon being maintained by members of certain factions.

 

Loot lists belong in loot lvlis. They show up in containers and such, and generally not on NPCs.

 

Lvlis can contain other leveled items. For example, you could make a leveled item that has throwing spears as it's main weapon, then a backup lvli included as well, so that the npc doesn't have no weapon left once they've thrown all their projectiles.

 

The "Calculate for each" lvli flag determines whether the game will roll for one entry in a lvli, then duplicate it as many times as the count it's being asked for, or, if it will instead roll for each count it's being asked for individually.

For example: You have a container called SchoolDesk. It has Apple x1 and the leveled item "PencilLoot" x3 in it.

https://i.imgur.com/1VYkZ0B.png

PencilLoot contains 3 entries: Pencil x1, Pencil x2, and Pencil x3.

https://i.imgur.com/tjvyhKa.png

Wherever this desk is placed, it will always have a single apple in it when the player finds it for the first time. However, the amount of pencils will be different each time the player finds this container.

The container currently might

Choose 1 pencil from the lvli, then duplicate it 3 times, providing 3 pencils.

Choose 2 pencils from the lvil, then duplicate them 3 times, providing 6 pencils.

Or choose 3 pencils, providing a total of 9 pencils.

If the "Calculate for Each" flag is set, the game could provide 3, 4, 5, 6, 7, 8, or 9 pencils, based on whether it grabbed one, two, or three pencils each time it rolled the dice for one of it's counts.

 

The "Chance None" value dictates how likely it will be that the game *will not* give that lvli's item when requested.

https://i.imgur.com/KewpY5b.png

In this SchoolDeskChanced container, the container might now have *0*, 3, 6, or 9 pencils. This is because the game might roll the dice and determine that it will not provide the item, based on the chance none, and then it will "duplicate" that lack of an item three times, since that's the count in the container, and it will result in 0.

Adding the "Calculate for Each" flag would mean that the possible pencil count would be 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9, since the game might roll the chance none for each count individually.

 

The "Calculate for all levels <= player's level" flag is not as straightforward. It checks the player's level for loot, vendor, and container lists, but it checks the holding NPC's level, if this leveled item is placed in an npc's inventory.

If you were to set the 3 pencil entry to level 5, the player would only be able to find 3 or 6 pencils in the container, until they reach level 5, at which point the *only* possibility would become 3 pencils, multiplied by the count of the lvli in it's container.

https://i.imgur.com/d5Qa57G.png

Adding the "Calculate for Each" flag would mean that the possible loot would, instead of changing to *only* the highest level that the player/npc has reached, *expand* to have the potential to grant three pencils per count of lvli in a container instead.

 

The "Use All" flag overrides all other flags, and ensures that the game provides all included items for every single count of the lvli.

https://i.imgur.com/UDSeFp3.png

https://i.imgur.com/ZHanMEU.png

You would find exactly 1 pencil, 2 apples, and 3 carrots in this desk everywhere it was placed.

However, with this count, you would always find exactly 4 pencils, 8 apples, and 12 pencils.

https://i.imgur.com/bmDBJ6w.png

The use all flag is often used for WithAmmo lists, and for general loadouts in some cases.

An NPC must have *at least* one round of the ammo that their weapon has, to fire it. With a single bullet, they will be able to fire and reload infinitely. WithAmmo lists contain a guaranteed ammo round, a chanced amount of additional rounds, a chanced amount of hulls/cases/drained cells, and a weapon condition lists, with the Use All flag set.

 

The base game uses "75" lists for a lot of leveled items. A "75" list generally contains a single entry for an item with it's Chance None set to 25, and the calculate for each flag set, meaning that when the game asks for that lvli, it will provide up to a maximum of the count it asks for, but each individual item will roll a 25% chance to not be provided. A container with a count of 8 of the Ammo10mm75 lvli will have up to a *max* of 8 ammo to spawn with it, but it may have as low as 0.

 

STEP 2: Your weapon needs a condition list.

Start by either making a new lvli if you're in the GECK, or "copy as new record" a base game lvli in the FalloutNV.esm into your plugin in FNVEdit.

I generally start the condition entries at about .2 health, generally extending them up to a max of .55, at .05 condition thresholds, and I set the max 4 conditions to higher levels. If you copied an existing record, change all the items to your new weapon.

Syntax: (Weapon Level Count Condition)

Example:

Weap10mmPistol 1 1 0.2

Weap10mmPistol 1 1 0.25

Weap10mmPistol 1 1 0.3

Weap10mmPistol 3 1 0.35

Weap10mmPistol 5 1 0.4

Weap10mmPistol 8 1 0.45

Weap10mmPistol 11 1 0.5

Weap10mmPistol 13 1 0.55

 

 

If you're *just* doing a non-ranged weapon, you're done making lvlis here. Non-ranged weapon cond lists are placed in loot/npc/container lists, as all they need to do is provide a variable conditioned weapon, since they don't use ammo.

If you're doing a ranged weapon, you will need a WithAmmo lvli:

A withammo lvli is what will actually be integrated into places in the base game and it's DLCs. It contains a single, 1-count weapon condition lvli entry, such as Cond10mmPistolLoot, a single, 1-count entry of the weapon's regular ammo type, such as Ammo10mm, an ammo 75 list entry, such as Ammo10mm75, set at the max potential ammo to be found with that weapon, and an casing/hull/drained cell 75 entry, such as Case10mm75, set at the max amount of casings/hulls/drained cells to be potentially found with the ammo.

 

Adding the condition list to the WithAmmo lvli means that a weapon of variable condition will be found in it's integration locations. The single 1-count ammo entry guarantees that any npcs it's provided to will be able to "load" their gun, allowing them to fire and reload forever. The Ammo75 entry (example: Ammo10mm75) provides a maximum amount of ammo for the player to find when they open that container or NPC. The Casing75 entry determines how many potential casings or drained cells will be found with the weapon. Casings/drained cells don't need the guaranteed entry like ammo does, because they're not crucial to the functioning of NPC weapons, so it's fine if they don't show up every time.

Explosives don't have hulls/casings generally, so they don't need those in their withammo lists.

 

Step 3: Scripted Integration

Once you've got your Cond list (in the case of melee weapons) or WithAmmo list (for ranged weapons), you can get started on the actual scripted integration:

In the GECK, make a new quest entry. Set it's ID, (name doesn't matter), priority to 55, tick the start game enabled box, and set the processing delay to .1. Close the quest, and save your plugin.

This has set up this quest to automatically start when a new game is started or the mod is loaded for the first time, which will automatically run your startup script each time the game runs.

 

Next, make a new script. Right away, *set the script type to QUEST* up at the top of the script window. If you don't, the script won't be visible when you go to attach it to your quest.

 

Now, we're going to start your integration script using the template below. This includes the formatting needed for naming your script, making sure it does it's commands at the right time, and just about all of the formlists you're likely to need to add an item to. This includes things like Shotgun Surgeon weapons, Grunt weapons, legion banned chems, casino weapon removal lists, and so on.

 

Open the integration script template, and copy and paste everything into your new script.

https://pastebin.com/ZAbw0dfZ

Change the script name to something of your own. I strongly recommend *against* starting your script name (or any editor ID) with a number, as it can cause problems.

 

Lines which start with a ; are commented out and not read when compiling your script. The notes in the integration template script are there to help inform you about what each section does. Feel free to remove them once you remember what each list is for.

 

Replace the qqq with the Editor ID of any of your weapons or other items that qualify for each list. Do this for every version of your weapon, if you have variants.

Make sure to find and add to any base game repair lists that your item might qualify for. You more than likely *don't* want to put any unique items in repair lists, as that will allow the player to accidentally (or purposefully) repair a generic version of a weapon with it's uniques.

 

Now you're at the leveled list choice part of the script.

There is an example of how the format works directly under a template line, filled with placeholder letters.

However, for the bulk of this, you'll want to be copy pasting from the leveled list compilation instead of duplicating that line.

https://pastebin.com/Z4h708r8

The lvli compilation is formatted for JIP leveled list and formlist additions. These are ListAddForm (replaces AddItemToFormlist) and LListAddForm (replaces AddItemToLeveledList). These are arguably superior replacements, because they don't bake into your save, allowing you to make each weapon/item optional, and able to be toggled at anytime, users won't experience *as much* of an issue if they remove your mod, and most importantly, YOU CAN UPDATE THE INTEGRATION SCRIPT ON EXISTING SAVES. The old command use method involved setting a DoOnce and stopping the startup quest, meaning that you can't update the script *literally at all* on existing saves. Using the JIP method bypasses all of those issues.

They're ready for you to copy paste into your script, then use Notepad++'s Find and Replace feature to replace all the instances of qqq in your new script with your Cond or WithAmmo list.

From here, you will generally need to use your intuition when deciding where to place your weapon. Feel free to ask questions about certain leveled lists and what should go in them, but the most independent thing to do will always be to just look at what's in the leveled list yourself.

 

There is one "editorial" factor due to *me* making this compilation, and not someone else:

I filled out the energy weapons sections with some lvlis which don't /always/ contain energy weapons in the base game. I chose relatively general lists, to expand the saturation of energy weapons in the game, since they're much less common than other weapon types. Simply avoid lists which don't say energy in them when copying from that list, and you should avoid that little flavoring choice by me, and your energy weapons will be much rarer, like in the base game.

 

The Gun Runner leveled lists are formatted differently than the rest, and their Editor ID spot has yyy instead of qqq:

The Gun Runners leveled lists don't use WithAmmo or condition lists, they get a direct entry of the weapon itself, set to 0.99 condition. This is the behavior in the base game. If you use a WithAmmo list there, the weapon will show up at noticeably lower condition than the other weapons provided by the Vendortron.

 

TTW entries are listed at the bottom.

 

* entries:

Any lists marked with a * do not have the "Calculate from all levels =< player's level" flag set, which means that they will provide any item in them, regardless of whether the player is fresh out of the vault at level 1, or at the end game and max level.

Use the following command on any lists marked with * to allow them to change their provided contents based on the player's progression:

LListSetFlags qq 1

 

Example:

LeveledListAddForm 188NCRArmsMerchantWeap WithAmmoSniperRifle* 18 1 1.0

If you're using this line, you want your weapon to only show up at a higher level; therefore you should also include the line

LListSetFlags 188NCRArmsMerchantWeap 1

to ensure that the sniper rifle is *not* the *only* candidate for spawning once the player hits that level.

 

My procedure is:

Copy my integration script into Notepad++

Copy and paste in all my leveled list choices, then at the end, use this tool to remove all lines NOT containing *

https://bedan.ir/modules/Tools/Remove-Lines-Containing.html

Copy the remaining lines back into a blank notepad++ file

Select LeveledListAddForm and find and replace LeveledListAddForm with nothing (Just click in the second box and backspace)

Do the same for the 1 1 1.0 parts and all their different leveled variants

One by one, find and replace all the withammo and cond list editor ids with nothing

Take the remaining lines, then find a remove duplicate lines tool

https://www.textfixer.com/tools/remove-duplicate-lines.php

Take the output text from that and go to this tool

https://pinetools.com/add-text-each-line

Paste your duplicates-removed text in the box on the left, select add text at the beginning of lines, put "LListSetFlags " in it, select add text after, and put " 1" in it, hit execute, then you have a block of commands that will set the flag appropriately on all the lists you chose that could use it.

Now, just paste those lines in at the end of your script, and use Find and Replace on * to delete all of them from earlier in the script.

You should probably make sure that your script is indented properly, for readability. Those lines won't be, once you process them with all those tools. Fortunately, you can paste your script into this tool

http://www.cipscis.com/fallout/utilities/validator.aspx

And it will auto indent it for you. (This tool will show you little error messages if you hover over them with the mouse; the tool hasn't been updated for years, so it doesn't know that the newer script commands are valid. You can ignore them)

 

Now, just copy paste that all back into your script, and hit save. If everything is valid, the little * next to the name of the script at the top of the script window will disappear, and the script will save. If not, you should have the GECK Extender installed, which will *actually tell you*, either via a pop-up or in the message log, what the problem with your script is. It may be a typo, or you may have forgotten to remove the *s from the earlier lines; I often do. That's why they're there, to make sure to remind you to set the flags on lists that need it.

 

 

You're done with most of the work now.

Go back to the quest you made earlier and open it. As long as you remembered to save your script as a quest script, you'll be able to select it in the script menu and attach your script. You can type "scpt" for the menu to automatically take you to the first script that starts with that.

Select it, then hit okay, and save your file.

 

Now to test!

Load up your file in the game. I suggest that when you load it for the first time, you uncomment the printc lines at the start and finish of the file, (and change what they say in the quotes to refer to your mod, for clarity) so that you can open the console and verify that your startup script started and finished successfully. There are cases where misuse of commands may lead to the script starting, but not finishing.

 

The easiest way to test your integration is with two commands:

DumpLevList xxx

DumpFormList xxx

 

Simply select one of the formlists or leveled lists that you added to, type the relevant command above, then the Editor ID that you're checking after it, hit enter, and the console will print all the items contained in that list. It may be long, but if you check it in the console log provided by Improved Console, and it has your item, you're good to go! It got added.