User:Aliser/Paths (modding) - Draft

A «path» is a string of characters used to reference either a file or a specific location within a .rules file (called a «node»).

It is similar to the paths used in an operating system, but it has its own distinct features and differences to fit the game's needs.

Path composition

A path is composed of:

Reference modifier

Syntax: &

Turns a string path into a reference path.

A string path is a path represented by a string with double quotes on both sides, e.g. "<ships/terran/terran.rules>/Terran/Parts" or "icon.png".

It can point to a particular file, or, if it's a .rules file, somewhere inside it (like to a particular component).

A reference path is a path that starts with & and has no double quotes on both sides, e.g. &~/Part/Components/EmpAbsorber/AbsorbsResourceDrain or &<super_armor/super_armor.rules>/Part.

It can similarly point to the things the same way how string path does, but it also has additional «modifiers» that change the origin of the path, e.g. to the top of the current .rules file or even to one of the nodes that the current node is inherited from.

The context of where to use either of those paths differs.

For instance, mod.rules actions target specific data fields or .rules files using string paths, whereas the regular .rules files might use string paths to reference certain files or reference paths to reference other nodes.

You can learn more about the format of paths used in different places by checking out other pages in the Modding section.

String path segment

Syntax (as part of a path): path/to/file, <path/to/file>

A path segment that points to a particular file: .rules file or any other.

Present when a path points to a file in any way (just the file or as a part of a bigger path, that goes into a .rules file). This excludes paths that reference something in the current .rules file, e.g. &~/Part/Components/EmpAbsorber/AbsorbsResourceDrain.

If a path goes inside a .rules file, the string path segment acquires angle brackets <...> to both of its sides. This is needed to distinguish between the file path and a .rules inside path.

String path segment examples

Path	String path segment
"ships/Arclight.ship.png"	ships/Arclight.ship.png
"<ships/terran/terran.rules>/Terran/Parts"	<ships/terran/terran.rules>
"./Data/ships/common/light_blob.png"	./Data/ships/common/light_blob.png
&~/Part/Components/EmpAbsorber/AbsorbsResourceDrain	None - it points to the top of the current file.
&/COMMON_EFFECTS/PowerDeliver	COMMON_EFFECTS/PowerDeliver
&<doodads/doodads.rules>/Doodads	doodads/doodads.rules

.rules path segment

A path segment that goes into the .rules file.

Prefix

Syntax:

• ./
• ../, ../../, etc.
• ~/
• ^/

A prefix, identifying a «root», from where a path starts.

./ references the Cosmoteer directory

The Cosmoteer directory is usually located here (see more): C:\Program Files (x86)\Steam\steamapps\common\Cosmoteer

Example

Starting from the game's Data folder, the path to the 1x1 armor icon would be ./Data/ships/terran/armor/icon.png.

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.

../ references a file/folder/node one level up

It's also can be combined with itself to move multiple levels up: ../../.

Example

For instance, if we wanted to set a BatteryStorage component capacity to the part's own health, you would do it like this: MaxResources = &../../MaxHealth:

• ../../ goes up 2 levels, so from the component's context → all components context → part context.

• MaxHealth references the field named MaxHealth in the part itself.

For instance, if we wanted to set a BatteryStorage component capacity to the part's own health, you would do it like this: MaxResources = &../../MaxHealth

• ../../ goes up 2 levels, so from the component's context → all components context → part context.
• MaxHealth references a field named MaxHealth in the part itself.

~/ references the «top» of the current .rules file

Example

Another way to write the path in the previous example would be MaxResources = &~/Part/MaxHealth:

• ~/ starts the path at the top of the current file.
• Part refers to the node called Part (which is a part definition for all parts) at the top the current file.
• MaxHealth refers to the MaxHealth field inside the Part node.

^/ references the nodes that the current node was inherited from

Since a node can inherit from multiple nodes, all the nodes that the current node is inherited from are in a list.
So, if you were to have NodeA, which contains NodeB, and NodeA inherits from NodeC and NodeD, NodeB can reference data from the nodes the parent NodeA inherits from using ^/0/, where the number represents which inherited node is being referred to.
^/0/ would refer to data inherited from NodeC, while ^/1/ would refer to data inherited from NodeD.  
This can be useful when you want to add onto inherited data instead of overwriting it.

Example

One example of this (although it doesn't do much) is a Part's ReceivableBuffs field.

For instance, for the large thruster it looks like this: ReceivableBuffs : ^/0/ReceivableBuffs [Engine].
* ^/0/ refers to the a single part that the current part is inherited from, <../base_part_terran.rules>/Part
* ReceivableBuffs refers to the same field in that part.
* [Engine] is just a list of values for this field. If the part, that the current part is inherited from, would have any values in this field, they would added to what is defined here. Currently, the <../base_part_terran.rules>/Part has an empty ReceivableBuffs.

   if no prefix is specified, the «root» is assumed to be the current file location

This means the current location within the .rules file itself, within the current node.

Examples

Example and Source	Description
Part : <../base_part_terran.rules>/Part @ ships\terran\armor\armor.rules	The armor Part definition, first line. The Part is inherited from the base part terran part, located one level above the current folder (the ../ syntax): <../base_part_terran.rules>/Part
ContinuingPenetrationResistance = &InitialPenetrationResistance @ ships\terran\armor\armor.rules	In the same armor Part definition we have the current file location reference. The ContinuingPenetrationResistance fields references InitialPenetrationResistance field which is located on the same level.
EditorIcon { Texture { File = "icon.png" SampleMode = Linear } Size = [32, 32] } @ ships\terran\armor\armor.rules

Limitations

• A path cannot be absolute, meaning all paths are relative to either the specified root, or to the current node/file.

Tip

You can use ../ prefix to go up a level (or multiple levels, if you combine them).

This is useful when you are trying to reference something within some other mod,

so you first go up a level from your mod.rules to a mods folder (containing your mod), then go the desired mod folder from there.

• A reference path cannot be used where a string path is used, and vise versa.

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.
• &/ refers to the top of Data/cosmoteer.rules

Based on the original text courtesy of Captain Redstone on the Cosmoteer official Discord.