.. _tribes_worker_programs:

Worker Programs
===============

Worker programs are defined in the ``programs`` subtable specified in the worker's
:ref:`lua_tribes_workers_common`. Each worker program is a Lua table in itself and defined as a
series of command strings. Commands can also have parameters, which are separated from each other by
a blank space. These parameters can also have values, which are separated from the parameter name by
a colon (:). Finally, programs can call other programs. The table looks like this::

   programs = {
      program_name1 = {
         "program_name2",
         "program_name3",
      }
      program_name2 = {
         "action1=parameter1:value1 parameter2:value2",
         "action2=parameter1",
      },
      program_name3 = {
         "action3",
         "action4=parameter1 parameter2 parameter3",
      }
   },


For general information about the format, see :ref:`map_object_programs_syntax`.

Available actions are:

- `createware`_
- `mine`_
- `breed`_
- `findobject`_
- `findspace`_
- `walk`_
- `animate`_
- `return`_
- `callobject`_
- `plant`_
- `createbob`_
- `removeobject`_
- `repeatsearch`_
- `findresources`_
- `scout`_
- `playsound`_
- `construct`_
- `terraform`_

createware
^^^^^^^^^^
.. function:: createware=\<ware_name\>

   :arg string ware_name: The ware type to create, e.g. ``wheat``.

   The worker will create and carry a ware of the given type. Example::

      harvest = {
         "findobject=attrib:ripe_wheat radius:2",
         "walk=object",
         "playsound=sound/farm/scythe 220",
         "animate=harvesting duration:10s",
         "callobject=harvest",
         "animate=gathering duration:4s",
         "createware=wheat", -- Create 1 wheat and start carrying it
         "return"
      },

mine
^^^^
.. function:: mine=\<resource_name\> radius:\<number\>

   :arg string resource_name: The map resource to mine, e.g. ``fish``.

   :arg int radius: After the worker has found a spot, the radius that is scanned for decreasing the
      map resource, e.g. ``1``.

   Mine on the current coordinates that the worker has walked to for resources decrease.
   Example::

      fish = {
         "findspace=size:any radius:7 resource:resource_fish",
         "walk=coords",
         "playsound=sound/fisher/fisher_throw_net 192",
         "mine=resource_fish radius:1", -- Remove a fish in an area of 1
         "animate=fishing duration:3s",
         "playsound=sound/fisher/fisher_pull_net 192",
         "createware=fish",
         "return"
      },

breed
^^^^^
.. function:: breed=\<resource_name\> radius:\<number\>

   :arg string resource_name: The map resource to breed, e.g. ``fish``.

   :arg int radius: After the worker has found a spot, the radius that is scanned for increasing the
      map resource, e.g. ``1``.

   Breed a resource on the current coordinates that the worker has walked to for
   resources increase. Example::

      breed = {
         "findspace=size:any radius:7 breed resource:resource_fish",
         "walk=coords",
         "animate=freeing duration:3s",
         "breed=resource_fish radius:1", -- Add a fish in an area of 1
         "return"
      },

findobject
^^^^^^^^^^
.. function:: findobject=radius:\<distance\> [type:\<map_object_type\>] [attrib:\<attribute\>]
   [no_notify]

   :arg int radius: Search for an object within the given radius around the worker.
   :arg string type: The type of map object to search for. Defaults to ``immovable``.
   :arg string attrib: The attribute that the map object should possess.
   :arg empty no_notify: Do not send a message to the player if this step fails.

   Find and select an object based on a number of predicates, which can be specified
   in arbitrary order. The object can then be used in other commands like ``walk``
   or ``callobject``. Examples::

      cut_granite = {
         "findobject=attrib:rocks radius:6", -- Find rocks on the map within a radius of 6 from your
         building
         "walk=object", -- Now walk to those rocks
         "playsound=sound/atlanteans/cutting/stonecutter 192",
         "animate=hacking duration:12s",
         "callobject=shrink",
         "createware=granite",
         "return"
      },

      hunt = {
         "findobject=type:bob radius:13 attrib:eatable", -- Find an eatable bob (animal) within a
         radius of 13 from your building
         "walk=object", -- Walk to where the animal is
         "animate=idle duration:1s500ms",
         "removeobject",
         "createware=meat",
         "return"
      },

