Avoiding mod crashes

This page aims to be a practical guide for preventing/stopping your mods from crashing.

Following these steps to the letter should get your mod to work. Feel free to add any missing steps or knowledge about fixing these errors!

Tip

Make sure to first read Modding Basics.

Preventing mod crashes

This section should allow you to make a mod without it crashing even once. If that doesn't work, see the other section.

Crashes caused by Actions

First things first! Any mod is governed by its mod.rules file, which uses Actions. This section deals with that.

Modifying the base game

Check: Actions

Actions are in your mod.rules file only.

1. Triple-check every path. Almost all mod-installing and loading crashes come from them.
   • Your AddTo (or equivalent) path should be within "" .
   • It also should start from inside the game's Data folder. That's because it has a hidden &<./Data/ at the start of it.
2. Make sure every Action is in its own {}, which is itself in the Actions list ( within the [] ).
3. Make sure you didn't make an Add action and then input a list of things to add, like it's an AddMany action.
4. Make sure your Replace actions target something that exists.
5. Make sure your Overrides actions are creating if not existing, if you're using them as Add actions.
6. Anything that is a list [] that you try to replace with something that isn't a list will crash the game. Put it within [] with the exact same syntax, and additonal , as needed (each item in the list must be separated by this). If that doesn't work, give up on that modification, it might be a forbidden data field (that's rare).

Note that if you replaced any path, you might also need to replace paths that referenced it.

For example, the Stats section at the end of part .rules files references a lot of paths ; if one is missing it will crash the game.

The quick and dirty solution is to just comment out everything inside that block. The cost is, no stats will be displayed when you press Alt in game. It's best to avoid this in the long run.

Crashes caused by Parts

Adding a new part

That still requires you to modify base game files because you need to "add" your part to the game's collection. So apply the section above as well.

In all cases (copied or not), make sure the first line in your part is :

Part : <./Data/ships/terran/base_part_terran.rules>/Part

instead of this line , which will crash (for parts copied from the base game) :

Part : <../base_part_terran.rules>/Part

Copying an existing part

For each part and projectile you've copied, before you even modify them for your mod (so you can start from something that works), and after you did that :

1. Open every .rules file in it 1 by 1, including in every subfolder (like "particles").
2. In each of them, Find (hotkey : "Ctrl+F") every path. In the Find search box, write these terms 1 by 1 to find them all : & , ./ , ~/ and File =.
   • Every time you find one, if it doesn't start with :
     1. &<./Data/,
     2. or something in all caps like COMMON_EFFECTS/ (i call those "super-paths", they're great),
     3. or the name of a folder that you copied alongside the part because it was inside that part's folder (like &<particles/ ),
   • ...then it will probably crash! That's because the game is going to wander around your mod folder looking for things that only exist in the base game's folder.
   • Fix it with what you've read in the paths page. For complex parts with dozens of ../-style paths (like missile_launcher), this could be an hour of work or more, it takes patience.
3. 90% of crash causes have just been eliminated.

Here is a little block of code just waiting to crash your game 3 times in a row if you ever copy missile_he_thruster_smoke.rules without applying these steps :

In that code, each ../../../ needs to be replaced by ./Data/ else the game crashes (unless you happened to copy it into precisely 3 levels below Data by pure luck).

That file hidden in missile_he/particles folder has another crash higher up, and the folder has 6 more files like it, by the way.

So if you do the math, trying to copy a single projectile would expose you to a good long time just crashing, fixing, and restarting. Just follow the steps instead.

If you modified any assets (sprites / visuals / sounds), don't change their file names. If you do, fix every path that referenced that file name.

If you moved any assets, same thing.

If you added any new assets, make sure every one of them is referenced by the proper path in your .rules files. Possibly your shader files too, I know nothing about shaders.

Creating it from scratch

Forget that and go back to the section above. You would need a checklist of all necessary fields and components, which right now maybe exists only on the developer's computer.

Crashes caused by Components

Did you either modify a base game part's components, or messed with a component in a part from your mod? If so, see this section.

Adding a component to a part

Make sure it has a unique name in that .rules file. For example, your "Acceleration" component does not need to be called "Acceleration", as long as it has Type = Acceleration.

If two components have the exact same name, the game will crash.

Modifying a component in a part

Make sure all the required parameters are set, and that you don't declare a parameter twice. Find (Ctrl+F) its name to make sure.

If you don't know which parameters are required ( = mandatory) :

• Search the component on this wiki. The old one doesn't list them AFAIK ;
• Or dive into the source code and examine it : if it doesn't have Optional = true, it's required. Note: It would be great to report your findings back to this wiki, so that this work can be avoided next time.

Fixing mod crashes

So, the prevention section above didn't fully work for you, and you do get crashes. Here is all the current knowledge on how to stop that.

Info

If you solved a crash in a way not listed here, let us know!

Crashes in certain game stages

I get a crash when ...

They come in many flavors, here are the most common.

When installing a mod

This isn't a real crash as it doesn't close the game. It will still give you a sort of log that you should read on the spot or screenshot.

When the game is loading to title screen

This one happens after you've "successfully" installed the mod, activated it by ticking the box green, and restarted the game to apply it.

Keep the crash log in your mod developer folder, outside your mod's files.

If you haven't yet, learn to use the log :

• Almost all of it is useless for debugging, the cause of the crash is usually in the first 20 lines, above "--- End of inner exception stack trace ---".
• It will only list 1 crash cause every time because, well, the game crashed before reading the rest of your mod. On the flip side, this means that everything in the file that caused the crash, up to the line of the crash, isn't crashing.
• Find the line describing the cause and read that line to the end. Do the same for the line right above it if it wasn't clear enough, sometimes the real path to the cause comes before.

When you've found the cause, fix it. Then either :

• Reload the game without mods, print a new zip of your mod, load that one, activate it and restart.
• Or delete your loaded mod from the game's local mods folder, restart the game in any way you want, print a new zip of your mod, load that one, activate it and restart. It can be faster this way.

When unlocking a new technology

Only happens in Career mode, when you try to unlock your new part.

Solution : Go to your tech.rules file and fix the issue (probably a wrong path or name).

When a part is destroyed

If it's a base game part with a steel cost that was reduced by a mod, or a modded part with a low steel cost, it's possible to get a crash saying roughly that "the destroyed part costed less than the structure below it".

Solution : Restore or increase the steel cost in Resources.

Randomly

This one gives no log. The game simply closes before it's done loading. If you were alt-tabbed, you might think you forgot to launch the game.

Of course that doesn't help you at all. You can go through your whole mod looking for issues, or remove content from it until it stops crashing, then you'll know the problem was in the last part you removed so you can focus on that one.

Backwards compatibility

• If you have crashing issues with a storage component that you changed, particularly when loading pre-patch saves :

"Just add the affected storage with max resources set to 0. [...] fixes a "Storage ABC not found in Part XYZ" error when it got removed" - SkipperWraith (Star wars : A Cosmos Divided modder)

To-do

• Potential name conflicts with the game/other mods.
• How to change your mod after it has been released, e.g. how to change components in such a way that they don't corrupt save games with earlier mod versions. (some info in this page though)