Actions

From Cosmoteer Wiki
< ModdingModding/Actions
Jump to navigation Jump to search
CalloutIconWarning.png
Work in Progress
This page is currently WORK IN PROGRESS. Some things may be missing.

Feel free to contribute and don't worry about perfection - other editors can make corrections if necessary. Just get creating!

Actions are the primary way to modify the game.

They are little commands that modify the game's .rules files after they have been loaded into memory. The actual .rules files in the Data folder are never modified, allowing for switching mods on and off without a risk of breaking the vanilla .rules.


First, the game loads the vanilla .rules files normally. Then, for every mod that is enabled, that mod's actions are run on top of the loaded .rules files (following the mod loading order), modifying them in memory.

Using this technique, mods can make practically any change to the game that could be made by modifying the .rules files directly, but without actually having to make any permanent changes to the game files.


There are a small number of .rules files that can't be modified using actions. The most prominent example is the language string files (such as en.rules) which are modified using the StringsFolder setting.

CalloutIconTip.png
Tip
Be sure to first learn about:
  • Modding basics: mod locations, example mod, .rules syntax.
  • Paths — to understand to which files the action relate to.

Action: Add — adds a new data fields

You can add You cannot add To where you can add it to?
  • Single value: a number/string/bool/math expression
  • List []
  • Group {}
  • .rules file (using references &)
 .rules file (using string path)
  • List []

Only if Name is provided:

  • Group {}
  • .rules file (using string path)

Syntax

{
    // [required: YES] 
    // The name of this action.
    Action = Add

    // [required: YES] 
    // A string path to a .rules file (without "&" modifier) 
    // or somewhere inside of it where to add the data.
    //
    // Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
    // Following it must be a path to a particular node inside the .rules file
    // (which can be omited if you adding something to the .rules file itself and not a particular node).
    AddTo = "<builtin_ships/builtins.rules>/Ships"

    // [required: no] 
    // If "true", the "AddTo" will be created if it doesn't exist instead of giving an error.
    // Default is "false".
    CreateIfNotExisting = false

    // [required: no] 
    // If "true", the action will do nothing if the "AddTo" doesn't exist instead of giving an error.
    // Default is "false".
    IgnoreIfNotExisting = false

    // [required: no]
    // If "true", the action will do nothing if the "Name" already exists instead of giving an error.
    // Default is "false".
    OnlyIfNotExisting = false

    // [required: depends, see below]  
    // The name of the field to add.
    // Only required when adding to .rules files (without going in) or groups {}.
    Name = "Density"

    // [required: YES] 
    // The data to add. 
    // Can be of any type: single values, lists [], groups {}, references &.
    // 
    // Note that below are only the examples of possible values - 
    // the action can't actually have multiple fields with the same name.
    
    // Example: group {}
    ToAdd
    {
        File = "ships/Arclight.ship.png"
        Faction = cabal
        Tags = [combat]
        Tier = 3
        Difficulty = 2
    }
    
    // Example: single value
    ToAdd = 3.0
    
    // Example: list []
    ToAdd
    [
        1,
        2,
        3
    ]

    // Example: reference &
    ToAdd = &<super_armor/super_armor.rules>/Part
}

Examples

Adding a new ship to spawnable Career mode ships

In the example_mod, adds a new ship called «Arclight».

The ship is added to the list of built-in ships (which enables it to spawn naturally): AddTo = "<builtin_ships/builtins.rules>/Ships". The .rules file is located under Cosmoteer/Data/builtin_ships → builtins.rules.

Both CreateIfNotExisting = false and IgnoreIfNotExisting = false ensure that the ship will be added only to an existing list, and otherwise throw an error (e.g. if the file name changes):

  • CreateIfNotExisting would create the AddTo path (the node Ships inside the builtins.rules) if set to true. It's set to false, meaning the action will not add anything if AddTo path doesn't exist.
  • IgnoreIfNotExisting would skip this action (if set to true) instead of giving an error if AddTo path doesn't exist. It's set to false, meaning the action will give an error if AddTo path doesn't exist and if CreateIfNotExisting is set to false.


The data to add is in ToAdd. You can look into any built-in ship (inside the builtin_ships folder) to gather some understanding about what these fields mean and values they can be assigned.

.rules file/node location: Cosmoteer/Standard Mods/example_mod/mod.rules
{
	Action = Add
	AddTo = "<builtin_ships/builtins.rules>/Ships"
	CreateIfNotExisting = false
	IgnoreIfNotExisting = false
	ToAdd
	{
		File = "ships/Arclight.ship.png"
		Faction = cabal
		Tags = [combat]
		Tier = 3
		Difficulty = 2 // (Note: Difficulty is currently unused but may be used in the future, so you should still specify a difficulty between 1-3.)
	}
}

Action: AddMany — adds multiple new data fields

