wl

Module Classes

Game

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

real_speed

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

In network games this is the speed resulting from the votes of the players, so it can be different from the local player’s desired_speed. Else it is the same as desired_speed.

time

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

desired_speed

(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 in network games this is the speed voted by the current player. The speed resulting from the votes is in real_speed.

allow_saving

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

interactive_player

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

value of wl.game.Player.number of the interactive player

last_save_time

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

type

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

win_condition

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

win_condition_duration

Added in version 1.2.

(RO) The time limit configured for the game’s win condition, in minutes. Only valid if the selected win condition allows configuring the time limit.

scenario_difficulty

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

allow_diplomacy

Added in version 1.1.

(RW) Whether players are allowed to change teams and resign.

allow_naval_warfare

Added in version 1.2.

(RW) Whether players are allowed to refit ships to warships and launch coastal invasions and ship-to-ship battles.

trades

Added in version 1.3.

(RO) An array of all proposed trade offers and ongoing trade agreements.

Each trade agreement is a table with the following properties:

• trade_id (integer): The unique identifier for this trade.

• state (string): Either "proposed" or "running".

• initiator (wl.map.Market): The market that initiated this trade.

• receiver (wl.map.Market): The market that receives this trade,

  or nil if the trade has not been accepted yet.

• sending_player (integer): The wl.game.Player.number

  of the player who initiated the trade.

• receiving_player (integer): The wl.game.Player.number

  of the player who receives the trade.

• items_to_send (table): A table of ware names to amounts of wares to send.

• items_to_receive (table): A table of ware names to amounts of wares to receive.

• num_batches (integer): The number of ware batches to exchange

  (-1 for indefinite trades).

See also:

get_trade()

See also:

wl.map.Market.propose_trade()

See also:

wl.map.Market.accept_trade()

See also:

wl.game.Player.cancel_trade()

See also:

wl.game.Player.reject_trade()

See also:

wl.game.Player.retract_trade()

trade_extension_proposals

Added in version 1.3.

(RO) An array of all proposed trade extensions.

Each trade extensions proposal is a table with the following properties:

• trade_id (integer): The unique identifier for the trade to extend.

• proposer (integer): The wl.game.Player.number

  of the player who proposed the trade extension.

• num_batches (integer): The number of ware batches to add to the trade

  (-1 to make the trade indefinite).

See also:

wl.game.Player.propose_trade_extension()

See also:

wl.game.Player.accept_trade_extension()

See also:

wl.game.Player.reject_trade_extension()

See also:

wl.game.Player.retract_trade_extension()

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.

Parameters:

• func (thread) – coroutine object to run

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

Returns:

nil

save(name)

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.

Parameters:

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.

Returns:

nil

get_trade(id)

Added in version 1.3.

Get a table containing information about the trade proposal or agreement with the provided unique ID.

See trades for information on the table structure.

If no trade with the provided ID exists, nil is returned.

Parameters:

id (integer) – Unique ID of the trade to look up.

See also:

trades

Editor

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.

all_tribes_names

Added in version 1.3.

Returns an array with the names of all registered tribes, including tribes not currently loaded.

(RO) array of string

tribes_descriptions

Returns a list of all the tribes that are available and loaded.

(RO) a list of TribeDescription objects

immovable_descriptions

Returns a list of all the immovables that are available and loaded.

(RO) a list of ImmovableDescription objects

building_descriptions

Added in version 1.2.

(RO) An array of all BuildingDescription objects that are available and loaded.

terrain_descriptions

Returns a list of all the terrains that are available and loaded.

(RO) a list of TerrainDescription objects

worker_descriptions

Returns a list of all the workers that are available and loaded.

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

Parameters:

• 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:

• Resource

• Terrain

• Critter

• Immovable

• Ware

• Worker

• Ship

• Building

• Productionsite

• Trainingsite

• Militarysite

• Warehouse

• Tribe

"resource"

Property descriptor	Values	Example	Since version
"max_amount"	amount (int)	wl.Descriptions():modify_unit("resource", "resource_coal", "max_amount", 50)	1.0
"descname"	descname (string)	wl.Descriptions():modify_unit("resource", "resource_coal", "descname", _("Fossilized Plants"))	1.3

"terrain"

Property descriptor	Values	Example	Since version
"enhancement"	category (string), terrain_name (string)	wl.Descriptions():modify_unit("terrain", "winter_tundra", "enhancement", "diking", "winter_taiga2")	1.0
"textures"	textures_and_fps (table)	wl.Descriptions():modify_unit("terrain", "winter_tundra", "textures", {fps = 10, textures = path.list_files(path.dirname(__file__) .. "blackland_water/water_??.png" )})	1.1
"descname"	descname (string)	wl.Descriptions():modify_unit("terrain", "winter_tundra", "descname", _("Winter Tundra"))	1.3

"critter"

Property descriptor	Values	Example	Since version
"descname"	descname (string)	wl.Descriptions():modify_unit("critter", "moose", "descname", _("Elk"))	1.3

"immovable"

Property descriptor	Values	Example	Since version
"descname"	descname (string)	wl.Descriptions():modify_unit("immovable", "spruce_summer_old", "descname", _("Fir Tree (Old)"))	1.3

"ware"

Property descriptor	Values	Example	Since version
"target_quantity"	tribe (string), amount (int or nil)	wl.Descriptions():modify_unit("ware", "reed", "target_quantity", "frisians", 20)	1.3
"preciousness"	tribe (string), amount (int)	wl.Descriptions():modify_unit("ware", "reed", "preciousness", "frisians", 3)	1.3
"descname"	descname (string)	wl.Descriptions():modify_unit("ware", "reed", "descname", _("Thatch Reed"))	1.3

"worker"

Property descriptor	Values	Example	Since version
"experience"	experience (int)	wl.Descriptions():modify_unit("worker", "frisians_baker", "experience", 32)	1.0
"becomes"	worker_name (string)	wl.Descriptions():modify_unit("worker", "frisians_baker", "becomes", "frisians_baker_chief")	1.0
"programs", "set"	program_name (string), actions_table (table)	wl.Descriptions():modify_unit("worker", "frisians_baker", "programs", "set", "plant_rye", { "findspace=size:any radius:2 space", "walk=coords", "animate=planting duration:6s", "plant=attrib:seed_rye", "animate=planting duration:6s", "return" })	1.0
"buildcost", "set"	ware_name (string), amount (int)	wl.Descriptions():modify_unit("worker", "frisians_baker", "buildcost", "set", "basket", 1)	1.2
"buildcost", "remove"	ware_name (string),	wl.Descriptions():modify_unit("worker", "frisians_baker", "buildcost", "remove", "bread_paddle")	1.2
"target_quantity"	amount (int or nil)	wl.Descriptions():modify_unit("worker", "frisians_baker", "target_quantity", 5)	1.3
"preciousness"	tribe (string), amount (int)	wl.Descriptions():modify_unit("worker", "frisians_baker", "preciousness", "frisians", 8)	1.3
"descname"	descname (string)	wl.Descriptions():modify_unit("worker", "frisians_baker", "descname", _("Bread Master"))	1.3

"ship"

Property descriptor	Values	Example	Since version
"descname"	descname (string)	wl.Descriptions():modify_unit("ship", "frisians_ship", "descname", _("Sail Ship"))	1.3

"building"

Property descriptor	Values	Example	Since version
"enhancement"	building_name (string)	wl.Descriptions():modify_unit("building", "frisians_farm", "enhancement", "frisians_farm_big")	1.1
"buildcost", "remove"	ware_name (string)	wl.Descriptions():modify_unit("building", "frisians_farm", "buildcost", "remove", "granite")	1.1
"buildcost", "set"	ware_name (string), amount (int)	wl.Descriptions():modify_unit("building", "frisians_farm", "buildcost", "set", "brick", 4)	1.1
"return_on_dismantle", "remove"	ware_name (string)	wl.Descriptions():modify_unit("building", "frisians_farm", "return_on_dismantle", "remove", "granite")	1.1
"return_on_dismantle", "set"	ware_name (string), amount (int)	wl.Descriptions():modify_unit("building", "frisians_farm", "return_on_dismantle", "set", "brick", 2)	1.1
"enhancement_cost", "remove"	ware_name (string)	wl.Descriptions():modify_unit("building", "frisians_farm", "enhancement_cost", "remove", "granite")	1.1
"enhancement_cost", "set"	ware_name (string), amount (int)	wl.Descriptions():modify_unit("building", "frisians_farm", "enhancement_cost", "set", "brick", 4)	1.1
"enhancement_return_on_dismantle", "remove"	ware_name (string)	wl.Descriptions():modify_unit("building", "frisians_farm", "enhancement_return_on_dismantle", "remove", "brick", 3)	1.1
"enhancement_return_on_dismantle", "set"	ware_name (string), amount (int)	wl.Descriptions():modify_unit("building", "frisians_farm", "enhancement_return_on_dismantle", "set", "brick", 3)	1.1
"descname"	descname (string)	wl.Descriptions():modify_unit("building", "frisians_farm", "descname", _("Barley Plantation"))	1.3

"productionsite"

Property descriptor	Values	Example	Since version
"input", "add_ware"	ware_name (string), amount (int)	wl.Descriptions():modify_unit("productionsite", "frisians_bakery", "input", "add_ware", "salt", 4)	1.0
"input", "modify_ware"	ware_name (string), new_amount (int)	wl.Descriptions():modify_unit("productionsite", "frisians_bakery", "input", "modify_ware", "water", 9)	1.0
"input", "remove_ware"	ware_name (string)	wl.Descriptions():modify_unit("productionsite", "frisians_bakery", "input", "remove_ware", "barley")	1.0
"input", "add_worker"	worker_name (string), amount (int)	wl.Descriptions():modify_unit("productionsite", "frisians_barracks", "input", "add_worker", "frisians_trainer", 4)	1.0
"input", "modify_worker"	worker_name (string), new_amount (int)	wl.Descriptions():modify_unit("productionsite", "frisians_barracks", "input", "modify_worker", "frisians_carrier", 4)	1.0
"input", "remove_worker"	worker_name (string)	wl.Descriptions():modify_unit("productionsite", "frisians_barracks", "input", "remove_worker", "frisians_carrier")	1.0
"programs", "set"	program_name (string), program_table (table)	wl.Descriptions():modify_unit("productionsite", "frisians_honey_bread_bakery", "programs", "set", "main", { descname = _("working"), actions = { "call=bake_honey", "call=bake_normal", "return=skipped" }})	1.0

"trainingsite"

Property descriptor	Values	Example	Since version
"soldier_capacity"	capacity (int)	wl.Descriptions():modify_unit("trainingsite", "frisians_training_arena", "soldier_capacity", 8)	1.1
"trainer_patience"	patience (int)	wl.Descriptions():modify_unit("trainingsite", "frisians_training_arena", "trainer_patience", 12)	1.1

"militarysite"

Property descriptor	Values	Example	Since version
"conquers"	radius (int)	wl.Descriptions():modify_unit("militarysite", "frisians_outpost", "conquers", 8)	1.1
"heal_per_second"	amount (int)	wl.Descriptions():modify_unit("militarysite", "frisians_outpost", "heal_per_second", 180)	1.1
"max_soldiers"	amount (int)	wl.Descriptions():modify_unit("militarysite", "frisians_outpost", "max_soldiers", 5)	1.1

"warehouse"

Property descriptor	Values	Example	Since version
"heal_per_second"	amount (int)	wl.Descriptions():modify_unit("warehouse", "frisians_warehouse", "heal_per_second", 220)	1.1
"conquers"	radius (int)	wl.Descriptions():modify_unit("warehouse", "frisians_warehouse", "conquers", 7)	1.1
"max_garrison"	amount (int)	wl.Descriptions():modify_unit("warehouse", "frisians_warehouse", "max_garrison", 10)	1.2

"tribe"

Property descriptor	Values	Example	Since version
"add_ware"	ware_name (string), menu_column (int), target_quantity (int or nil), preciousness (int), helptexts (table)	wl.Descriptions():modify_unit("tribe", "frisians", "add_ware", "rye", 1, nil,1, { helptexts = { purpose = _("Rye is used to bake bread. It needs to be ground into flour first.") }})	1.0
"add_worker"	worker_name (string), menu_column (int), target_quantity (int or nil), preciousness (int or nil), helptexts (table)	wl.Descriptions():modify_unit("tribe", "frisians", "add_worker", "frisians_miller", 2, nil, nil, { helptexts = { purpose = _("The miller grinds barley and rye into flour.") }})	1.0
"add_building"	building_name (string), helptexts (table)	wl.Descriptions():modify_unit("tribe", "frisians", "add_building", "frisians_rye_farm", { helptexts = { purpose = _("The rye farm sows and harvests rye.") }})	1.0
"add_immovable"	immovable_name (string), helptexts (table)	wl.Descriptions():modify_unit("tribe", "frisians", "add_immovable", "ryefield_small", { helptexts = { purpose = _("This rye field is growing.") }})	1.0
"descname"	descname (string)	wl.Descriptions():modify_unit("tribe", "frisians", "descname", _("Frisia Magna"))	1.3

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:

wl.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
wl.Descriptions():modify_unit("productionsite", "frisians_smokery",
      "input", "add_ware", "salt", 6)

-- Overwrite the two predefined programs with new ones
wl.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",
            "sleep=duration:16s",
            "animate=working duration:30s",
            "produce=smoked_fish:2"
      }})
wl.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",
            "sleep=duration:16s",
            "animate=working duration:30s",
            "produce=smoked_meat:2"
      }})

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