# wl.game¶

## Module Classes¶

### Player¶

class wl.game.Player

Child of: wl.bases.PlayerBase

This class represents one of the players in the game. You can access information about this player or act on his behalf. Note that you cannot instantiate a class of this type directly, use wl.Game().players instead.

name

(RO) The name of this Player.

allowed_buildings

(RO) an array with name:bool values with all buildings that are currently allowed for this player. Note that you can not enable/forbid a building by setting the value. Use allow_buildings() or forbid_buildings() for that.

objectives

(RO) A table of objectives in form of {objectivename:objective}. You can change the objectives in this table and it will be reflected in the game. To add a new item, use add_objective().

defeated

(RO) true if this player was defeated, false otherwise

messages

(RO) An array of all the inbox messages sent to the player. Note that you can’t add messages to this array, use send_to_inbox() for that.

inbox

(RO) An array of the inbox messages that are either read or new. Note that you can’t add messages to this array, use send_to_inbox() for that.

color

(RO) The playercolor assigned to this player, in hex notation.

team

(RW) The team number of this player (0 means player is not in a team)

normally only reading should be enough, however it’s a nice idea to have a modular scenario, where teams form during the game.

tribe

Returns the player’s tribe.

(RO) The wl.map.TribeDescription for this player.

see_all

(RW) If you set this to true, the map will be completely visible for this player.

allow_additional_expedition_items

(RW) Whether the player may take additional items onto expeditions.

hidden_from_general_statistics

(RW) Whether this player’s existence and statistics are not disclosed to other players in the general statistics menu.

send_to_inbox(title, message[, opts])

Send a message to the player’s inbox. One should prefer send_to_inbox() from messages.lua, which has an option to wait before sending the message until the player leaves the roadbuilding mode. Title or Message can be a formatted using widelands’ richtext functions.

Parameters
• title (string) – title of the message

• message (string) – text of the message

Opts is a table of optional arguments and can be omitted. If it exist it must contain string/value pairs of the following type:

Parameters
• field (wl.map.Field) – the field connected to this message. Default: no field connected to message

• status (string) – status to attach to this message. can be ‘new’, ‘read’ or ‘archived’. Default: “new”

• popup (boolean) – should the message window be opened for this message or not. Default: false

• icon (string The icon’s file path.) – show a custom icon instead of the standard scenario message icon. Default: “images/wui/messages/menu_toggle_objectives_menu.png”“

• heading – a longer message heading to be shown within the message. If this is not set, title is used instead. Default: “”

Returns

the message created

Return type

wl.game.InboxMessage

message_box(title, message[, opts])

Shows a message box to the player. While the message box is displayed the game is set to pause. Usually you want to use campaign_message_box() which has more options, e.g. easier positioning of message boxes.

Parameters
• title (string) – title of the message

• message (string) – text of the message

Opts is a table of optional arguments and can be omitted. If it exist it must contain string/value pairs of the following type:

Parameters
• field (wl.map.Field) – The main view will be centered on this field when the box pops up. Default: no field attached to message

• modal (boolean) – If this is false, the game will not wait for the message window to close, but continue at once.

• w (integer) – width of message box in pixels. Default: 400.

• h (integer) – width of message box in pixels. Default: 300.

• posx (integer) – x position of window in pixels. Default: centered

• posy (integer) – y position of window in pixels. Default: centered

Returns

nil

sees_field(f)

Returns true if this field is currently seen by this player

Returns

true or false

Return type

bool

seen_field(f)

Returns true if this field has ever been seen by this player or is currently seen

Returns

true or false

Return type

bool

allow_buildings(what)

This method disables or enables buildings to build for the player. What can either be the single string “all” or a list of strings containing the names of the buildings that are allowed.

Parameters

what – either “all” or an array containing the names of the allowed buildings

Returns

nil

The opposite function is forbid_buildings()

forbid_buildings(what)

See allow_buildings() for arguments. This is the opposite function.

Parameters

what – either “all” or an array containing the names of the allowed buildings

Returns

nil

add_objective(name, title, descr)

Add a new objective for this player. Will report an error, if an Objective with the same name is already registered - note that the names for the objectives are shared internally for all players, so not even another player can have an objective with the same name.

Parameters
• name (string) – the name of the objective

• title (string) – the title of the objective that will be shown in the menu

• body (string) – the full text of the objective

Returns

The objective class created

Return type

wl.game.Objective

reveal_fields(fields)

Make these fields visible for the current player. The fields will remain visible until they are hidden again by hide_fields(), even if they are not in vision range of any buildings or workers. See also field_animations.lua for animated revealing.

Parameters

fields (array of fields) – The fields to reveal

Returns

nil

hide_fields(fields[, state = "seen"])

