Paths (modding)

How they work

A "path" is like the address of something, in computer terms.

At their core, modding paths work similarly to normal operating system file paths, though a few additions to the system have to be made to prevent mods (or the game itself) from needing to be installed at an exact location.

In a nutshell, paths contain a list of folder names that the game needs to follow to find a specific file.
For instance, starting from the game's Data folder, the path to the 1x1 armor's icon would be ./Data/ships/terran/armor/icon.png (I'll explain the ./ later).
Note that any path including or inside of a .rules file must start with &, and it's good practice to encase any other file paths in quotation marks ("").

In Cosmoteer

Unlike operating system file paths, paths in Cosmoteer allow you to reference specific parts of a file.
This follows a similar structure as the rest of the path, with the names of folders being replaced by the names of nodes (basically anything with a {}).
Importantly, when pathing to any part of a .rules file, the path must start with & (as previously mentioned), and everything in the "regular" path must be encased in angle brackets (<>), while the part of the path that references individual components of a file must be outside of those angle brackets.

As an example, if we wanted to change 1x1 armor tiles' icon, we'd first need to path to the rules file with ./Data/ships/terran/armor/armor.rules. Since we're pathing to part of a .rules file we need to prepend &, and encase actual folders/files in the path in <>, giving us &<./Data/ships/terran/armor/armor.rules>.

Looking inside of the file, it's sometimes easier to figure out the desired path "backwards"; the value we're looking for is File, which is inside of Texture{}, which is inside of EditorIcon{}, which is finally inside of Part{}. Putting that all together we get Part/EditorIcon/Texture/File, and appending that to our "original" path gives a final answer of &<./Data/ships/terran/armor/armor.rules>/Part/EditorIcon/Texture/File. This may all seem really complicated, but with a bit of practice it should become pretty intuitive.

Lists

Sometimes within .rules files, you'll encounter square brackets ([]) instead of curly brackets ({}); nodes with square brackets are referred to as "lists", and contain any number of unnamed nodes. To reference an unnamed node inside of a list, all you need to do is pretend each node in the list is named by number, starting at 0.

As an example, open the armor 1x1 rules file, then look at Part/Components/Graphics/Floor; referencing the first sprite would be DamageLevels/0/File, the second sprite would be DamageLevels/1/File, and the third DamageLevels/2/File.

Pathing prefixes

Now, there are a lot of different ways that paths can start (we will call those "prefixes"), which is where the system gets both versatile and confusing.

Below is every prefix with a brief description of what it does.
If none of the below prefixes are given, the game will either start at the current file or node's position, depending on if <>s are used or not.

For instance if you wanted to set a part's Density to its Health, you can simply say Density = &Health, since they're on the same "level" in the file structure. Using Density = &<Health> would instead start looking for actual files since <>s are used, with the default position being the file where this path is contained in. If you wanted to reference a non-.rules file, simply remove the & and <>, and Density = "Health.png" now tries to reference an image instead.

List of prefixes

• ./ tells the game to start at the top level of the game's data files. That's why all paths that reference data files start with ./Data/; simply using Data/ would look for a folder called Data relative to the current file's location.
  • NOTE: the second line of all mod.rules Actions already starts at &./Data/, and should be given quotes as good practice; pathing to the terran parts folder would be <ships/terran> instead of &<./Data/ships/terran>.

• ../ tells the game to look a level up from the current node or file's position. For instance, if we wanted to set a BatteryStorage{}'s capacity to the part's own health, you could say MaxResources = &../../MaxHealth; the path starts at MaxResources, moves up to BatteryStorage's level, then Components' level, then looks for a value called MaxHealth.

• ~/ starts at the top of the current rules file. Another way to write the path in the previous example would be MaxResources = &~/Part/MaxHealth; the path starts at the very top of the file, opens Parts{}, then looks for a value called Maxhealth

• ^/ is uh, complicated. You won't need this in 99% of applications though, so don't worry if this doesn't immediately make sense. Lets say you have NodeA{}, which contains NodeB{}; if NodeA inherits from NodeC{} and NodeD{}, NodeB can reference data from the parent NodeA{}'s inherits using ^/0/, where the number represents which inherit is being referred to. ^/0/ would refer to data inherited from NodeC{}, while ^/1/ would refer to data inherited from NodeD{}. This is only really useful when you want to add onto inherited non-list data instead of overwriting it.

• Some paths will only be found by searching File = because they don't deal with .rules files. These are often assets. They also need to be valid.

Original text courtesy of Captain Redstone on the Cosmoteer official Discord.