0.9a Compatibility

This is a modding guide for updating Starsector mods from version 0.8 to 0.9

Netbeans users

(as an aside, you should probably clear the Netbeans cache entirely after every SS update by deleting the folder under %USERPROFILE%\AppData\Local\NetBeans\Cache\ - this will save you a ton of headaches)

Quick checklist

A non-exhaustive checklist of commonly needed tasks

• Fields in ship_data.csv
• Fields in weapon_data.csv
• Fields in wing_data.csv
• Fields in hull_mods.csv

• Add variants in default_ship_roles.json
• Faction file entirely reworked

• MIRV projs reworked

• blueprints in special_items.csv

• new conditions and industries in the "system markets".json
• Modules defined differently in .variant files

Basic 0.9a Compatibility

In order to update a mod that worked in 0.8.1a to 0.9a compatibility, the following things need to be done:

1. Adjust any custom Market Conditions in market_conditions.csv which might refer to market condition scripts which no longer exist (due to those Market Conditions now instead being Industries)
2. Update your AddMarketplace method, if you use one (rather than the economy .json file that vanilla uses) to handle adding Industries as well as Market Conditions, and to pass the new WithJunkAndChatter boolean argument to globalEconomy.addMarket
3. Update any market definitions in your system generation scripts to include Industries instead of Conditions where they formerly included Conditions which were moved to Industries in 0.9a (i.e. Military Base, etc)
   1. If you use the economy market list .json, like vanilla, these above two steps (2 & 3) aren't necessary and you can just stuff industries (and even industry-modifying special items -- check Sindria for an example) into the list in your json file