Undo the effect of reveal_fields() on these fields for the current player and optionally completely hide them or reset them to unexplored. See also field_animations.lua for animated hiding. .. note:: Passing a boolean as the state argument is deprecated. Use "permanent" instead of true and "seen" instead of false.

Parameters
• fields (array of fields) – The fields to hide

• state (string) – Optional. If "permanent", the fields will be marked as completely hidden and will not be seen by buildings or workers until they are revealed again by reveal_fields(). If "explorable", they will no longer be visible, but can still be rediscovered by buildings, ships or workers (own or allied). If "seen", they will no longer be permanently visible (fading to foggy), but can still be seen by buildings or workers (own or allied), and the player will remember the last state that they had been seen. This is the default.

Returns

nil

mark_scenario_as_solved(name)

Marks a campaign scenario as solved. Reads the scenario definition in data/campaigns/campaigns.lua to check which scenario and/or campaign should be revealed as a result. This only works for the interactive player and most likely also only in single player games.

Parameters

name (string) – name of the scenario to be marked as solved

get_ships()
Returns

array of player’s ships

Return type

array or table

get_buildings(which)

which can be either a single name or an array of names. In the first case, the method returns an array of all Buildings that the player has of this kind. If which is an array, the function returns a table of (name,array of buildings) pairs.

Rtype which

string or array

Returns

information about the player’s buildings, see wl.map.Building.

Return type

array or table

get_constructionsites(which)

which can be either a single name or an array of names. In the first case, the method returns an array of all constructionsites that the player has of this kind. If which is an array, the function returns a table of (name,array of buildings) pairs.

Rtype which

string or array

Returns

information about the player’s constructionsites, see wl.map.ConstructionSite

Return type

array or table

get_suitability(building, field)

Returns whether this building type can be placed on this field. This is mainly useful in initializations where buildings must be placed automatically.

Parameters
• building (string) – internal name of the building to check for

• field (wl.map.Field) – where the suitability should be checked

Returns

whether the field has a suitable building plot for this building type

Return type

boolean

allow_workers(what)

This will become the corresponding function to allow_buildings(), but at the moment this is only a stub that accepts only “all” as argument. It then activates all workers for the player, that means all workers are allowed to spawn in all warehouses.

switchplayer(playernumber)

If this is the local player (the player set in interactive player) switch to the player with playernumber

produced_wares_count(what)

Returns count of wares produced by the player up to now. ‘what’ can be either an “all” or single ware name or an array of names. If single ware name is given, integer is returned, otherwise the table is returned.

is_attack_forbidden(who)

Returns true if this player is currently forbidden to attack the player with the specified player number. Note that the return value false does not necessarily mean that this player can attack the other player, as they might for example be in the same team.

Parameters

who (int) – player number of the player to query

Return type

boolean

set_attack_forbidden(who, forbid)

Sets whether this player is forbidden to attack the player with the specified player number. Note that setting this to false does not necessarily mean that this player can attack the other player, as they might for example be in the same team.

Parameters
• who (int) – player number of the player to query

• forbid (boolean) – Whether to allow or forbid attacks

### Objective¶

class wl.game.Objective

This represents an Objective, a goal for the player in the game. This is mainly for displaying to the user, but each objective also has a done which can be set by the scripter to define if this is done. Use visible to hide it from the user.

name

(RO) the internal name. You can reference this object via wl.game.Player.objectives with name as key.

title

(RW) The line that is shown in the objectives menu

body

(RW) The complete text of this objective. Can be Widelands richtext

visible

(RW) is this objective shown in the objectives menu

done

(RW) defines if this objective is already fulfilled. If done is true, the objective will not be shown to the user, no matter what. visible is set to. A savegame will be created when this attribute is changed to true.

### InboxMessage¶

class wl.game.InboxMessage

This represents a message in the inbox of a player.

title

(RO) The title of this message

body

(RO) The body of this message

sent

(RO) The game time in milliseconds when this message was sent

field

(RO) The field that corresponds to this Message.

status

(RW) The status of the message. Can be either of

• new

• archived

heading

(RO) The long heading of this message that is shown in the body

icon_name

(RO) The filename for the icon that is shown with the message title

wl.game.report_result(plr, result[, info = ""])

Reports the game ending of a player. The player get prompted with a window containing a table showing the results of all players and teams (if there are any). For mutliplayer games this reports the game ending also to the metaserver if this is an Internet network game.

Parameters
• plr (Player) – The Player to report results for.

• result (number) – The player result (0: lost, 1: won, 2: resigned)

• info (string) – A string containing extra data for this particular win condition. Likely one wants to use make_extra_data() for this. The string will be shown beside the table as “Player information: string”.

Example reporting a won game:

wl.game.report_result(plr, 1, make_extra_data(
plr, wc_name, wc_version, {score = "Score for this player"}))