.rules file format

This page describes the syntax/format of the .rules files contents.

Tip

You can read more on what the .rules files are in the .rules files Modding Basics section.

Basic syntax

Type	Syntax	Example usage	Explanation
Single Values			Single values are usually set by using "Name = Value"
Arrays	[]		Arrays are enclosed in [] tags. As an example, all of the actions you do in a mod.rules file is enclosed in a [] pair, so it's an array (a.k.a. "list").
Groups	{}		Groups are enclosed in {} tags. A group can contain single values, other groups, other arrays, or a mix.
Comments	// or /* */		Comment lines begin with // or you can comment blocks out by enclosing them in /* and */

Other syntax

You can copy a component or value without repeating all the code (a bad practice called "code duplication"), by using any syntax from this list instead :

• BatteryStorage2 = &BatteryStorage1
• BatteryStorage3 : &BatteryStorage1 {}
• BatteryStorage4 : &BatteryStorage1 { MaxResources = 10 } *This is how you change a single value and keep the rest identical.
• BatteryStorage5 = &<some_file.rules>/Part/Components/BatteryStorage
• BatteryStorage6 : &<some_file.rules>/Part/Components/BatteryStorage { MaxResources = 10 } *This is how you change a single value and keep the rest identical.

Of course it works with other component types.

It is also possible to use math on variables, Cosmoteer uses math syntax compatible with https://mathparser.org/mxparser-math-collection/. One caveat, when referencing other variables in math, any whole reference must be in parenthesis, like so:

var1 = 10
var2 = 2
result = (&var1) / (&var2) + ceil(17/2) // will equal to 14

Practical use

New modders

The first thing you should do if you haven't, is play around with the built-in mods that ship with the game.

They're all made by the game's developer and are guaranteed bug-free.

To do so just open the game's mod manager on the bottom left, turn one (or more) of them on, and either click the "Restart Game" prompt or close and reopen it manually.

Once you've experienced their effects, back in the mod manager, right-click them and choose "Show Folder" to see their files.

Tip

You will need a code editor. I you don't have one, Notepad++ and Visual Studio Code are completely free.

They contain a lot of comments that will help you become familiar with the whole thing, especially "Example Mod".

The very basics of making a mod can be simply copying the Example Mod folder, and renaming + editing everything in your copy until it does what you want it to.

As you get more familiar, you can use a mod that has no comments as your "copy source" to save time on deleting the comments you don't need.

Once that's done, you zip the folder, open the mod manager again and install that zip with the small button in the top right. Congrats, you're modding now!

Other modders

One of the first things to realize to avoid crashes when trying to mod .rules files, is that the syntax of any added part will be different from the syntax of any base game part.

Usually, it is good to use a solid reference to make something new. But if, say, you just copy-paste the base game's 1x1 armor block into your mod, you will immediately get a crash.

Why? Well here are common reasons that apply to any part you want to add.

The paths

First of all, base game parts use a lot of shortcuts in paths contained in their .rules files.

Mods are not authorized to use these shortcuts, and the crash (when there is one) will tell you that the game :

• "Cannot find node at path ........ "
• "Cannot read non-array ........... "
• "...... Value must not be null"
• etc.

In most of these cases, you haven't really made a mistake, in the sense that if your code was in a file from the base game, it would have worked.

However, your code is not there, and will have to apply the following practices to save time on debugging.

The part's path

When creating a new Part, it needs to inherit from base game part. In base game parts it looks like this, and is usually the very first line in any part's .rules file:

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

Of course, new modded parts are not in same directory as base game parts, so this path has to be changed to full path otherwise game will crash (for more on this topic, see Avoiding mod crashes) with a message that file was not found:

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

These are the same addresses if you start from the game's "terran" folder, but your mod is not there.

Warning

This isn't sufficient to succeed, you also need to add the part via your mod.rules file.

Requirement to use full paths instead of relative ones is true for inheriting from base game parts, but you can (and should, where applicable) use relative paths like <../file.rules> within your own mod.

You might see this inherit with and without & and both forms work and are equivalent. Walt explained:

> In inheritance, there's no difference. Personally I prefer without the & simply because I consider it redundant, but there's no harm in having it.

(See paths for more details).

Inheritance and references

Both of those work, because in inheritance having & is optional:

Part : <./Data/ships/terran/base_part_terran.rules>/Part
       <../cables.rules>/Part
{
}

and

Part : &<./Data/ships/terran/base_part_terran.rules>/Part
       &<../cables.rules>/Part
{
}

However this does not work correctly:

# BatteryStorage = <../cables.rules>/Part/Components/BatteryStorage

It must have & to work. Referencing values of other blocks/variables requires & :

BatteryStorage = &<../cables.rules>/Part/Components/BatteryStorage

Omitting & here works fine because in inheritance it is optional:

BatteryStorage : <../cables.rules>/Part/Components/BatteryStorage
{
    MaxResources = 10
}

See also

Advanced coding :

• SerializeAttribute

Back to Modding.