Workers are created in a warehouse or recruited by a building. Most workers will work in buildings, while special worker types will act as carriers or soldiers.

Widelands knows about the following worker types:

Common Worker Properties

Workers are defined with Lua functions called new_<worker_type>_type{table}. The contents of table depend on the type of worker that you are defining. The common properties shared by all workers are:

msgctxt: The context that Gettext will use to disambiguate the translations for strings in this table.

name: A string containing the internal name of this worker.

descname: The translatable display name. Use pgettext with the msgctxt above to fetch the string.

helptext_script: The full path to the helptexts.lua script for this worker.

icon: The full path to the menu icon for this worker.


The size of the radius that the worker sees.


Optional. A table with the wares and workers used by warehouses to create this worker, containing warename - amount pairs, e.g.:

buildcost = { atlanteans_carrier = 1, hammer = 1 }

Optional. An int defining the default target quantity for the worker’s tribe’s economy. Use this if the worker is produced by a production site rather than the warehouses. For example, default_target_quantity = 10


Optional. The amount of experience that the worker needs to gather in order to be transformend into a higher worker type. If becomes is defined, this needs to be set as well.


Optional. The name of the higher worker type that this worker will transform to after gaining enough experience. If experience is defined, this needs to be set as well.


A table containing all animations for this worker. Workers have an “idle” animation. They also have directional animations called “walk” and “walkload” which are defined with the help of add_walking_animations(), plus additional Animations used in their worker programs. The “idle” and “walk” animations are mandatory.


Optional. If the worker leaves the building to do his work, the Worker Programs that define which type of space or resource the worker has to find on the map in order to do his work, and what that work is, including any animations and sounds played.


Optional. The x, y coordinates for adjusting the placement of the ware being carried. The default value is {0, 15}. Increase x to shift the ware to the left and y to shift it upwards. For example:

ware_hotspot = { -2, 13 },

Optional. A list of hints for the AI. Can contain the following optional entries:

preciousness: How precious this worker is to each tribe. For example, { atlanteans = 0, empire = 1 }. You can use this for workers that are recruited.

Help Texts

Each worker has a helptexts.lua script, which is located in the same directory as its init.lua script. The function in this file returns a text that is used for the worker by the Tribal Encyclopedia.


Returns a localized string with the helptext for this worker type. It needs to be fetched by pgettext, using <tribename>_worker as the message context. Example:

function worker_helptext()
   -- TRANSLATORS: Helptext for a worker: Armorsmith
   return pgettext("atlanteans_worker", "Produces armor for the soldiers.")