:mod:`wl.bases` ================== .. module:: wl.bases :synopsis: Base functions for common features in Game and Editor .. moduleauthor:: The Widelands development team .. currentmodule:: wl.bases The :mod:`wl.bases` module contains Base functions on which the classes of :mod:`wl.game` and :mod:`wl.editor` are based. You will not need to create any of the functions in this module directly, but you might use their functionality via the child classes: .. code-block:: lua local map = wl.Game().map -- the map object of a game currently running local map = wl.Editor().map -- the map object in the editor Module Classes ^^^^^^^^^^^^^^^^ EditorGameBase -------------- .. graphviz:: :alt: Dependency graph for class: EditorGameBase graph EditorGameBase { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] EditorGameBase [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] EditorGameBase [shape=house, ] "wl.Game" [href="../autogen_wl/index.html#game", target="_parent", label="wl.Game", tooltip="Game"] "EditorGameBase" -- "wl.Game" "wl.Editor" [href="../autogen_wl/index.html#editor", target="_parent", label="wl.Editor", tooltip="Editor"] "EditorGameBase" -- "wl.Editor" } .. class:: EditorGameBase Common functionality between Editor and Game. .. attribute:: map (RO) The :class:`~wl.map.Map`, either in a game or in the editor. .. attribute:: players (RO) An :class:`array` with the defined players. The players are either of type :class:`wl.game.Player` or :class:`wl.editor.Player`. In game, there might be less players then defined in :attr:`wl.map.Map.player_slots` because some slots might not be taken. Also note that for the same reason you cannot index this :class:`array` with :attr:`wl.bases.PlayerBase.number`, but the players are ordered with increasing number in this :class:`array`. The editor always creates all players that are defined by the map. .. function:: get_immovable_description(immovable_name) Returns the :class:`~wl.map.ImmovableDescription` of the named immovable. To get descriptions for buildings use :meth:`get_building_description`. :arg immovable_name: The internal name of the immovable. :type immovable_name: :class:`string` .. function:: immovable_exists(immovable_name) Returns whether the descriptions know about an :class:`ImmovableDescription` for the named object. This is :const:`true` if the named immovable exists, :const:`false` otherwise. :arg immovable_name: The internal name of the immovable. :type immovable_name: :class:`string` .. function:: get_building_description(building_name) Returns the description for the given building depending on the type of building. See the point **Buildings** in the list of :attr:`~wl.map.MapObjectDescription.type_name`. :arg building_name: The internal name of the building. :type building_name: :class:`string` .. function:: get_ship_description(ship_name) Returns the :class:`~wl.map.ShipDescription` for the given ship. :arg ship_name: The name of the ship. :type ship_name: :class:`string` .. function:: get_tribe_description(tribe_name) Returns the :class:`~wl.map.TribeDescription` of the given tribe. Loads the tribe if it hasn't been loaded yet. :arg tribe_name: The name of the tribe. :type tribe_name: :class:`string` .. function:: get_ware_description(ware_name) Returns the :class:`~wl.map.WareDescription` for the given ware. :arg ware_name: The internal name of the ware. :type ware_name: :class:`string` .. function:: get_worker_description(worker_name) Returns the :class:`~wl.map.WorkerDescription` for the given worker. :arg worker_name: The internal name of the worker. :type worker_name: :class:`string` .. function:: get_resource_description(resource_name) Returns the :class:`~wl.map.ResourceDescription` for the given resource. :arg resource_name: The internal name of the resource. :type resource_name: :class:`string` .. function:: get_terrain_description(terrain_name) Returns the :class:`~wl.map.TerrainDescription` for the given terrain. :arg terrain_name: The internal name of the terrain. :type terrain_name: :class:`string` .. function:: save_campaign_data(campaign_name, scenario_name, data) Saves information that can be read by other scenarios. See also :meth:`read_campaign_data`. :arg campaign_name: The name of the current campaign, e.g. "empiretut" or "frisians". :type campaign_name: :class:`string` :arg scenario_name: The name of the current scenario, e.g. "emp04" or "fri03". :type scenario_name: :class:`string` :arg data: If an :class:`array` is used, the data will be saved in the correct order. Arrays may not contain :const:`nil` values. If a :class:`table` is used, all keys have to be strings. Tables may contain subtables of any depth. Cyclic dependencies will cause Widelands to crash. Values have to be of type :class:`string`, :class:`integer`, :const:`boolean` or :class:`table`. :type data: :class:`array` or :class:`table` .. function:: read_campaign_data(campaign_name, scenario_name) Reads information that was saved by :meth:`save_campaign_data`. :arg campaign_name: The name of the campaign, e.g. "empiretut" or "frisians". :type campaign_name: :class:`string` :arg scenario_name: The name of the scenario that saved the data, e.g. "emp04" or "fri03". :type scenario_name: :class:`string` :returns: The data is returned as a :class:`table` of key-value pairs. The :class:`table` is not guaranteed to be in any particular order, unless it is an :class:`array`, in which case it will be returned in the same order as it was saved. This function returns :const:`nil` if the file cannot be opened for reading. .. function:: set_loading_message(text) Changes the progress message on the loading screen. May be used from the init.lua files for tribe/world loading only. :arg text: The text to display. :type text: :class:`string` PlayerBase ---------- .. graphviz:: :alt: Dependency graph for class: PlayerBase graph PlayerBase { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] PlayerBase [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] PlayerBase [shape=house, ] "wl.editor.Player" [href="../autogen_wl_editor/index.html#player", target="_parent", label="wl.editor.Player", tooltip="Player"] "PlayerBase" -- "wl.editor.Player" "wl.game.Player" [href="../autogen_wl_game/index.html#player", target="_parent", label="wl.game.Player", tooltip="Player"] "PlayerBase" -- "wl.game.Player" } .. class:: PlayerBase The base class for the Player objects in Editor and Game. .. attribute:: number (RO) The number of this Player. .. attribute:: tribe_name (RO) The name of the tribe of this player. .. function:: place_flag(field[, force]) Builds a flag on a given field if it is legal to do so. If not, reports an error. :arg field: where the flag should be created :type field: :class:`~wl.map.Field` :arg force: (Optional) If this is :const:`true` the flag is created with pure force: * if there is an immovable on this field, it will be removed * if there are flags too close by to this field, they will be ripped * if the player does not own the territory, it is conquered for him. :type force: :class:`boolean` :returns: The :class:`~wl.map.Flag` object created or :const:`nil`. .. method:: place_road(roadtype, start_flag, dirs, ...[, force=false]) Start a road or waterway at the given flag, then walk the **dirs** given. Places a flag at the last field. See also the convenience function :meth:`connected_road` in *infrastructure.lua*. :arg roadtype: One of: :const:`"normal"`, :const:`"busy"`, or :const:`"waterway"`. :type roadtype: :class:`string` :arg start_flag: The flag where to start the road. :type start_flag: :class:`~wl.map.Flag` :arg dirs: Comma separated directions of the road. Allowed values for each direction are either: * directions: :const:`"r"`, :const:`"l"`, :const:`"br"`, :const:`"bl"`, :const:`"tr"`, :const:`"tl"` * cardinal directions: :const:`"e"`, :const:`"w"`, :const:`"ne"`, :const:`"nw"`, :const:`"se"`, :const:`"sw"` :type dirs: :class:`string` :arg force: (Optional) If :const:`true` the road will be created by force: All immovables in the way are removed and land is conquered. Defaults to :const:`false`. :type force: :class:`boolean` :returns: The :class:`~wl.map.Road` created. Example: .. code-block:: lua local plr = wl.Game().players[1] local start_field = wl.Game().map:get_field(20,10) local start_flag = pl:place_flag(start_field, true) plr:place_road("normal", start_flag, "br", "br", "r", "r", true) .. method:: place_building(name, field[, cs = false, force = false]) Immediately creates a building on the given field. The building starts out completely empty. See also the functions :meth:`place_building_in_region` and :meth:`prefilled_buildings` in *"infrastructure.lua"*. :arg name: The internal name of the building to create. :type name: :class:`string` :arg field: The field to place the building. :type field: :class:`~wl.map.Field` :arg cs: (Optional) If :const:`true` the building is not created directly, instead a constructionsite for this building is placed. :type cs: :class:`boolean` :arg force: (Optional) If :const:`true` the building is forced into existence: The same action is taken as for :meth:`place_flag` when **force** is :const:`true`. Additionally, all buildings that are too close to the new one are ripped. If you want to use **force** you have to set **cs** also. :type force: :class:`boolean` :returns: The object of the building created. .. method:: place_ship(field) Places a ship for the player's tribe, which will be owned by the player. :arg field: The field where the ship should be placed. :type field: :class:`~wl.map.Field` :returns: The new :class:`~wl.map.Ship` that was created. .. method:: place_pinned_note(field, text[, r, g, b]) .. versionadded:: 1.2 Place a pinned note on the map for this player. :arg field: The field where the note should be placed. :type field: :class:`~wl.map.Field` :arg text: The text of the note. :type text: :class:`string` :arg r: The Red component of the note's color. :type r: :class:`integer` :arg g: The Green component of the note's color. :type g: :class:`integer` :arg b: The Blue component of the note's color. :type b: :class:`integer` :returns: The new :class:`~wl.map.PinnedNote` that was created. .. method:: conquer(f[, radius=1]) Conquer an area around the given field if it does not belong to the player already. This will conquer the fields no matter who owns it at the moment. :arg f: Center field for conquering. :type f: :class:`~wl.map.Field` :arg radius: (Optional) Radius to conquer around. The default of 1 results in 7 fields conquered. :type radius: :class:`integer` :returns: :const:`nil` .. method:: get_workers(name) Returns the number of workers of this name in the players stock. :arg name: The internal name of the worker to get. :type name: :class:`string`. :returns: The number of workers. .. method:: get_wares(name) Returns the number of wares of this name in the players stock. :arg name: The name of the worker to get. :type name: :class:`string`. :returns: The number of wares.