Programs ======== .. _map_object_programs: Many map objects have special programs that define their behavior. You can describe these programs in their ``init.lua`` files, in the ``programs`` table. * :ref:`map_object_programs_syntax` * :ref:`map_object_programs_datatypes` * :ref:`map_object_programs_actions` Map objects that can have programs are: .. toctree:: :maxdepth: 1 Immovables Production Sites Workers Critters all run the same built-in program, so you don't need to define any programs for them. .. _map_object_programs_syntax: Syntax ------ Map object programs are put in a Lua table, like this: .. code-block:: lua programs = { main = { "action1=parameter1:value1 parameter2:value2", "action2=value1", }, program_name2 = { "action3", "action4=value1 value2 value3", }, program_name3 = { "action5=value1 value2 parameter:value3", } }, For productionsites, there is a nested ``actions`` table, so that we can give them a descname for the tooltips: .. code-block:: lua programs = { main = { -- TRANSLATORS: Completed/Skipped/Did not start doing something because ... descname = _("doing something"), actions = { "call=program_name2", "call=program_name3", } ... } } * Named parameters of the form ``parameter:value`` can be given in any order, but we recommend using the order from the documentation for consistency. It will make your code easier to read. * Values without parameter name need to be given in the correct order. * Some actions combine both named and unnamed values, see ``action5`` in our example. If there is a program called ``"main"``, this is the default program. For :ref:`productionsites `, having a main program is mandatory. For :ref:`immovables `, having a main program is optional, because their programs can also be triggered by a productionsite or by a worker. :ref:`Workers ` have no default program, because their individual programs are always called from their production site. .. _map_object_programs_datatypes: Data Types ---------- Some numerical action parameters use units of measure to clarify their meaning. .. _map_object_programs_datatypes_duration: Duration ^^^^^^^^ Temporal duration is specified with an accompanying unit. Valid units are: * ``m`` (minutes) * ``s`` (seconds) * ``ms`` (milliseconds) You can combine these units in descending order as you please. Examples: * ``4m`` * ``12s`` * ``500ms`` * ``4m12s`` * ``12s500ms`` * ``4m500ms`` * ``4m12s500ms`` * ``1m500s100000ms`` will work too, but is not recommended (unreadable) .. _map_object_programs_datatypes_percent: Percent ^^^^^^^ A percent value. Valid unit is: * ``%`` (percent) Maximum value is ``100%``. Examples: * ``25%`` * ``25.1%`` * ``25.13%`` .. _map_object_programs_actions: Actions ------- The actions documented in this section are available to all map object types. .. _map_object_programs_animate: animate ^^^^^^^ .. function:: animate=\ [duration:\] Switch to new animation and pause program execution for the given duration. :arg string name: The name of the animation to be played. :arg duration duration: The time :ref:`map_object_programs_datatypes_duration` for which the program will wait before continuing on to the next action. If omitted, the program will continue to the next step immediately. Example for a worker: .. code-block:: lua plantvine = { "findspace=size:any radius:1", "walk=coords", "animate=dig duration:2s500ms", -- Play a digging animation for 2.5 seconds. "plant=attrib:seed_grapes", "animate=planting duration:3s", -- Play a planting animation for 3 seconds. "return" }, The animate action will trigger a new animation, then wait for the specified duration before moving on to the next action in the program. The animation will continue playing and loop around until the program ends or another ``animate=`` action is called. The given duration does not have to equal the length of the animation. When the program ends, the map object will switch back to the default ``idle`` animation. Some actions also have an animation associated with them that will be played instead, e.g. ``"walk=coords"`` will play the walking animation for the direction the worker is walking in. .. _map_object_programs_playsound: playsound ^^^^^^^^^^ .. function:: playsound=\ priority:<\percent\> \[allow_multiple\] :arg string sound_dir/sound_name: The directory (folder) that the sound files are in, relative to the data directory, followed by the name of the particular sound to play. There can be multiple sound files to select from at random, e.g. for `sound/farm/scythe`, we can have `sound/farm/scythe_00.ogg`, `sound/farm/scythe_01.ogg` ... :arg percent priority: The priority to give this sound, in :ref:`map_object_programs_datatypes_percent`. Maximum priority is ``100%``. :arg allow_multiple: When this parameter is given, the sound can be played by different map objects at the same time. Trigger a sound effect. Whether the sound effect is actually played is determined by the sound handler. Examples: .. code-block:: lua -- Worker harvest = { "findobject=attrib:ripe_wheat radius:2", "walk=object", -- Almost certainly play a swishy harvesting sound "playsound=sound/farm/scythe priority:95%", "animate=harvesting duration:10s", "callobject=harvest", "animate=gathering duration:4s", "createware=wheat", "return" } -- Production site produce_ax = { -- TRANSLATORS: Completed/Skipped/Did not start forging an ax because ... descname = _("forging an ax"), actions = { "return=skipped unless economy needs ax", "consume=coal iron", "sleep=duration:26s", -- Play a banging sound 50% of the time. -- Other buildings can also play this sound at the same time. "playsound=sound/smiths/smith priority:50% allow_multiple", "animate=working duration:22s", -- Play a sharpening sound 50% of the time, -- but not if another building is already playing it right now. "playsound=sound/smiths/sharpening priority:90%", "sleep=duration:9s", "produce=ax" } }