# 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. To get an object of a player index the array of players:

local plr = wl.Game().players[1]                            -- the first player (usually blue)
local plr = wl.Game().players[2]                            -- the second player
local plr = wl.Game().players[wl.Game().interactive_player] -- the interactive player

name

(RO) The name of this Player.

allowed_buildings

(RO) An array with boolean 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

(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. Note that the player for whom this is set to true can’t attack any buildings anymore.

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) – The title of the message.

• message (string) – The 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) – If true the message window popups immediately, defaults to false.

• icon (string) – A file path to an icon which is shown beside this message. Defaults to "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) – The title of the message.

• message (string) – The 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) – The width of the message box in pixels. Default: 400.

• h (integer) – The height of the 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

• allow_next_scenario (boolean) – If set to true, show a button that allows starting the next scenario at once. Defaults to false.

Returns

nil

sees_field(f)

Returns true if this field is currently seen by this player.

Returns

true or false.

Return type

boolean

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 (string or array) – Either the string "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 (string or array) – Either the string "all" or an array containing the names of the allowed buildings.

Returns

nil

add_objective(name, title, body)

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. Has to be unique.

• 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 created.

Return type

wl.game.Objective

reveal_fields(fields)

Make these fields visible for the 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.

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 player and optionally completely hide them or reset them to unexplored.

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) One of "permanent", "explorable" or "seen". 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) – The name of the scenario to be marked as solved.

get_ships()
Returns

An array of player’s ships.

Return type

array

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.

Parameters

which (string or array) – The name of a building or an array of building names.

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_constructionsites} pairs.

Parameters

which (string or array) – The internal name of a constructionsites building or an array of building names.

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) – The internal name of the building to check for.

• field (wl.map.Field) – The field to check for suitability.

Returns

true if the field has a suitable building plot for this building, false otherwise.

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)

Switch the interactive_player to the player with playernumber gaining full control over the player given by playernumber and loosing control over the formerly interactive player.

Parameters

playernumber (integer) – An index in the array of players.

produced_wares_count(what)

Returns count of wares produced by the player up to now.

Parameters

what (string or array) – This can be either "all" or a single name of a ware or an :classarray of ware names.

Returns

If a single ware name is given, integer is returned, otherwise a table is returned.

Return type

integer or table

is_attack_forbidden(playernumber)

Returns true if this player is currently forbidden to attack the player with the specified playernumber. 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

playernumber (int) – An index in the array of players.

Return type

boolean

set_attack_forbidden(playernumber, forbid)

Sets whether this player is forbidden to attack the player with the specified playernumber. 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
• playernumber (int) – An index in the array of players.

• forbid (boolean) – If this is true forbids attacking, false allows attacking (if the player is not in the same team).

### 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 an attribute 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 formatted via Widelands richtext.

visible

(RW) This is true if this objective is shown in the objectives menu, false otherwisae.

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"

• "read"

• "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 (integer) – 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: info”.

Example reporting a won game:

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