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 asdesired_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.
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 tocoroutine.yield()
at regular intervals with the absolute game time on which the function should be awakened again. You should also have a look atcore.cr
.- Parameters
func (
thread
) – coroutine object to runwhen (
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 allBuildingDescription
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
andworld
categories from theirpostload.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"
¶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" }})