Immovable Programs

Immovables can have programs that will be executed by the game engine. Programs are required to allow workers to interact with an immovable (e.g. a tree will need a “fall” program to allow woodcutters to remove the tree).

It is not mandatory for immovables to define programs. If the immovable defines a program named main, this program will be started as the main program on creation. Immovables without such a program will simply display their ‘idle’ animation indefinitely.

Note

The main program used to be called program, which has been deprecated.

Programs are defined as Lua tables. Each program must be declared as a subtable in the immovable’s Lua table called programs and have a unique table key. The entries in a program’s subtable are the actions to execute, like this:

programs = {
   main = {
      "animate=idle 1550000",
      "transform=deadtree4 chance:5.13%",
      "seed=alder_summer_sapling proximity:70.31%",
   },
   fall = {
      "transform=",
   },
},

For general information about the format, see Syntax.

Available actions are:

animate

Runs an animation. See animate.

playsound

Plays a sound effect. See playsound.

script

Runs a Lua function. See script.

transform

transform=[bob:]\<name\> [chance:\<percent\>]
Parameters:

  • <name> (string) – The name of the map object to turn into. If the bob:<name> flag is given, the transformation target is a bob; otherwise it is an immovable. Currently, only ships are supported as bobs.

  • chance (percent) – The Percent chance that the transformation will be performed. The game will generate a random number and the transformation will be performed if and only if this number is less than chance. If chance:<percent> is omitted, the transformation will always be performed.

Deletes this immovable and instantly replaces it with a different immovable or a bob. If chance is specified, there’s a probability that the transformation will be skipped. When the transformation succeeds, no further program steps will be executed, because this object will be gone. Example:

main = {
    "animate=idle duration:25m50s",
    "transform=deadtree3 chance:9.37%",
    -- This line will be skipped if the removal succeeds
    "seed=spruce_summer_sapling proximity:78.12%",
 },

grow

grow=\<immovable_name\>
Parameters:

<immovable_name> (string) – The name of the immovable to turn into.

Deletes the immovable (preventing subsequent program steps from being called) and replaces it with an immovable of the given name. The chance that this program step succeeds depends on how well this immovable’s terrain affinity matches the terrains it is growing on. If the growth fails, the next program step is triggered. This command may be used only for immovables with a terrain affinity. Example:

main = {
   "animate=idle duration:57s500ms",
   "remove=chance:8.2%",
   "grow=alder_summer_pole",
},

remove

remove=[chance:\<percent\>]
Parameters:

chance (percent) – The Percent chance that the immovable will be removed. The game will generate a random number and the immovable will be removed if and only if this number is less than chance. If chance:<percent> is omitted, the immovable will always be removed.

Remove this immovable. If chance is specified, there’s a probability that the removal will be skipped. When the removal succeeds, no further program steps will be executed, because this object will be gone. Examples:

main = {
   "animate=idle duration:55s",
   "remove=chance:16.41%",
   "grow=spruce_summer_pole", -- This line will be skipped if the removal succeeds
},
fall = {
   "remove=", -- This object will always be removed when 'fall' is called
},

seed

seed=\<immovable_name\> proximity:\<percent\>
Parameters:

  • <immovable_name> (string) – The name of the immovable to create.

  • proximity (percent) – The radius within which the immovable will seed is not limited and is determined by repeatedly generating a random number and comparing it with the proximity Percent chance until the comparison fails. The higher this number, the closer the new immovable will be seeded.

Finds a random location nearby and creates a new immovable with the given name there with a chance depending on this immovable’s terrain affinity. The chance that such a location will be searched for in a higher radius is influenced by the proximity parameter. Note that this program step will consider only one random location, and it will only seed there if the terrain is well suited. This command may be used only for immovables with a terrain affinity. Example:

main = {
    "animate=idle duration:20s",
    "remove=chance:11.72%",
    -- Select a location with a chance of 19.53% in the base radius,
    -- then expand the radius and try again with a chance of 19.53%.
    -- Repeat until a location has been selected, then plant an
    -- 'umbrella_red_wasteland_sapling' if the terrain affinity check
    -- for this immovable succeeds at the selected location.
    "seed=umbrella_red_wasteland_sapling proximity:19.53%",
    "animate=idle duration:20s",
    "remove=chance:7.81%",
    "grow=umbrella_red_wasteland_old",
},

construct

construct=\<animation_name\> duration:\<duration\> decay_after:\<duration\>
Parameters:

  • animation_name (string) – The animation to display while the immovable is being constructed.

  • duration (duration) – The Duration of each construction step for visualising the construction progress. Used only in drawing code.

  • decay_after (duration) – When no construction material has been delivered for this Duration, the construction progress starts to gradually reverse.

Blocks execution of subsequent programs until enough wares have been delivered to this immovable by a worker. The wares to deliver are specified in the immovable’s buildcost table which is mandatory for immovables using the construct command. If no wares are being delivered for a while, the progress gradually starts to reverse, increasing the number of wares left to deliver. If the immovable keeps decaying, it will eventually be removed. Example:

main = {
   "construct=idle duration:5s decay_after:3m30s",
   "transform=bob:frisians_ship",
}