# 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 = {
"command1=parameter1:value1 parameter2:value2",
"command2=parameter1",
},
program_name3 = {
"command3",
"command4=parameter1 parameter2 parameter3",
}
},


The available commands are:

## 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 = {
"walk=object",
"playsound=sound/farm/scythe 220",
"animate=harvesting 10000",
"callobject=harvest",
"animate=gathering 4000",
"createware=wheat", -- Create 1 wheat and start carrying it
"return"
},


## mine¶

mine=<resource_name> <area>
Parameters: resource_name (string) – The map resource to mine, e.g. fish. area (int) – 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 = {
"walk=coords",
"playsound=sound/fisher/fisher_throw_net 192",
"mine=fish 1", -- Remove a fish in an area of 1
"animate=fishing 3000",
"playsound=sound/fisher/fisher_pull_net 192",
"createware=fish",
"return"
},


## breed¶

breed=<resource_name> <area>
Parameters: resource_name (string) – The map resource to breed, e.g. fish. area (int) – 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:fish",
"walk=coords",
"animate=freeing 3000",
"breed=fish 1", -- Add a fish in an area of 1
"return"
},


## findobject¶

findobject=radius:<distance> [type:<map_object_type>] [attrib:<attribute>]
Parameters: radius (int) – Search for an object within the given radius around the worker. type (string) – The type of map object to search for. Defaults to immovable. attrib (string) – The attribute that the map object should possess.

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 12000",
"callobject=shrink",
"createware=granite",
"return"
},

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


## findspace¶

findspace=size:<plot> radius:<distance> [breed] [resource:<name>]
[avoid:<immovable_attribute>] [saplingsearches:<number>] [space]
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. 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).

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:fish",
"walk=coords",
"animate=freeing 3000",
"breed=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 2000",
"animate=planting 1000",
"plant=attrib:tree_sapling",
"animate=water 2000",
"return"
},

plant = {
-- The farmer will want to walk to this field again later for harvesting his crop
"walk=coords",
"animate=planting 4000",
"plant=attrib:seed_wheat",
"animate=planting 4000",
"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.

Walk to a previously selected destination. Examples:

plant = {
"walk=coords", -- Walk to the space found by the command above
"animate=planting 4000",
"plant=attrib:seed_blackroot",
"animate=planting 4000",
"return"
},

harvest = {
"walk object", -- Walk to the blackroot field found by the command above
"animate=harvesting 10000",
"callobject=harvest",
"animate=gathering 2000",
"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:shipconstruction unless object",
"playsound=sound/sawmill/sawmill 230",
"animate=work 500",
"construct", -- 1. This will find a space for us if no object has been planted yet
"animate=work 5000",
"return"
},


## animate¶

animate=<name> <duration>
Parameters: name (string) – The name of the animation. duration (int) – The time in milliseconds for which the animation will be played.

Play the given animation for the given duration. Example:

plantvine = {
"walk=coords",
"animate=dig 2000", -- Play a digging animation for 2 seconds.
"plant=attrib:seed_grapes",
"animate=planting 3000", -- Play a planting animation for 3 seconds.
"return"
},


## 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 = {
"walk=object",
"playsound=sound/woodcutting/fast_woodcutting 250",
"animate=hacking 10000",
"playsound=sound/woodcutting/tree-falling 130",
"callobject=fall", -- Cause the tree to fall
"animate=idle 2000",
"createware=log",
"return"
}


## plant¶

plant attrib:<attribute> [attrib:<attribute> ...] [unless object]
Parameters: attrib: (string) – Select at random any world immovable or immovable of the worker’s tribe that has this attribute. unless object (empty) – 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 = {
"walk=coords",
"animate=dig 2000",
"animate=planting 1000",
"plant=attrib:tree_sapling", -- Plant any random sapling tree
"animate=water 2000",
"return"
},

plant = {
"walk=coords",
"animate=planting 4000",
-- Plant the tiny field immovable that the worker's tribe knows about
"plant=attrib:seed_wheat",
"animate=planting 4000",
"return",
},

buildship = {
"walk=object-or-coords",
-- Only create a shipconstruction if we don't already have one
"plant=attrib:shipconstruction unless object",
"playsound=sound/sawmill/sawmill 230",
"animate=work 500",
"construct",
"animate=work 5000",
"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 (usually an animal) to the map at the worker’s current location. Randomly select from the list of bob_name. Example:

release = {
"walk=coords",
"animate=releasein 2000",
"createbob=wildboar stag sheep", -- Release a wildboar, stag or sheep into the wild
"animate=releaseout 2000",
"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 1000",
-- The selected eatable map object has been hunted, so remove it from the map
"removeobject",
"createware=meat",
"return"
}


## repeatsearch¶

repeatsearch=<repetitions> <radius> <program_name>
Parameters: 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=15 5 search"
},


## 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 5000",
"animate=idle 2000",
"playsound=sound/hammering/geologist_hammer 192",
"animate=hacking 3000",
-- Plant a resource marker at the current location, according to what has been found.
"findresources"
}


## scout¶

scout=<radius> <time>
Parameters: radius (int) – The radius of map fields for the scout to explore. time (int) – The time in milliseconds that the scout will spend scouting.

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

scout = {
"scout=15 75000", -- Scout within a radius of 15 for 75 seconds
"return"
},


## playsound¶

playsound=<sound_dir/sound_name> [priority]
Parameters: sound_dir/sound_name (string) – 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 … priority (int) – The priority to give this sound. Maximum priority is 255.

Play a sound effect. Example:

harvest = {
"walk=object",
"playsound=sound/farm/scythe 220", -- Almost certainly play a swishy harvesting sound
"animate=harvesting 10000",
"callobject=harvest",
"animate=gathering 4000",
"createware=wheat",
"return"
}


## 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:shipconstruction unless object",
"playsound=sound/sawmill/sawmill 230",
"animate=work 500",
-- 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 5000",
"return"
},