Modding troubleshooting

Ship hull [mod_ship_id] from ship_data.csv not found in store

• There is a ship ID in ship_data.csv that cannot find a match in any .ship files in the hullId field, so it cannot find the ship hull. It finds it based solely on the hullId field and not the filename. It is case sensitive.

Fatal: Index: 0, Size: 0

• Make sure your IDE is set to compile the Java classes in JDK 7 format.

Fatal: Index: 1, Size: 1

• Usually means attempted to use an array in a fatally unsupported manner. The output is the size of the array. The two classic causes of this is trying to put too much data into a fixed size array that is too small or the game engine expecting an array size different to what it found. This can generate IndexOutOfBoundsException errors. For example a single barrel gun with two values for turret angle offset, so the engine looks for the second, non-existent barrel.

Errors from commented out lines

• Starsector's JSON parser has been modified to allow java style comments. It has some quirks and in particular it is not recommended to use JSON comments for issue isolation identification, as it will not behave as expected in 100% of situations

Effects scaling differently on different computers

• Scripts are run per frame and frame rate is variable depending on specific setup. If a calculation is performed on itself, scaling itself per frame, every frame then it will have different effect scaling over time, potentially dramatically so. The method CombatEngineAPI.getElapsedInLastFrame() combined with checking CombatEngineAPI.isPaused() provides the time since last frame which is useful to avoid this frame rate scaling issue

Mod ships don't appear in fleets/markets

• In addition to listing the hulls/tags in the .faction file, you also need to specify the variants in data/world/factions/default_ship_roles.json.

Mod weapons not used in autofit despite being in a variant OK

• The variant appears with the weapons OK but trying to autofit to that variant causes it to not use those guns. The autofit uses the tags section of Weapon data.csv so if tags are missing, such as kinetic3 or pd4, then it will not use those guns

Linux compatibility

• Consistent case sensitivity is very important. There are quite a number of places where a case mismatch will work on other OS' but will break Linux. Pay attention to your case sensitivity!

"???" invalid characters
Or my CSV file cannot be read

• Use UTF-8 (not UTF-8 BOM) encoding for any and all text. It is very easy to accidentally use incompatible special characters otherwise.

File access and reflection are not allowed to scripts

• There are a few different possible causes of this.
• Loggers can't be instance variables, only static variables. Using a non-static logger can cause this. (Any save you make with this issue is permanently "poisoned", so start a new save to test the fix)
• Any attempt to to call the Java I/O methods directly or use reflection will naturally fail.
  • If you need to write data to an external file and then read it, use SettingsAPI.writeTextFileToCommon(String filename, String data) and SettingsAPI.readTextFileFromCommon(String filename).
    • These methods load/save text data from the <installdir>/saves/common/ folder.

Works with one but weirdness when there is more than one of it

• Check STATIC keyword usage. Things going weird when there are more than one of something is a classic symptom of a STATIC variable or method being shared between multiple instances.

ArrayIndexOutOfBoundsException: 20887 in TextureLoader

• Starsector uses 8-bit colour graphics. Loading in an image with higher colour precision can potentially be out of expected bounds. Fix by modifying the image colour precision; this is done in GIMP with Image -> Precision -> 8bit

Mod does not appear in mod list in the launcher

• Very frequently caused by a malformed mod_info.json file. Rarely but possible caused by an critical issue in a file the mod_info.json is referencing. Rarely but possible caused by issues steaming from undefined behaviour of having two mods in the list with the same unique mod ID.

At least two versions out of date. Last verified for version 0.9. Please refer to Version History and update this page.

---

Return to Modding