.. _immovable_programs: 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: .. code-block:: lua programs = { main = { "animate=idle 1550000", "transform=deadtree4 chance:5.13%", "seed=alder_summer_sapling proximity:70.31%", }, fall = { "transform=", }, }, .. highlight:: default For general information about the format, see :ref:`map_object_programs_syntax`. Available actions are: - `animate`_ - `transform`_ - `grow`_ - `remove`_ - `seed`_ - `construct`_ - `playsound`_ animate ------- Runs an animation. See :ref:`map_object_programs_animate`. playsound --------- Plays a sound effect. See :ref:`map_object_programs_playsound`. transform --------- .. function:: transform=[bob:]\ [chance:\] :arg string \: The name of the map object to turn into. If the ``bob:`` flag is given, the transformation target is a bob; otherwise it is an immovable. Currently, only ships are supported as bobs. :arg percent chance: The :ref:`map_object_programs_datatypes_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:`` 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: .. code-block:: lua 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 ---- .. function:: grow=\ :arg 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: .. code-block:: lua main = { "animate=idle duration:57s500ms", "remove=chance:8.2%", "grow=alder_summer_pole", }, remove ------ .. function:: remove=[chance:\] :arg percent chance: The :ref:`map_object_programs_datatypes_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:`` 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: .. code-block:: lua 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 ---- .. function:: seed=\ proximity:\ :arg string \: The name of the immovable to create. :arg percent proximity: 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 :ref:`map_object_programs_datatypes_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: .. code-block:: lua 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 --------- .. function:: construct=\ duration:\ decay_after:\ :arg string animation_name: The animation to display while the immovable is being constructed. :arg duration duration: The :ref:`map_object_programs_datatypes_duration` of each construction step for visualising the construction progress. Used only in drawing code. :arg duration decay_after: When no construction material has been delivered for this :ref:`map_object_programs_datatypes_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: .. code-block:: lua main = { "construct=idle duration:5s decay_after:3m30s", "transform=bob:frisians_ship", }