4. Update any custom fleet spawning scripts you have to use FleetFactoryV3 rather than FleetFactoryV2
5. Define custom blueprints for your stuff in special_items.csv (if you want)
6. Apply blueprint-related tags to weapons, fighter wings, and ships in the relevant .csv files (update stuff like weapon tooltips too, while you're at it!) -- be careful here, as errors can cause a NullPointerException from the autofit when mousing over fleets on the campaign map
   1. Remember to apply faction tags ("persean", "derelict" etc) and/or blueprint tags ("pirate_bp", "midline_bp" "modprefix_your_custom_blueprint_bp" etc) to stuff you want to spawn in the campaign as well
7. Update the flux/shot of your multi-barrel weapons: it's now flux per bullets directly.
8. Doublecheck any variants of vanilla ships or using vanilla weapons that your mod includes for OP changes
   1. Also note that modules are now defined differently in variant files. Instead of being attached to a weapon mount in a weapon group, there is now a separate "modules" array field in the variant file. This array is independent of the "weaponGroups" array, and can be put directly after it.

The format of the array is roughly as follows:

"modules": [ {"SLOT_1":"MODULE_1"}, {"SLOT_2":"MODULE_2"}, ... ],

where each SLOT is a weapon slot ID and MODULE is the variant ID of a module ship, just as they were before. Each individual slot/module pairing should be enclosed in curly brackets, with multiple module fields being separated by commas. All those fields are then enclosed in square brackets alongside the "modules": tag. Make sure to move all your module mount specifications to this field and out of "weaponGroups".

1. Move ship variant role definitions for all factions to combined lists in default_ship_roles.json -- remember to add the combatSmallForSmallFleets section too ;)
2. Delete any .faction files for vanilla factions that consisted only of ship role definitions. note that if you do not do this, they will override vanilla and the ship variants you defined will be the only ships that spawn for those roles
3. Adjust any .faction files for factions added by your mod to use the new blueprint system -- the vanilla files are somewhat sparsely commented, so here's what we've been able to piece together so far for a 'how-to':
   1. "variantOverrides" restricts any hulls included in it to the listed variants only, and allows you to set the probability of said variants as well. Look at luddic_path.faction for an example -- they will only ever use Overdriven variants of the enforcer, hammerhead, and sunder, and will use them very frequently; 30 frequency each vs. a 'default' of 10 each for most variants that a faction has access to
   2. "hullFrequency" modifies the frequency of any hulls or blueprint tags listed in it to the listed value, from a default of 1. For example, in pirates.faction, the falcon_p hull is set to 0.5 or 50% frequency, as it's very powerful. In hegemony.faction, the buffalo2 hull is set to 0 frequency, and so will never spawn despite the hegemony 'knowing' that blueprint, and the heg_aux_bp tag is set to 2 or 200% frequency while the XIV_bp tag is set to 0.25 or 25% frequency as XIV ships should be fairly rare while militarized hegemony auxiliary ships should be very common, more common in fact than 'default' ships in hegemony fleets.
   3. "shipsWhenImporting", somewhat confusingly, is not "extra" ships the faction will get access to through trade. It should be the reduced list of available blueprints/ships which the faction will have access to from markets that do not have a Heavy Industry industry -- situations where a player colony would be restricted to base_bp Mules and Condors and Hounds, etc. Including ship hulls in the 'hulls' list will allow the faction to produce those ships even when they fall outside of blueprints listed in the 'tags' list.
   4. "knownShips" is the list of blueprints/ships the faction will produce from when they do have a Heavy Industry industry on the producing market. Including ship hulls in the 'hulls' list will allow the faction to produce those ships even when they fall outside of blueprints listed in the 'tags' list.
   5. "priorityShips" is the list of blueprints/ships the faction will preferably produce, even when others are available. Same as the way the player can flag some designs as "Priority" in-game.
   6. The rest of the groups are essentially the same as the above but for Fighter LPCs, Weapons, and Hull Mods.
   7. "factionDoctrine" replaces the old doctrine settings, and is the same as the player-accessible doctrine settings in game. Note that weird shit might happen if you set groups meant to be limited to a total of 7 (warships/carriers/phaseships, officerQuality/shipQuality/numShips) to a total of something else.
   8. Note there are some new entries under "fleetTypeNames" and "custom" (mostly relating to the way they interact with the player and the player's colonies, i.e. what they will send raids for, etc) as well.

NOTE FOR STARSECTOR 0.9a-RC10 AND BEYOND

Big change in version 0.9a-RC10 that potentially breaks all your settings if you were using .faction files or anything else that merges with vanilla files.

Modding:=

When merging json files: if a mod provides an empty json array, the merged json will be set to an empty array instead of appending the empty array to it (which is a no-op)

For example, "engineSlots":[] in a missile's .proj file will clear the engine slots instead of doing nothing

Specifically in .faction files blank arrays i.e. "tags", "hulls", "fighters", "weapons", "hullMods" etc need to be removed.

I.E. including a bit like:

     "knownShips":{
         "tags":[],
         "hulls":[
         ],
     }, 

in a faction file will cause that faction to know ZERO ships, overwriting both their known ship tags and any specific hulls they might have known outside of tags. Likewise, including an empty [] "tags" and a list of your added ships will force them to use ONLY those hulls.

In order to avoid this, it is a good idea to do one of the following if adding ships to a vanilla faction:

• EITHER Remove or comment out all empty arrays in your .faction files (including multi-line arrays like "knownShips"!)
  • this option offers more control if you want your blueprint (i.e. "mymod_pirate_bp") to be lootable from a faction's military bases or to make fine-grained spawn weight adjustments for a specific faction (vs just using the "rarity" columns in the data .csvs and/or the variant weights in default_ship_roles.json)
• OR Delete all .faction files for factions other than those added by your mod (if you didn't do this in the 0.9a compatibility process while moving your variant role definitions to default_ship_roles.json) and manage spawning in campaign by adding them to faction tags and/or existing blueprints
  • this option is cleaner and simpler if you're just adding generally-available (or generally-rare) ships to existing blueprints (i.e. "pirate_bp") and/or faction tags (i.e. "pirates")

Similar issues will occur if you have any other files that merge with vanilla (graphics updates or balance patches, perhaps?)