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 the wl.Game.players insteadl

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 name -> wl.game.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 messages sent to the player. Note that you can’t add messages to this array, use send_message() for that.

inbox

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

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 Tribe_description for this player.

see_all

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

send_message(t, m[, opts])

Send a message to the player, the message will appear in his inbox. Title or Message can be a formatted using wideland’s rich text.

Parameters
  • t (string) – title of the message

  • m (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.Message

message_box(t, m[, opts])

Shows a message box to the player. While the message box is displayed the game will not continue. Use this carefully and prefer send_message() because it is less interruptive, but nevertheless for a set of narrative messages with map movements, this is still useful.

Parameters
  • t (string) – title of the message

  • m (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

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

See

forbid_buildings()

Parameters

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

Returns

nil

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. See also field_animations.lua for animated revealing.

Parameters

fields (array of wl.map.Fields) – The fields to reveal

Returns

nil

hide_fields(fields)

Make these fields hidden for the current player if they are not seen by a military building. See also field_animations.lua for animated hiding.

Parameters
  • fields (array of wl.map.Fields) – The fields to hide

  • unexplore (boolean) – Optional. If true, the fields will be marked as completely unexplored.

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 players buildings

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) – name of the building description 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 :const`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 :const`true`.

Message

class wl.game.Message

This represents a message in the Message Box of a given user.

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 to the metaserver if this is an Internet network game. Otherwise, does nothing.

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. This will vary from game type to game type. See PlayerEndStatus for allowed values