:mod:`wl.game` ====================== .. module:: wl.game :synopsis: Provides access on game internals like Players .. moduleauthor:: The Widelands development team .. currentmodule:: wl.game Module Classes ^^^^^^^^^^^^^^^^ Player ------ .. graphviz:: :alt: Dependency graph for class: Player graph Player { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Player [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] PlayerBase [shape=house, href="../autogen_wl_bases/index.html#playerbase", target="_parent"] PlayerBase -- Player } .. class:: Player Child of: :class:`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 :class:`array` of :attr:`~wl.bases.EditorGameBase.players`: .. code-block:: lua 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 .. attribute:: name (RO) The name of this Player. .. attribute:: allowed_buildings (RO) An :class:`array` with :class:`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 :meth:`allow_buildings` or :meth:`forbid_buildings` for that. .. attribute:: objectives (RO) A :class:`table` of :class:`objectives ` in form of ``{objectivename=objective}``. You can change the objectives in this :class:`table` and it will be reflected in the game. To add a new item, use :meth:`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. .. attribute:: defeated (RO) :const:`true` if this player was defeated, :const:`false` otherwise .. attribute:: resigned .. versionadded:: 1.1 (RO) :const:`true` if this player has resigned, :const:`false` otherwise .. attribute:: end_result .. versionadded:: 1.2 (RO) This player's end status: :const:`0`: lost, :const:`1`: won, :const:`2`: resigned, :const:`255`: end status is not set .. attribute:: messages (RO) An :class:`array` of **all** the :class:`inbox messages ` sent to the player. Note that you can't add messages to this :class:`array`, use :meth:`send_to_inbox` for that. .. attribute:: inbox (RO) An :class:`array` of the :class:`inbox messages ` that are either read or new. Note that you can't add messages to this :class:`array`, use :meth:`send_to_inbox` for that. .. attribute:: color (RO) The playercolor assigned to this player, in hex notation. .. attribute:: 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. .. attribute:: tribe (RO) The :class:`wl.map.TribeDescription` for this player. .. attribute:: see_all (RW) If you set this to :const:`true`, the map will be completely visible for this player. Note that the player for whom this is set to :const:`true` can't attack any buildings anymore. .. attribute:: allow_additional_expedition_items (RW) Whether the player may take additional items onto expeditions. .. attribute:: hidden_from_general_statistics (RW) Whether this player's existence and statistics are not disclosed to other players in the general statistics menu. .. method:: send_to_inbox(title, message[, opts]) Send a message to the player's inbox. One should prefer :meth:`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' :ref:`richtext functions `. :arg title: The title of the message. :type title: :class:`string` :arg message: The text of the message. :type message: :class:`string` Opts is a :class:`table` of optional arguments and can be omitted. If it exist it must contain string/value pairs of the following type: :arg field: The field connected to this message. Default: no field connected to message. :type field: :class:`wl.map.Field` :arg status: Status to attach to this message. Can be :const:`"new"`, :const:`"read"` or :const:`"archived"`. Default: :const:`"new"` :type status: :class:`string` :arg popup: If :const:`true` the message window popups immediately, defaults to :const:`false`. :type popup: :class:`boolean` :arg icon: A file path to an icon which is shown beside this message. Defaults to ``"images/wui/messages/menu_toggle_objectives_menu.png"``. :type icon: :class:`string` :arg heading: A longer message heading to be shown within the message. If this is not set, `title` is used instead. Default: :const:`""` :type building: :class:`string` :returns: The message created. :rtype: :class:`wl.game.InboxMessage` .. method:: 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 :meth:`campaign_message_box` which has more options, e.g. easier positioning of message boxes. :arg title: The title of the message. :type title: :class:`string` :arg message: The text of the message. :type message: :class:`string` Opts is a :class:`table` of optional arguments and can be omitted. If it exist it must contain string/value pairs of the following type: :arg field: The main view will be centered on this field when the box pops up. Default: No field attached to message. :type field: :class:`wl.map.Field` :arg modal: If this is :const:`false`, the game will not wait for the message window to close, but continue at once. :type modal: :class:`boolean` :arg w: The width of the message box in pixels. Default: 400. :type w: :class:`integer` :arg h: The height of the message box in pixels. Default: 300. :type h: :class:`integer` :arg posx: x position of window in pixels. Default: centered :type posx: :class:`integer` :arg posy: y position of window in pixels. Default: centered :type posy: :class:`integer` :arg allow_next_scenario: If set to ``true``, show a button that allows starting the next scenario at once. Defaults to ``false``. :type allow_next_scenario: :class:`boolean` :returns: :const:`nil` .. method:: sees_field(f) Returns :const:`true` if this field is currently seen by this player. :returns: :const:`true` or :const:`false`. :rtype: :class:`boolean` .. method:: seen_field(f) Returns :const:`true` if this field has ever been seen by this player or is currently seen. :returns: :const:`true` or :const:`false`. :rtype: :class:`bool` .. method:: 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. :arg what: Either the string :const:`"all"` or an :class:`array` containing the names of the allowed buildings. :type what: :class:`string` or :class:`array` :returns: :const:`nil` The opposite function is :meth:`forbid_buildings` .. method:: forbid_buildings(what) See :meth:`allow_buildings` for arguments. This is the opposite function. :arg what: Either the string :const:`"all"` or an :class:`array` containing the names of the allowed buildings. :type what: :class:`string` or :class:`array` :returns: :const:`nil` .. method:: add_objective(name, title, body) Add a new :class:`~wl.game.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: 1. 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 2. Win conditions where it is assumed that all players have the same goal :arg name: The name of the objective. Has to be unique. :type name: :class:`string` :arg title: The title of the objective that will be shown in the menu. :type title: :class:`string` :arg body: The full text of the objective. :type body: :class:`string` :returns: The objective created. :rtype: :class:`wl.game.Objective` .. method:: reveal_fields(fields) Make these **fields** visible for the player. The fields will remain visible until they are hidden again by :meth:`hide_fields`, even if they are not in vision range of any buildings or workers. See also :ref:`field_animations` for animated revealing. :arg fields: The fields to reveal. :type fields: :class:`array` of :class:`fields `. :returns: :const:`nil` .. method:: hide_fields(fields[, state = "seen"]) Undo the effect of :meth:`reveal_fields` on these fields for the player and optionally completely hide them or reset them to unexplored. See also :ref:`field_animations` for animated hiding. :arg fields: The fields to hide. :type fields: :class:`array` of :class:`fields `. :arg state: (Optional) One of :const:`"permanent"`, :const:`"explorable"` or :const:`"seen"`. If :const:`"permanent"`, the fields will be marked as completely hidden and will not be seen by buildings or workers until they are revealed again by :meth:`reveal_fields`. If :const:`"explorable"`, they will no longer be visible, but can still be rediscovered by buildings, ships or workers (own or allied). If :const:`"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. :type state: :class:`string` :returns: :const:`nil` .. method:: 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. :arg name: The name of the scenario to be marked as solved. :type name: :class:`string` .. method:: get_ships() :returns: An :class:`array` of player's :class:`ships `. :rtype: :class:`array` .. method:: get_buildings(which) **which** can be either a single name or an :class:`array` of names. In the first case, the method returns an :class:`array` of all Buildings that the player has of this kind. If **which** is an :class:`array` or "all", the function returns a :class:`table` of ``{name=array_of_buildings}`` pairs. :arg which: The name of a building or an :class:`array` of building names. :type which: :class:`string` or :class:`array` :returns: Information about the player's buildings, see :class:`wl.map.Building`. :rtype: :class:`array` or :class:`table` .. method:: get_constructionsites(which) **which** can be either a single name or an :class:`array` of names. In the first case, the method returns an :class:`array` of all constructionsites that the player has of this kind. If which is an :class:`array` or "all", the function returns a :class:`table` of ``{name=array_of_constructionsites}`` pairs. :arg which: The internal name of a constructionsites building or an :class:`array` of building names or "all". :type which: :class:`string` or :class:`array` :returns: Information about the player's constructionsites, see :class:`wl.map.ConstructionSite`. :rtype: :class:`array` or :class:`table` .. method:: 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. :arg building: The internal name of the building to check for. :type building: :class:`string` :arg field: The field to check for suitability. :type field: :class:`wl.map.Field` :returns: :const:`true` if the field has a suitable building plot for this building, :const:`false` otherwise. :rtype: :class:`boolean` .. method:: allow_workers(what) This will become the corresponding function to :meth:`allow_buildings`, but at the moment this is only a stub that accepts only :const:`"all"` as argument. It then activates all workers for the player, that means all workers are allowed to spawn in all warehouses. .. method:: switchplayer(playernumber) Switch the :attr:`~wl.Game.interactive_player` to the player with **playernumber** gaining full control over the player given by **playernumber** and loosing control over the formerly interactive player. :arg playernumber: The :attr:`wl.bases.PlayerBase.number` of the player to switch to. :type playernumber: :class:`integer` .. method:: produced_wares_count(what) Returns count of wares produced by the player up to now. :arg what: This can be either :const:`"all"` or a single name of a ware or an :class`array` of ware names. :type what: :class:`string` or :class:`array` :returns: If a single ware name is given, integer is returned, otherwise a :class:`table` is returned. :rtype: :class:`integer` or :class:`table` .. method:: is_attack_forbidden(playernumber) Returns :const:`true` if this player is currently forbidden to attack the player with the specified **playernumber**. Note that the return value :const:`false` does not necessarily mean that this player *can* attack the other player, as they might for example be in the same team. :arg playernumber: The value of :attr:`wl.bases.PlayerBase.number` of the other player. :type playernumber: :class:`int` :rtype: :class:`boolean` .. method:: set_attack_forbidden(playernumber, forbid) Sets whether this player is forbidden to attack the player with the specified **playernumber**. Note that setting this to :const:`false` does not necessarily mean that this player *can* attack the other player, as they might for example be in the same team. :arg playernumber: The value of :attr:`wl.bases.PlayerBase.number` of the other player. :type playernumber: :class:`int` :arg forbid: If this is :const:`true` forbids attacking, :const:`false` allows attacking (if the player is not in the same team). :type forbid: :class:`boolean` Objective --------- .. class:: 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 :attr:`done` which can be set by the scripter to define if this is done. Use :attr:`visible` to hide it from the users. .. attribute:: name (RO) The internal name. You can reference this object via :attr:`wl.game.Player.objectives` with :attr:`name` as key. .. note:: Although objectives are accessible through :class:`~wl.game.Player`, they are actually shared by all players. .. attribute:: title (RW) The line that is shown in the objectives menu. .. attribute:: body (RW) The complete text of this objective. Can be formatted via Widelands :ref:`richtext `. .. attribute:: visible (RW) This is :const:`true` if this objective is shown in the objectives menu, :const:`false` otherwisae. .. attribute:: done (RW) Defines if this objective is already fulfilled. If done is :const:`true`, the objective will not be shown to the users, no matter what :attr:`visible` is set to. A savegame will be created when this attribute is changed to :const:`true`. InboxMessage ------------ .. class:: InboxMessage This represents a message in the inbox of a player. .. attribute:: title (RO) The title of this message. .. attribute:: body (RO) The body of this message. .. attribute:: sent (RO) The game time in milliseconds when this message was sent. .. attribute:: field (RO) The field that corresponds to this Message. .. attribute:: status (RW) The status of the message. Can be either of * :const:`"new"` * :const:`"read"` * :const:`"archived"` .. attribute:: heading (RO) The long heading of this message that is shown in the body. .. attribute:: icon_name (RO) The filename for the icon that is shown with the message title. .. function:: report_result(plr, result[, info = ""]) Reports the game ending of a player. The player get prompted with a window containing a :class:`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. :arg plr: The Player to report results for. :type plr: :class:`~wl.game.Player` :arg result: The player result (0: lost, 1: won, 2: resigned) :type result: :class:`integer` :arg info: A string containing extra data for this particular win condition. Likely one wants to use :meth:`make_extra_data` for this. The string will be shown beside the :class:`table` as "Player information: info". :type info: :class:`string` Example reporting a won game: .. code-block:: lua wl.game.report_result(plr, 1, make_extra_data( plr, wc_name, wc_version, {score = "Score for this player"}))