findspace
^^^^^^^^^
.. function:: findspace=size:\<plot\> radius:\<distance\> [breed] [resource:\<name\>]
   [avoid:\<immovable_attribute\>] [saplingsearches:\<number\>] [space] [ferry]
   [terraform:\<category\>] [no_notify]

   :arg string size: The size or building plot type of the free space.
      The possible values are:

      * ``any``: Any size will do.
      * ``build``: Any building plot.
      * ``small``: Small building plots only.
      * ``medium``: Medium building plots only.
      * ``big``: Big building plots only.
      * ``mine``: Mining plots only.
      * ``port``: Port spaces only.
      * ``swim``: Anything on the coast.

   :arg int radius: Search for map fields within the given radius around the worker.

   :arg empty breed: Used in front of ``resource`` only: Also accept fields where the
      resource has been depleted. Use this when looking for a place for breeding.

   :arg string resource: A resource to search for. This is mainly intended for
      fishers and suchlike, for non-detectable resources and default resources.

   :arg string avoid: A field containing an immovable that has this attribute will
      not be used.

   :arg int saplingsearches: The higher the number, the better the accuracy
      for finding a better spot for immovables that have terrain affinity, e.g. trees.

   :arg empty space: Find only fields that are walkable in such a way that all
      neighbors are also walkable (an exception is made if one of the neighboring
      fields is owned by this worker's location).

   :arg empty ferry: Find only fields reachable by a ferry.

   :arg string terraform: Find only nodes where at least one adjacent triangle has
      terrain that can be enhanced.

   :arg empty no_notify: Do not send a message to the player if this step fails.

   Find a map field based on a number of predicates.
   The field can then be used in other commands like ``walk``. Examples::

      breed = {
         -- Find any field that can have fish in it for adding a fish to it below
         "findspace=size:any radius:7 breed resource:resource_fish",
         "walk=coords",
         "animate=freeing duration:3s",
         "breed=resource_fish 1",
         "return"
      },

      plant = {
         -- Don't get in the way of the farmer's crops when planting trees. Retry 8 times.
         "findspace=size:any radius:5 avoid:field saplingsearches:8",
         "walk=coords",
         "animate=dig duration:2s",
         "animate=planting duration:1s",
         "plant=attrib:tree_sapling",
         "animate=water duration:2s",
         "return"
      },

      plant = {
         -- The farmer will want to walk to this field again later for harvesting his crop
         "findspace=size:any radius:2 space",
         "walk=coords",
         "animate=planting duration:4s",
         "plant=attrib:seed_wheat",
         "animate=planting duration:4s",
         "return",
      },

walk
^^^^
.. function:: walk=\<destination_type\>

   :arg string destination_type: Defines where to walk to. Possible destinations are:

      * ``object``: Walk to a previously found and selected object.
      * ``coords``: Walk to a previously found and selected field/coordinate.
      * ``object-or-coords``: Walk to a previously found and selected object if present;
        otherwise to previously found and selected field/coordinate.
      * ``ne|e|se|sw|w|nw``: New in version 1.2. Orders the worker to move one field in the
        specified direction. The worker program exits with "fail" if the movement is not possible.

   Walk to a previously selected destination. Examples::

      plant = {
         "findspace=size:any radius:2",
         "walk=coords", -- Walk to the space found by the command above
         "animate=planting duration:4s",
         "plant=attrib:seed_blackroot",
         "animate=planting duration:4s",
         "return"
      },

      harvest = {
         "findobject=attrib:ripe_blackroot radius:2",
         "walk object", -- Walk to the blackroot field found by the command above
         "animate=harvesting duration:10s",
         "callobject=harvest",
         "animate=gathering duration:2s",
         "createware=blackroot",
         "return"
      },

      buildship = {
         "walk=object-or-coords", -- Walk to coordinates from 1. or to object from 2.
         -- 2. This will create an object for us if we don't have one yet
         "plant=attrib:atlanteans_shipconstruction unless object",
         "playsound=sound/sawmill/sawmill 230",
         "animate=work duration:500ms",
         "construct", -- 1. This will find a space for us if no object has been planted yet
         "animate=work duration:5s",
         "return"
      },

animate
^^^^^^^
Runs an animation. See :ref:`map_object_programs_animate`.

return
^^^^^^
.. function:: return

   Return home and then drop any ware we're carrying onto our building's flag. Example::

      scout = {
         "scout=15 75000",
         "return" -- Go home
      }

callobject
^^^^^^^^^^^
.. function:: callobject=\<program_name\>

   :arg string program_name: The name of the program to be executed.

   Cause the currently selected object to execute its given program. Example::

      harvest = {
         "findobject=attrib:tree radius:10",
         "walk=object",
         "playsound=sound/woodcutting/fast_woodcutting 250",
         "animate=hacking duration:10s",
         "playsound=sound/woodcutting/tree-falling 130",
         "callobject=fall", -- Cause the tree to fall
         "animate=idle duration:2s",
         "createware=log",
         "return"
      }

   See also :ref:`immovable_programs`.

plant
^^^^^
.. function:: plant attrib:\<attribute\> [attrib:\<attribute\> ...] [unless object]

   :arg string attrib\:\<attribute\>: Select at random any immovable
      that has this attribute.

   :arg empty unless object: Do not plant the immovable if it already exists at
      the current position.

   Plant one of the given immovables on the current position, taking into account
   the fertility of the area. Examples::

      plant = {
         "findspace=size:any radius:5 avoid:field",
         "walk=coords",
         "animate=dig duration:2s",
         "animate=planting duration:1s",
         "plant=attrib:tree_sapling", -- Plant any random sapling tree
         "animate=water duration:2s",
         "return"
      },

      plant = {
         "findspace=size:any radius:2 space",
         "walk=coords",
         "animate=planting duration:4s",
         -- Plant the tiny field immovable that the worker's tribe knows about
         "plant=attrib:seed_wheat",
         "animate=planting duration:4s",
         "return",
      },

      buildship = {
         "walk=object-or-coords",
         -- Only create a shipconstruction if we don't already have one
         "plant=attrib:barbarians_shipconstruction unless object",
         "playsound=sound/sawmill/sawmill 230",
         "animate=work duration:500ms",
         "construct",
         "animate=work duration:5s",
         "return"
      }

createbob
^^^^^^^^^
.. function:: createbob=\<bob_name\> [\<bob_name\> ...]

   :arg string bob_name: The bob type to add to the selection. Specify as many bob
      types as you want.

   Adds a bob (an animal or a worker, e.g. a deer or a ferry) to the map at the worker's current
   location. Randomly select from the list of ``bob_name``. Examples::

      release = {
         "findspace=size:any radius:3",
         "walk=coords",
         "animate=releasein duration:2s",
         "createbob=wildboar stag sheep", -- Release a wildboar, stag or sheep into the wild
         "animate=releaseout duration:2s",
         "return"
      },

      buildferry = {
         "findspace=size:swim radius:5",
         "walk=coords",
         "animate=work duration:10s",
         "createbob=frisians_ferry",
         "return"
      }

terraform
^^^^^^^^^
.. function:: terraform=\<category\>

   Turns the terrain of one of the triangles around the current node into its
   enhancement terrain. Example::

      terraform = {
         "findspace=size:any radius:6 terraform:amazons",
         "walk=coords",
         "animate=dig duration:2s",
         "terraform=amazons",
         "return"
      }

removeobject
^^^^^^^^^^^^
.. function:: removeobject

   Remove the currently selected object. Example::

      hunt = {
         "findobject=type:bob radius:13 attrib:eatable", -- Select an object to remove
         "walk=object",
         "animate=idle duration:1s",
         -- The selected eatable map object has been hunted, so remove it from the map
         "removeobject",
         "createware=meat",
         "return"
      }

repeatsearch
^^^^^^^^^^^^
.. function:: repeatsearch=\<program_name\> repetitions:\<number\> radius:\<number\>

   :arg string program_name: The name of the program to repeatedly call from this program.

   :arg int repetitions: The number of times that the worker will move to a
      different spot on the map to execute ``program_name``. Used by geologists.

   :arg int radius: The radius of map fields for the worker not to stray from.

   Walk around the starting point randomly within a certain radius, and execute
   your ``program_name`` for some of the fields. Example::

      expedition = {
         "repeatsearch=search repetitions:15 radius:5"
      },

findresources
^^^^^^^^^^^^^
.. function:: findresources

   Check the current position for map resources (e.g. coal or water), and plant
   a marker object when possible. Example::

      search = {
         "animate=hacking duration:5s",
         "animate=idle duration:2s",
         "playsound=sound/hammering/geologist_hammer 192",
         "animate=hacking duration:3s",
         -- Plant a resource marker at the current location, according to what has been found.
         "findresources"
      }

scout
^^^^^
.. function:: scout=radius:\<number\> duration:\<duration\>

   :arg int radius: The radius of map fields for the scout to explore.

   :arg duration duration: The time :ref:`map_object_programs_datatypes_duration` that the scout
      will spend scouting.

   Sends a scout out to run around scouting the area. Example::

      scout = {
         "scout=radius:15 duration:1m15s",
         "return"
      },

playsound
^^^^^^^^^^
Plays a sound effect. See :ref:`map_object_programs_playsound`.

construct
^^^^^^^^^
.. function:: construct

   Give the ware currently held by the worker to the immovable object for construction.
   This is used in ship building. Example::

      buildship = {
         "walk=object-or-coords", -- Walk to coordinates from 1. or to object from 2.
         -- 2. This will create an object for us if we don't have one yet
         "plant=attrib:atlanteans_shipconstruction unless object",
         "playsound=sound/sawmill/sawmill 230",
         "animate=work duration:5s",
         -- 1. Add the current ware to the shipconstruction. This will find a space for us if no
         -- shipconstruction object has been planted yet
         "construct",
         "animate=work duration:5s",
         "return"
      },