`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 i_plr
for p_idx, player in pairs(wl.Game().players) do
   if player.number == wl.Game().interactive_player then
      i_plr = player                                        -- the interactive player
      break
   end
end

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

Note

The actual implementation of objectives has a single list that is shared by all players, so it’s not possible to have different objectives for different players.

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

resigned¶: Added in version 1.1.

(RO) true if this player has resigned, false otherwise

end_result¶

Added in version 1.2.

(RO) This player’s end status: 0: lost, 1: won, 2: resigned,: 255: end status is not set

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.

ai_type¶

Added in version 1.2.

(RO) Type of the AI controlling this player (“normal”, “weak”, “very_weak”, “empty”; “” if human controlled only)

This information is reliable for multi player games. For single player games, the value for an ai player may also be “random” or even “”.

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 the game. Will report an error, if an objective with the same name is already registered.

Note

Objectives are shared by all players, so it’s not possible to have different objectives for different players.

This function has two kind of users currently:

Scenarios where the objective is only relevant for the interactive player, but it doesn’t matter that it’s also set for the AI players
Win conditions where it is assumed that all players have the same goal

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.

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

See also field_animations.lua for animated hiding.

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 or “all”, 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 or “all”, 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 or “all”.
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) – The wl.bases.PlayerBase.number of the player to switch to.

get_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 array 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) – The value of wl.bases.PlayerBase.number of the other player.
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) – The value of wl.bases.PlayerBase.number of the other player.
forbid (boolean) – If this is true forbids attacking, false allows attacking (if the player is not in the same team).

cancel_trade(id)¶

Added in version 1.3.

Cancel the trade agreement with the provided ID.

Only active trade agreements can be cancelled. Either of the two players between whom the agreement exists may cancel it at any time.

Parameters:: id (integer) – Unique ID of the trade to cancel.
See also:: wl.Game.trades

reject_trade(id)¶

Added in version 1.3.

Reject the proposed trade with the provided ID.

Only proposed trade offers can be rejected. Only the recipient of the offer may reject it.

Parameters:: id (integer) – Unique ID of the trade to reject.
See also:: wl.Game.trades

retract_trade(id)¶

Added in version 1.3.

Retract the proposed trade with the provided ID.

Only proposed trade offers can be retracted. Only the player who initiated the offer may retract it.

Parameters:: id (integer) – Unique ID of the trade to retract.
See also:: wl.Game.trades

propose_trade_extension(id, batches)¶

Added in version 1.3.

Propose to extend the trade with the given ID by the given number of batches.

Parameters:

id (integer) – Unique ID of the trade to propose to extend.
batches (integer) – Number of batches to add to the trade. Maximum 100. Use -1 to make the trade indefinite.

See also:

wl.Game.trade_extension_proposals

accept_trade_extension(id, batches)¶

Added in version 1.3.

Accept the proposal to extend the trade with the given ID by the given number of batches.

Parameters:

id (integer) – Unique ID of the trade to propose to extend.
batches (integer) – Number of batches to add to the trade. Maximum 100. Use -1 to make the trade indefinite.

See also:

wl.Game.trade_extension_proposals

reject_trade_extension(id, batches)¶

Added in version 1.3.

Reject the proposal to extend the trade with the given ID by the given number of batches.

Parameters:

id (integer) – Unique ID of the trade to propose to extend.
batches (integer) – Number of batches to add to the trade. Maximum 100. Use -1 to make the trade indefinite.

See also:

wl.Game.trade_extension_proposals

retract_trade_extension(id, batches)¶

Added in version 1.3.

Retract the proposal to extend the trade with the given ID by the given number of batches.

Parameters:

id (integer) – Unique ID of the trade to propose to extend.
batches (integer) – Number of batches to add to the trade. Maximum 100. Use -1 to make the trade indefinite.

See also:

wl.Game.trade_extension_proposals

Objective¶

class wl.game.Objective¶

This represents an Objective, a goal for the player(s) 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 users.

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

Note

Although objectives are accessible through Player, they are actually shared by all players.

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

`wl.game`¶

Module Classes¶

Player¶

Objective¶

InboxMessage¶

Table of Contents

Previous topic

Next topic

This Page

wl.game¶

Module Classes¶

Player¶

Objective¶

InboxMessage¶

`wl.game`¶