Module Classes


class wl.Game

Child of: wl.bases.EditorGameBase

The root class to access the game internals. Use wl.Game() to access the properties, e.g.:

current_speed = wl.Game().real_Speed

(RO) The speed that the current game is running at in ms. For example, for game speed = 2x, this returns 2000.


(RO) The absolute time elapsed since the game was started in milliseconds.


(RW) Sets the desired speed of the game in ms per real second, so a speed of 2000 means the game runs at 2x speed. Note that this will not work in network games as expected.


(RW) Disable or enable saving. When you show off UI features in a tutorial or scenario, you have to disallow saving because UI elements can not be saved and therefore reloading a game saved in the meantime would crash the game.


(RO) The player number of the interactive player, or 0 for spectator


(RO) The gametime at which the game was last saved.


(RO) One string out of "undefined", "singleplayer", "netclient", "nethost", "replay", describing the type of game that is played.


(RO) The (unlocalized) name of the game’s win condition, e.g. "Endless Game". For scenarios this is "Scenario".


(RO) The difficulty level of the current scenario. Values range from 1 to the number of levels specified in the campaign’s configuration in campaigns.lua. By convention higher values mean more difficult. Throws an error if used outside of a scenario.

launch_coroutine(func[, when = now])

Hands a Lua coroutine object over to widelands for execution. The object must have been created via coroutine.create(). The coroutine is expected to coroutine.yield() at regular intervals with the absolute game time on which the function should be awakened again. You should also have a look at core.cr.

  • func (thread) – coroutine object to run

  • when (integer) – absolute time when this coroutine should run




Requests a savegame. Note that the actual save will be performed later, and that you have no control over any error that may happen by then currently.


name (string) – name of save game, as if entered in the save dialog. If this game already exists, it will be silently overwritten. If empty, the autosave name will be used.




class wl.Editor

Child of: wl.bases.EditorGameBase

The Editor object; it is the correspondence of the wl.Game that is used in a Game. Use ẁl.Editor() to access the properties.

World and Tribe Descriptions

class wl.Descriptions

This offers access to the objects in the Widelands world and allows to add new objects. On how to build the world and adding new objects to it, see Scripts for World and Scripts for Tribes.


Returns a list of all the immovables that are available.

(RO) a list of ImmovableDescription objects


Returns a list of all the terrains that are available.

(RO) a list of TerrainDescription objects


Returns a list of all the workers that are available.

(RO) a list of WorkerDescription objects

modify_unit(type, name, property …, value …)

This powerful function can be used to modify almost every property of every object description.

Currently, support is implemented only for a limited number of properties. Contact the Widelands Development Team if you need access to a property that can not be modified by this function yet.

This function is meant to be used only by add-ons of the tribes and world categories from their postload.lua. Do not use it in scenario scripts, add-ons of other types, or the debug console.

  • type (string) – The object type to modify. See below for a list of valid values.

  • name (string) – The name of the item to modify.

  • property… (string) – The property to modify. A property is specified as a sequence of one or more strings. See below for a list of all supported property descriptors.

  • value… – The values for the property. The number and types of the expected values depend on the property being modified (see below).

Supported types and properties are:


Property descriptor




amount (int)



terrain_name (string)



experience (int)



worker_name (string)


"programs" "set"

program_name (string), actions_table (table)



building_name (string)


"input" "add_ware"

ware_name (string), amount (int)


"input" "modify_ware"

ware_name (string), new_amount (int)


"input" "remove_ware"

ware_name (string)


"input" "add_worker"

worker_name (string), amount (int)


"input" "modify_worker"

worker_name (string), new_amount (int)


"input" "remove_worker"

worker_name (string)


"programs" "set"

program_name (string), program_table (table)



ware_name (string), menu_column (int), target_quan (int or nil), preciousness (int), helptexts (table)



worker_name (string), menu_column (int), target_quan (int or nil), preciousness (int or nil), helptexts (table)



building_name (string), helptexts (table)



immovable_name (string), helptexts (table)

Example to add a new worker to an existing tribe; the worker will be appended to the 2nd column in the workers displays (stock menu, warehouse window, economy options), and have no target quantity or preciousness:

descriptions:modify_unit("tribe", "frisians", "add_worker", "frisians_salter",
      2, nil, nil, { helptexts = { purpose =
         _("The salter washes salt from the shores of the sea.")

Example to add a new input ware to a building and ensure that the programs use it:

-- Add the input
descriptions:modify_unit("productionsite", "frisians_smokery",
      "input", "add_ware", "salt", 6)

-- Overwrite the two predefined programs with new ones
descriptions:modify_unit("productionsite", "frisians_smokery", "programs", "set",
      "smoke_fish", { descname = _("smoking fish"), actions = {
            "return=skipped unless economy needs smoked_fish",
            "consume=fish:2 salt log",
            "animate=working duration:30s",
descriptions:modify_unit("productionsite", "frisians_smokery", "programs", "set",
      "smoke_meat", { descname = _("smoking meat"), actions = {
            "return=skipped when site has fish:2 and economy needs smoked_fish",
            "return=skipped unless economy needs smoked_meat",
            "consume=meat:2 salt log",
            "animate=working duration:30s",

-- The main program needs to be overwritten as well – otherwise
-- the new program definitions will not not applied!
descriptions:modify_unit("productionsite", "frisians_smokery", "programs", "set",
      "main", { descname = _("working"), actions = {