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

New 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

New in version 1.1.

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

allow_naval_warfare

New in version 1.2.

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

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

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.

tribes_descriptions

Returns a list of all the tribes that are available.

(RO) a list of TribeDescription objects

immovable_descriptions

Returns a list of all the immovables that are available.

(RO) a list of ImmovableDescription objects

building_descriptions

New in version 1.2.

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

terrain_descriptions

Returns a list of all the terrains that are available.

(RO) a list of TerrainDescription objects

worker_descriptions

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.

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

• Ware

• Worker

• Building

• Productionsite

• Trainingsite

• Militarysite

• Warehouse

• Tribe

"resource"

Property descriptor	Values	Since version
"max_amount"	amount (int)	1.0

"terrain"

Property descriptor	Values	Since version
"enhancement"	terrain_name (string)	1.0
"textures"	textures_and_fps (table)	1.1

"ware"

Property descriptor	Values	Since version
"target_quantity"	tribe (string), amount (int or nil)	1.3
"preciousness"	tribe (string), amount (int)	1.3

"worker"

Property descriptor	Values	Since version
"experience"	experience (int)	1.0
"becomes"	worker_name (string)	1.0
"programs", "set"	program_name (string), actions_table (table)	1.0
"buildcost", "set"	ware_name (string), amount (int)	1.2
"buildcost", "remove"	ware_name (string),	1.2
"target_quantity"	amount (int or nil)	1.3
"preciousness"	tribe (string), amount (int)	1.3

"building"

Property descriptor	Values	Since version
"enhancement"	building_name (string)	1.1
"buildcost", "remove"	ware_name (string)	1.1
"buildcost", "set"	ware_name (string), amount (int)	1.1
"return_on_dismantle", "remove"	ware_name (string)	1.1
"return_on_dismantle", "set"	ware_name (string), amount (int)	1.1
"enhancement_cost", "remove"	ware_name (string)	1.1
"enhancement_cost", "set"	ware_name (string), amount (int)	1.1
"enhancement_return_on_dismantle", "remove"	ware_name (string)	1.1
"enhancement_return_on_dismantle", "set"	ware_name (string), amount (int)	1.1

"productionsite"

Property descriptor	Values	Since version
"input", "add_ware"	ware_name (string), amount (int)	1.0
"input", "modify_ware"	ware_name (string), new_amount (int)	1.0
"input", "remove_ware"	ware_name (string)	1.0
"input", "add_worker"	worker_name (string), amount (int)	1.0
"input", "modify_worker"	worker_name (string), new_amount (int)	1.0
"input", "remove_worker"	worker_name (string)	1.0
"programs", "set"	program_name (string), program_table (table)	1.0

"trainingsite"

Property descriptor	Values	Since version
"soldier_capacity"	capacity (int)	1.1
"trainer_patience"	patience (int)	1.1

"militarysite"

Property descriptor	Values	Since version
"conquers"	radius (int)	1.1
"heal_per_second"	amount (int)	1.1
"max_soldiers"	amount (int)	1.1

"warehouse"

Property descriptor	Values	Since version
"heal_per_second"	amount (int)	1.1
"conquers"	radius (int)	1.1
"max_garrison"	amount (int)	1.2

"tribe"

Property descriptor	Values	Since version
"add_ware"	ware_name (string), menu_column (int), target_quantity (int or nil), preciousness (int), helptexts (table)	1.0
"add_worker"	worker_name (string), menu_column (int), target_quantity (int or nil), preciousness (int or nil), helptexts (table)	1.0
"add_building"	building_name (string), helptexts (table)	1.0
"add_immovable"	immovable_name (string), helptexts (table)	1.0

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