You can add You cannot add To where you can add it to?
  • Single values: a number/string/bool/math expression
  • Lists []
  • Groups {}
  • .rules files (using references &)
 .rules files (using string path) List []

Syntax

{
	// [required: YES] 
	// The name of this action.
	Action = AddMany

	// [required: YES] 
	// A string path to a .rules file or somewhere inside of it where to add the data.
	//
	// Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
	// Following it, must be a path to a list node [] inside that .rules file.
	AddTo = "<ships/terran/terran.rules>/Terran/Parts"

	// [required: no] 
	// If "true", the "AddTo" will be created if it doesn't exist instead of giving an error.
	// Default is "false".
	CreateIfNotExisting = false

	// [required: no] 
	// If "true", the action will do nothing if the "AddTo" doesn't exist instead of giving an error.
	// Default is "false".
	IgnoreIfNotExisting = false

	// [required: YES] 
	// The data to add. 
	// Must be a list []. Values can be of a particular type 
	// (single values, lists [], groups {}, references &) or 
	// mixed (e.g. [a single value, a group]).
	// Note that below are only the examples of possible values - 
	// the action can't actually have multiple fields with the same name.
		
	// Example: file references (using "&" modifier)
	ToAdd = [
		&<super_armor/super_armor.rules>/Part,
		&<super_armor_2x1/super_armor_2x1.rules>/Part
	]
	
	// Example: single values
	ManyToAdd = [
		3.0
	]
	// Example: list []
	ToAdd
	[
		[2, 3],
		[5, [ Foo: "bar" ]],
	]
	// Example: group {}
	ToAdd
	[
		{
			File = "ships/Arclight.ship.png"
			Faction = cabal
			Tags = [combat]
			Tier = 3
			Difficulty = 2 
		},
		{
			File = "ships/SuperCoolShip.ship.png"
			Faction = monolith
			Tags = [combat]
			Tier = 7
			Difficulty = 3 
		},
	]
	
	// Example: mixed
	ToAdd = [
		3.0,
		[2, 3],
			{
			File = "ships/Arclight.ship.png"
			Faction = cabal
			Tags = [combat]
			Tier = 3
			Difficulty = 2 
		},
		&<super_armor/super_armor.rules>/Part,
	]
}

Action: AddBase — adds a new reference to the inheritance list of a data field

Presumably, this is the Action to use when you want to make something inherit from something else.[clarification needed][1]

You can add You cannot add To where you can add it to?
  • List []
  • Group {}
  • .rules file (using reference &)
  • Single value: a number/string/bool/math expression
  • .rules file (using string path)
  • List []
  • Group {}

Syntax

{
	// [required: YES] 
	// The name of this action.
	Action = AddBase

	// [required: YES] 
	//  A string path to a list [] or a group {} to the inheritance list of which to add.
	//
	// Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
	// Following it, must be a path to a list [] or a group {} node inside that .rules file.
	AddBaseTo = "<ships/terran/control_room_small/control_room_small.rules>/Part/Components"

	// [required: no] 
	// If "true", the action will do nothing if the "AddBaseTo" doesn't exist instead of giving an error.
	// Default is "false".
	IgnoreIfNotExisting = false

	// [required: YES] 
	// The data to add. 
	// Must be either a file reference, a group {} or a list [].
    // 	
	// Note that below are only the examples of possible values - 
	// the action can't actually have multiple fields with the same name.

	// Example: file reference (using "&" modifier)
	BaseToAdd = &<control_room_small_components.rules>
	
	// Example: list []
	BaseToAdd
	[
		1,
		"hello",
	]
	
	// Example: group {}
	BaseToAdd
	{
		File = "ships/Arclight.ship.png"
		Faction = cabal
		Tags = [combat]
		Tier = 3
		Difficulty = 2 
	}
}

Example mods

Action: Replace — replaces a data field

[clarification needed][2]

You can replace You cannot replace With what you can replace it with?
  • Single value: a number/string/bool/math expression
  • List []
  • Group {}
  • .rules file (using reference&)
  • .rules file (using string path)
  • Single value: a number/string/bool/math expression
  • List []
  • Group {}
  • .rules file (using reference &)

Syntax

{
    // [required: YES] 
    // The name of this action.
    Action = Replace

    // [required: YES] 
    // A string path to somewhere inside a .rules file (without "&" modifier).
    //
    // Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
    // Following it must be a path to a particular node inside that .rules file.
    Replace = "<modes/career/career.rules>/EconDifficultyLevels/1/StartingMoney"

    // [required: no] 
    // If "true", the action will do nothing if the "Replace" doesn't exist instead of giving an error.
    // Default is "false".
    IgnoreIfNotExisting = false

    // [required: YES] 
    // The data to replace the data field in "Replace" with. 
    // Can be of any type: single value, list [], group {} or a reference &.
    // 
    // Note that below are only the examples of possible values - 
    // the action can't actually have multiple fields with the same name.
    // Example: single value
    With = 12345.0
    
    // Example: list []
    With
    [
        1,
        2,
        3
    ]
    
    // Example: group {}
    With
    {
        File = "ships/Arclight.ship.png"
        Faction = cabal
        Tags = [combat]
        Tier = 3
        Difficulty = 2
    }
    
    // Example: reference &
    With = &<super_armor/super_armor.rules>/Part/MaxHealth
}

