Data Merging and Replacing

You should know about .json and .csv file formats from the Data and file types page before reading this page.

Starsector holds a lot of data in .json and .csv files. When you make your own mod, you want some way to add your own data to them. For that purpose, the game has ways for you to add or replace existing data.

CSV Merging and Replacing

As a general rule, if you want to add or replace something from Starsector, you have to match the filename and folder location to that of the target you are planning to modify. If either of those two does not match the target, then the game will ignore your file entirely. Notice how in the example below, Starsector has a file at /data/hullmods/hull_mods.csv. So to modify it, we also have to match this very path in our mod folder.

Starsector
- mods
  - YourMod
    - data
      - hullmods
        hull_mods.csv ✓ Same name and relative file location, its rows will be merged with Starsector's file.
      - hullmod
        hull_mod.csv ✗ File name doesn't match, and the relative path doesn't match either, so it will not be merged.
- starsector-core
  - data
    - hullmods
      - hull_mods.csv

Now, when Starsector starts loading its data, it will do so by first loading its own hull_mods.csv file. After it is done, it will start checking every mod to see if they also have the hull_mods.csv file. It does so while following the Load Order of mods. Mods earlier in the load order will modify the result before other mods do; this becomes more relevant later.

There are two different behaviours during the merging of CSVs.

Append: Starsector appends a row from your CSV to the data it has loaded so far.
Replace: Starsector uses a row you provided to replace the prior data it loaded from its own CSV.

Which of those behaviours is picked depends on the id column of your row. If the id column in one of your rows exactly matches that of an entry in Starsector's own CSV, then it will replace Starsector's own data for that row. Otherwise it will use the Append behaviour. Below is a simplified example based on the hull_mods.csv file.

Whose Data?	name	id	cost_frigate	cost_destroyer
Starsector's hullmods.csv	Accelerated Shields	advancedshieldemitter	3	6
Your Mod's hullmods.csv	Accelerated Shields (Better)	advancedshieldemitter	1	3
What is actually loaded ingame	Accelerated Shields (Better)	advancedshieldemitter	1	3

By using the same id as the existing Accelerated Shields hullmod, we were able to rename the hullmod and decrease its ordnance point cost for frigates and destroyers. Do keep in mind, however, that when you replace a row, you replace the entirety of it, not just a few targeted values.

This process doesn't happen in isolation though. In reality, many mods will be merging the same file. And it can happen that two mods may want to replace the same row. In those cases, the mod with the later load order wins out. You can imagine it like this: Starsector loads the row -> Mod1 replaces the row -> Mod2, which loaded later than Mod1, replaces Mod1's replacement.

Cases like those are rare, but should be kept in mind. If you discover that your replacement doesn't work, it may be because another mod is trying to do the same replacement and wins out over your replacement.

JSON Merging and Replacing

Many of the same rules regarding file location/name and load order in .csv files apply to JSONs as well, but there are some additional rules that you need to be aware of.

As you have learned on the Data and file types page, JSON files are made up of key and value pairs. Keys are treated like id's were in the CSV section above. If your JSON has a matching key to that of the target you are planning to modify, you will replace its value. But in reality it is slightly more complicated. This is because the behaviour depends on the data type being targeted.

Simple values, like text, numerical values (i.e. 10) and truth values (i.e. true) will all be replaced if your key matches that of an existing key. Lists have a different behaviour: your values will simply be appended to the rest of the list.

If the key of a list contains the word "color" and the list is 4 elements long, then it will be replaced instead of appended. This allows replacing color values in the game.

You can overwrite the append behaviour of Lists by making the first element in your replacement "core_clearArray". This will clear the existing list, and then append your new values. For example, "myList":["core_clearArray", 1, 2, 3] will delete the existing content in myList and add 1, 2, 3 to it. This behaviour, however, is currently broken, and will be fixed in version 0.98.5a.

Objects will do a recursive merge. This means that when you match the key of an object, your object will combine all of its values by following the same rules for lists and simple values as stated above.

Asset Replacing

Ìmage files like .png and .jpg, but also sound files like .ogg always replace the existing file with the same name and folder location. Same as with CSV and JSON files, the later mod in the load order wins out.

"replace" field in mod_info.json

Your mod_info.json file has an optional field called "replace". This field can be used to completely overwrite an existing CSV or JSON file. If, for example, you want to prevent Starsector from loading any of its original hullmods, and want to replace them with just your own, you could do it like this.

"replace":[
  "data/hullmods/hull_mods.csv",
],

In 99% of cases you should not require this. This is a utility reserved for feature overhauls and total conversions, which can easily introduce game-breaking behaviour if used without care.