Worker Programs¶

Worker programs are defined in the programs subtable specified in the worker’s Common Worker Properties. 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 Syntax.

Available actions are:

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

createware¶

createware=\<ware_name\>

Parameters:: ware_name (string) – 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¶

mine=\<resource_name\> radius:\<number\>

Parameters:

resource_name (string) – The map resource to mine, e.g. fish.
radius (int) – 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¶

breed=\<resource_name\> radius:\<number\>

Parameters:

resource_name (string) – The map resource to breed, e.g. fish.
radius (int) – 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¶

findobject=radius:\<distance\> [type:\<map_object_type\>] [attrib:\<attribute\>]

[name:\<name\>] [no_notify]

Parameters:

radius (int) – Search for an object within the given radius around the worker.
type (string) –
The type of map object to search for. The possible values are:
- immovable: Only immovables with the given name or attribute are considered.
- bob: Only critters and workers with the given name or attribute are considered.
- special: Special objects like pinned notes might be considered. (no consistency checks are implemented for this case)
Defaults to immovable.
attrib (string) – The attribute that the map object should possess.
name (string) – The internal name of the map object (since version 1.3)
no_notify (empty) – 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. Note that the predicates attrib and name are mutually exclusive. 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¶

findspace=size:\<plot\> radius:\<distance\> [breed] [resource:\<name\>]

[avoid:\<immovable_attribute\>] [saplingsearches:\<number\>] [space] [ferry]

[terraform:\<category\>] [no_notify]

Parameters:

size (string) –
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.
radius (int) – Search for map fields within the given radius around the worker.
breed (empty) – Used in front of resource only: Also accept fields where the resource has been depleted. Use this when looking for a place for breeding.
resource (string) – A resource to search for. This is mainly intended for fishers and suchlike, for non-detectable resources and default resources.
avoid (string) – A field containing an immovable that has this attribute will not be used.
saplingsearches (int) – The higher the number, the better the accuracy for finding a better spot for immovables that have terrain affinity, e.g. trees.
space (empty) – 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).
ferry (empty) – Find only fields reachable by a ferry.
terraform (string) – Find only nodes where at least one adjacent triangle has terrain that can be enhanced.
no_notify (empty) – 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¶

walk=\<destination_type\>

Parameters:

destination_type (string) –

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 animate.

return¶

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¶

callobject=\<program_name\>

Parameters:: program_name (string) – 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"
}

plant¶

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

Parameters:

attrib:<attribute> (string) – Select at random any immovable that has this attribute.
object (empty unless) – 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¶

createbob=\<bob_name\> [\<bob_name\> ...]

Parameters:: bob_name (string) – 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¶

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¶

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¶

repeatsearch=\<program_name\> repetitions:\<number\> radius:\<number\>

Parameters:

program_name (string) – The name of the program to repeatedly call from this program.
repetitions (int) – The number of times that the worker will move to a different spot on the map to execute program_name. Used by geologists.
radius (int) – 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¶

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¶

scout=radius:\<number\> duration:\<duration\>

Parameters:

radius (int) – The radius of map fields for the scout to explore.
duration (duration) – The time 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 playsound.

construct¶

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"
},

script¶

Runs a Lua function. See script.

Worker Programs¶

createware¶

mine¶

breed¶

findobject¶

findspace¶

walk¶

animate¶

return¶

callobject¶

plant¶

createbob¶

terraform¶

removeobject¶

repeatsearch¶

findresources¶

scout¶

playsound¶

construct¶

script¶

Table of Contents

Previous topic

Next topic

This Page