Action: Overrides — modifies group {} data field

You can modify You cannot modify With what you can modify it with?
  • Group {}
  • Single value: a number/string/bool/math expression.
  • List []
  • .rules file (using reference&)
  • .rules file (using string path)
  • Single value: a number/string/bool/math expression
  • List []
  • Group {}
  • .rules file (using reference &)

Syntax

{
    // [required: YES] 
    // The name of this action.
    Action = Overrides

    // [required: YES] 
	// A string path to a .rules file or somewhere inside of it where to add the data.
	//
	// Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
	// Following it, must be a path to a group node {} inside that .rules file.
    OverrideIn = "<modes/career/career.rules>/EconDifficultyLevels/1"
    
	// [required: no] 
	// If "true", the "OverrideIn" will be created if it doesn't exist instead of giving an error.
	// Default is "false".
	CreateIfNotExisting = false

    // [required: no] 
    // If "true", the action will do nothing if the "OverrideIn" doesn't exist instead of giving an error.
    // Default is "false".
    IgnoreIfNotExisting = false

    // [required: YES] 
    // The data fields to modify in "OverrideIn", along with their new values.
    // Must be a group {}.
    // 
    // Note that below are only the examples of possible values - 
    // the action can't actually have multiple fields with the same name.
    // Example: single value
    Overrides = {
        // string
		MoneyRewardFactor = "300%"
		FameRewardFactor = "300%"
		
        // number
		StartingMoney = 100000
		
        // whatever else		
    }
}

Action: Remove — removes a data field

You can remove You cannot remove
  • Single value: a number/string/bool/math expression.
  • List []
  • Group {}
  • .rules file (using reference&)

[^^ clarification needed][3]

  • .rules file (using string path)

Syntax

{
    // [required: YES] 
    // The name of this action.
    Action = Remove

    // [required: YES] 
    // A string path to somewhere inside a .rules file (without "&" modifier).
    //
    // Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
    // Following it must be a path to a particular node inside that .rules file.
    Remove = "<ships/terran/reactor_small/reactor_small.rules>/Part/Components/DestroyedEffects/HitEffects"

    // [required: no] 
    // If "true", the action will do nothing if the "Remove" doesn't exist instead of giving an error.
    // Default is "false".
    IgnoreIfNotExisting = false
}

Action: RemoveMany — removes multiple data fields

You can remove You cannot remove
  • Single values: a number/string/bool/math expression.
  • Lists []
  • Groups {}
  • .rules files (using reference&)

[^^ clarification needed][4]

  • .rules files (using string path)

Syntax

{
    // [required: YES] 
    // The name of this action.
    Action = RemoveMany

    // [required: no] 
    // If "true", the action will do nothing if the "Remove" doesn't exist instead of giving an error.
    // Default is "false".
    IgnoreIfNotExisting = false
    
    // [required: YES] 
    // A list of string paths all leading to somewhere inside a .rules file (without "&" modifier).
    //
    // Value in <...> must be a string path to a .rules file, relative to the Cosmoteer's Data directory.
    // Following it must be a path to a particular node inside that .rules file.
    RemoveMany
    [
		"<ships/terran/cannon_med/cannon_med.rules>/Part/Components/CommandConsumer"
		"<ships/terran/cannon_large/cannon_large.rules>/Part/Components/CommandConsumer"
		"<ships/terran/railgun_loader/railgun_loader.rules>/Part/Components/CommandConsumer"
		"<ships/terran/railgun_accelerator/railgun_accelerator.rules>/Part/Components/CommandConsumer"
		"<ships/terran/railgun_launcher/railgun_launcher.rules>/Part/Components/CommandConsumer"
	]
}

Actions targeting other mods

It is possible to modify what other mods do or contain via your own mod. That's one way to interact with content that you don't integrate into your own mod (for legal reasons for example).

However it's not possible to directly modify what the Actions in another mod do[5]. You can still remove anything an Action added, for example.

  1. ↑ clarification needed: what happens if the action adds to an inheritance list of a node that doesn't inherit from anything?
  2. ↑ clarification needed: can a file be replaced?
  3. ↑ ^^ clarification needed: does this doesn't work?
  4. ↑ ^^ clarification needed: does this doesn't work?
  5. ↑ https://discord.com/channels/314103695568666625/368422988753928193/1228049113405456456
Retrieved from "https://cosmoteer.wiki.gg/index.php?title=Modding/Actions&oldid=11657"