Automation (scripting) ru RU

Starting from version 2.0.0, the mod supports a new format of the rules: scripted rules. That is, you can set up conditions and actions via a simple scripting language. And these actions can be changed during the game!

Main Concepts of the Scripting Approach

• There are "signals" that provide string or numeric values. They are primarily used in conditions but can also be used as value parameters in actions. When something happens in the Timberborn universe, a signal can trigger. If there is a condition for this signal, it will be handled, and the action will execute (if the condition evaluates to true).
• Signals can be global (e.g., the current weather season change) or bound to a specific building (e.g., inventory changes).
• Actions are always bound to a specific building. They execute only on the same building to which the rule belongs. Different buildings have different actions. E.g. a floodgate can have action SetHeight, but it won't make any sense for an inventory.
• The conditions that depend on a signal are only checked when the signal changes its value. E.g. the weather season singnal will only trigger when the season changes. The conditions that depends on it, will not be checked on a regular basis!

When you manually create scripts, you need to understand which building they will be working on. Else, the script won't compile.

You can add your scripts via the new Rules Editor dialog. Simple scripts can be made via the visual constructor, but if you need complex conditions, you need to write them as a script.

TBD: give a screenshot here.

Script Syntax

The script follows the Lisp syntax convention. Both the condition and action are operators:

• The condition must be a logical operator.
• The action must be an operator act.

Operators

Operator is recorded as (<OperatorName> arg1 arg2 ...). It depends on the specific operator how many arguments it has. There are also restrictions to what values can the arguments have. Sometimes, another operator can be a value, but in the other cases a constant value may be required. Checkout the guide below to learn which operator needs what.

The arguments can be:

• A strings constant. They must be quoted with single quote sumbol. E.g. 'MapleSyrup'.
• A number. All numbers in the scripts are real numbers, written with a 2-digits fixed precision. That is, the value 1.50 will be recorded as 150. And value 1.555 cannot be written in the script, you has to round it up to the last two digits - 1.56. Examples:
  • Script value 100 means 1 in the game.
  • Script value 123 means 1.23 in the game.
  • Script value 1230 means 12.34 in the game.
• A signal. Signal provides either a string or a numeric value. You can use it everywhere unless it's declared the constant is required.

Condition operators

This is a set of operators that are made for the condition checking. The condition must always be a logical operator.

Binary operators

As the name assumes, there are always exactly two arguments. The first argument is always a signal, and the second can be either a constant or a signal.

Examples:

• (eq (sig Wather.Season) 'drought') - a correct condition that will evaluate to true when the weather season changes to Drought.
• (eq 'drought' (sig Wather.Season)) - an error! The first argument must be a signal.
• (eq (sig Wather.Season) (sig Wather.Season)) - an absurd example that always evalautes to true, but it illustrates that the right value is not required to be a constant.

The available binary operators are:

• eq - "is equal to".
• ne - "is not equal to".
• gt - "is greater than".
• ge - "is greater then or eqaul to".
• lt - "is less than".
• le - "is less than and equal to".

Note that for the string value type, only eq and ne make sense. The parser will throw an error of you try to use any other binary operator on a string value.

Logical operators

Only two are supported: and and or. These operators can accept any number of arguments, but not less than two. Every argument is required to be a logical operator.

• (and arg1 arg2 ...)
• (or arg1 arg2 ...)

Examples:

• (and (eq ...) (eq ...) (eq ...)). Three conditions, checked for "and" term: <arg1> and <arg2> and <arg3>.
• (and (eq ...) (or (eq ...) (eq ...))). Three conditions, checked for a mix of terms: <arg1> and (<arg2> or <arg3>).

Signals

Signal operator are written as: (sig <NameOfTheSignal> arg1 arg2 ...). At this point, there are no signals that accept arguments, but they can be added later.

• Weather.Season - returns the current weather season as a string. The possible values are: "drought", "badtide", and "temperate".
• Inventory.InputGood.<good_id> - returns the good amount stored as the buildings inventory input. The good_id part specifies which good is being checked.
• Inventory.OutputGood.<good_id> - returns the good amount stored as the buildings inventory output (the product, if it's a workshop). In the stockpiles, all goods are checked for "output".
• District.Bots - returns the number of bots in the district to which the building is connected. If the buildig is not connected to any district, then then the result is 0.
• District.Beavers - returns the number of beavers, adaults and kittens, in the district to which the building is connected. If the buildig is not connected to any district, then then the result is 0.

Usage examples:

• (eq (sig Weather.Season) 'drought'). Triggers when the weather season changes to Drought.
• (gt (sig Inventory.InputGood.Planks) 10000). Triggers when inventory gets more than 100 items of Planks (10000 in the script is 100 integer number).

Action

Action operator does the actual effect on the building. It's syntax: (act <NameOfTheAction> arg1 arg2 ...). Some actions have arguments, and some don't. The action argument can be a constant or a signal.

Examples:

• (act Floodgate.SetHeight 100). Sets floodgate height to 1 (read above to learn why 100 turns into 1).
• (act Floodgate.SetHeight (sig Signals.MyCustomSignal)). Sets floodgate height to the current value of the custom signal MyCustomSignal
  • Custom signals are not implemented as of 3/9/2025. It's a future feature.

WARNING. If you use a signal value as an argument, keep in mind that the action is bond to the condition. If the condition didn't trigger, the action will not execute. That's being said, if you use a signal as a value to the action and need the action re-executed on the signal change, this signal must aslo be a part of the condition of the rule.