:mod:`wl.map` ============= .. module:: wl.map :synopsis: Provides access to Fields and Objects on the map .. moduleauthor:: The Widelands development team .. currentmodule:: wl.map .. currentmodule:: wl.map.MapObject Common functions ^^^^^^^^^^^^^^^^ Some map objects share the same functions and attributes: * :ref:`has_wares` * :ref:`has_workers` * :ref:`has_soldiers` * :ref:`has_inputs` .. _has_wares: Common properties for objects with ware storage ----------------------------------------------- Functions for objects which can store wares. Supported at the time of this writing by :class:`~wl.map.Flag` and :class:`~wl.map.Warehouse`. For objects which consume wares, see: :ref:`has_inputs`. .. method:: get_wares(which) Gets the number of wares that currently reside here. :arg which: Can be either of: * The string :const:`"all"`. In this case the function will return a :class:`table` of ``{ware_name=amount}`` pairs that gives information about all ware information available for this object. * A ware name. In this case a single integer is returned. No check is made if this ware makes sense for this location, you can for example ask a :const:`lumberjacks_hut` for the number of :const:`granite` he has and he will return 0. * An :class:`array` of ware names. In this case a :class:`table` of ``{ware_name=amount}`` pairs is returned where only the requested wares are listed. All other entries are :const:`nil`. :returns: :class:`integer` or :class:`table` .. method:: set_wares(which[, amount]) Sets the wares available in this location. Either takes two arguments, a ware name and an amount to set it to. Or it takes a :class:`table` of ``{ware_name=amount}`` pairs. Wares are created and added to an economy out of thin air. :arg which: Name of ware or a :const:`table` of `{ware_name=amount}`` pairs. :type which: :class:`string` or :class:`table` :arg amount: This many units will be available after the call. :type amount: :class:`integer` .. attribute:: valid_wares (RO) A :class:`table` of ``{ware_name=count}`` if storage is somehow constrained in this location. For example for a :class:`~wl.map.ProductionSite` this is the information what wares and how much can be stored as inputs. For unconstrained storage (like :class:`~wl.map.Warehouse`) this is :const:`nil`. You can use this to quickly fill a building: .. code-block:: lua if b.valid_wares then b:set_wares(b.valid_wares) end .. _has_inputs: Common properties for objects requiring production inputs --------------------------------------------------------- Supported at the time of this writing by :class:`~wl.map.ProductionSite` and :class:`~wl.map.TrainingSite`. These functions allows to set workers as inputs. These workers are consumed by the production or trainings programs. To access workers that do the work, see: :ref:`has_workers`. .. method:: get_inputs(which) Gets the number of wares and workers that currently reside here for consumption. :arg which: Can be either of: * The string :const:`all`. In this case the function will return a :class:`table` of ``{ware/worker_name,amount}`` pairs that gives information about all ware information available for this object. * A ware or worker name. In this case a single integer is returned. No check is made if this ware/worker makes sense for this location, you can for example ask a :const:`lumberjacks_hut` for the number of :const:`granite` he has and he will return 0. * An :class:`array` of ware and worker names. In this case a :class:`table` of ``{ware/worker_name=amount}`` pairs is returned where only the requested wares/workers are listed. All other entries are :const:`nil`. :returns: :class:`integer` or :class:`table` .. method:: set_inputs(which[, amount]) Sets the wares/workers available in this location which will be consumed by the production/training programm. Either takes two arguments, a ware/worker name and an amount to set it to. Or it takes a :class:`table` of ``{ware/worker_name=amount}`` pairs. Wares are created and added to an economy out of thin air. :arg which: name of ware/worker or ``{ware/worker_name=amount}`` :class:`table` :type which: :class:`string` or :class:`table` :arg amount: this many units will be available after the call :type amount: :class:`integer` .. attribute:: valid_inputs (RO) A :class:`table` of ``{ware/worker_name=amount}`` which describes how many wares/workers can be stored here for consumption. For example for a :class:`~wl.map.ProductionSite` this is the information what wares/workers and can be stored in which amount as inputs. You can use this to quickly fill a building: .. code-block:: lua if b.valid_inputs then b:set_inputs(b.valid_inputs) end .. method:: set_priority(ware, prio [, cs_setting = false]) Sets the priority for the given ware inputqueue. :arg ware: ware name :type ware: :class:`string` :arg prio: The new priority. One of ``"very_low"``, ``"low"``, ``"normal"``, ``"high"``, or ``"very_high"``. :type prio: :class:`string` :arg cs_setting: Only valid for productionsite-constructionsites. If :const:`true`, refers to the settings to apply after construction. :type cs_setting: :class:`bool` .. method:: get_priority(ware [, cs_setting = false]) Returns the priority for the given ware inputqueue. See also :meth:`set_priority`. :arg ware: A ware name. :type ware: :class:`string` :arg cs_setting: Only valid for productionsite-constructionsites. If :const:`true`, refers to the settings to apply after construction. :type cs_setting: :class:`bool` :returns: :class:`string` .. method:: set_desired_fill(item, fill [, cs_setting = false]) Sets the desired fill for the given ware or worker inputqueue, as if the player had clicked the increase/decrease buttons. :arg item: Ware or worker name. :type item: :class:`string` :arg fill: The desired fill. :type fill: :class:`integer` :arg cs_setting: Only valid for productionsite-constructionsites. If :const:`true`, refers to the settings to apply after construction. :type cs_setting: :class:`bool` .. method:: get_desired_fill(item, fill [, cs_setting = false]) Returns the desired fill for the given ware or worker inputqueue. See also :meth:`set_desired_fill`. :arg item: Ware or worker name. :type item: :class:`string` :arg cs_setting: Only valid for productionsite-constructionsites. If :const:`true`, refers to the settings to apply after construction. :type cs_setting: :class:`bool` :returns: :class:`integer` .. _has_workers: Common properties for objects requiring workers ----------------------------------------------- Supported at the time of this writing by :class:`~wl.map.Road`, :class:`~wl.map.Warehouse` and :class:`~wl.map.ProductionSite`. In the case of ProductionSites, these methods allow access to the workers which do the work instead of workers which are consumed. For workers which are consumed, see: :ref:`has_inputs`. .. method:: get_workers(which) Similar to :meth:`wl.map.MapObject.get_wares`. .. method:: set_workers(which[, amount]) Similar to :meth:`wl.map.MapObject.set_wares`. .. attribute:: valid_workers (RO) Similar to :attr:`wl.map.MapObject.valid_wares` but for workers in this location. .. _has_soldiers: Common properties for objects garrisoning soldiers -------------------------------------------------- Supported at the time of this writing by :class:`~wl.map.Warehouse`, :class:`~wl.map.MilitarySite` and :class:`~wl.map.TrainingSite`. .. method:: get_soldiers(descr) Gets information about the soldiers in a location. :arg descr: Can be either of: * A soldier description. Returns an :class:`integer` which is the number of soldiers of this kind in this building. A soldier description is an :class:`array` that contains the level for health, attack, defense and evade (in this order). A usage example: .. code-block:: lua building:get_soldiers({0,0,0,0}) would return the number of soldiers of level 0 in this location. * The string :const:`"all"`. In this case a :class:`table` of ``{soldier_descriptions=count}`` is returned. Note that the following will not work, because Lua indexes tables by identity: .. code-block:: lua building:set_soldiers({0,0,0,0}, 100) building:get_soldiers({0,0,0,0}) -- works, returns 100 building:get_soldiers("all")[{0,0,0,0}] -- works not, this is nil -- Following is a working way to check for a {0,0,0,0} soldier for descr,count in pairs(building:get_soldiers("all")) do if descr[1] == 0 and descr[2] == 0 and descr[3] == 0 and descr[4] == 0 then print(count) end end :returns: Number of soldiers that match **descr** or the :class:`table` containing all soldiers :rtype: :class:`integer` or :class:`table`. .. method:: set_soldiers(which[, amount]) Analogous to :meth:`wl.map.MapObject.set_workers`, but for soldiers. Instead of a name an :class:`array` is used to define the soldier. See below for an example. :arg which: Either a :class:`table` of ``{description=count}`` pairs or one description. In that case amount has to be specified as well. :type which: :class:`table` or :class:`array`. Usage example: .. code-block:: lua building:set_soldiers({0,0,0,0}, 100) would add 100 level 0 soldiers. While .. code-block:: lua building:set_soldiers({ [{0,0,0,0}] = 10, [{1,2,3,4}] = 5, }) would add 10 level 0 soldier and 5 soldiers with hit point level 1, attack level 2, defense level 3 and evade level 4 (as long as this is legal for the players tribe). .. attribute:: max_soldiers (RO) The maximum number of soldiers that can be inside this building at one time. If it is not constrained, like for :class:`~wl.map.Warehouse`, this will be :const:`nil`. .. currentmodule:: wl.map Module Classes ^^^^^^^^^^^^^^ Map --- .. class:: Map Access to the map and its objects. You cannot instantiate this directly, instead access it via ``wl.Game().map``. .. attribute:: allows_seafaring (RO) Whether the map currently allows seafaring. :returns: :const:`true` if there are at least two port spaces that can be reached from each other. .. attribute:: number_of_port_spaces (RO) The amount of port spaces on the map. :returns: An :class:`integer` with the number of port spaces. .. attribute:: port_spaces (RO) A list of coordinates for all port spaces on the map. :returns: A :class:`table` of port space coordinates, like this: ``{{x=0,y=2},{x=54,y=23}}``. .. attribute:: width (RO) The width of the map in fields. .. attribute:: height (RO) The height of the map in fields. .. attribute:: waterway_max_length .. versionadded:: 1.2 (RW) The waterway length limit on this map. .. attribute:: player_slots (RO) This is an :class:`array` that contains a :class:`~wl.map.PlayerSlot` for each player defined in the map. Use :attr:`wl.bases.PlayerBase.number` as index to get this player's description as suggested by the map's author. .. method:: count_conquerable_fields() (RO) Counts all reachable fields that a player could build on. **Note:** The fields are only calculated afresh when this is called for the first time. :returns: An integer with the amount of fields. .. method:: count_terrestrial_fields() (RO) Counts all fields that are not swimmable. **Note:** The fields are only calculated afresh when this is called for the first time. :returns: An integer with the amount of fields. .. method:: count_owned_valuable_fields([immovable_attribute]) (RO) Counts the number of owned valuable fields for all players. :arg immovable_attribute: Optional: If this is set, only count fields that have an immovable with the given attribute. :type immovable_attribute: :class:`string` :returns: A :class:`table` mapping player numbers to their number of owned fields. .. method:: find_ocean_fields(number) Returns an :class:`array` with the given number of Fields so that every field is swimmable, and from each field a sea route to any port space exists. :arg number: The number of fields to find. :type number: :class:`integer` :returns: :class:`array` of :class:`wl.map.Field` .. method:: place_immovable(name, field) Creates an immovable on a given field. If there is already an immovable on the field, an error is reported. :arg name: The name of the immovable to create :type name: :class:`string` :arg field: The immovable is created on this field. :type field: :class:`wl.map.Field` :returns: The created immovable. .. method:: get_field(x, y) Returns a :class:`wl.map.Field` object of the given coordinates. The coordinates must be in range from 0 (inclusive) to the map's width/height (exclusive). :see also: :meth:`wrap_field` .. method:: wrap_field(x, y) .. versionadded:: 1.2 Returns a :class:`wl.map.Field` object of the given coordinates. If the coordinates are out of bounds, they will wrap around. :see also: :meth:`get_field` .. method:: recalculate() This map recalculates the whole map state: Height of fields, buildcaps, whether the map allows seafaring and so on. You only need to call this function if you changed :attr:`~wl.map.Field.raw_height` in any way. .. method:: recalculate_seafaring() This method recalculates whether the map allows seafaring. You only need to call this function if you have been changing terrains to/from water and wanted to defer recalculating whether the map allows seafaring. .. method:: set_port_space(x, y, allowed) Sets whether a port space is allowed at the coordinates (x, y). Returns :const:`false` if the port space couldn't be set. :arg x: The x coordinate of the port space to set/unset. :type x: :class:`integer` :arg y: The y coordinate of the port space to set/unset. :type y: :class:`integer` :arg allowed: Whether building a port will be allowed here. :type allowed: :class:`bool` :returns: :const:`true` on success, or :const:`false` otherwise :rtype: :class:`bool` .. method:: sea_route_exists(field, port) Returns whether a sea route exists from the given field to the given port space. :arg field: The field where to start :type field: :class:`wl.map.Field` :arg port: The port space to find :type port: :class:`wl.map.Field` :returns: :const:`true` if a sea route exists, or :const:`false` otherwise :rtype: :class:`bool` TribeDescription -------------------- .. class:: TribeDescription A static description of a tribe. This class contains information about which buildings, wares, workers etc. a tribe uses. .. attribute:: buildings (RO) An :class:`array` of :class:`BuildingDescription` with all the buildings that the tribe can use, casted to their appropriate subclasses. .. attribute:: builder (RO) The internal name of the builder type that this tribe uses as :class:`string`. .. attribute:: carriers .. versionadded:: 1.1 (RO) An :class:`array` of the internal names of the carrier types that this tribe uses as :class:`string`. .. attribute:: carrier .. deprecated:: 1.1 Use :attr:`carriers` instead. (RO) The internal name of the carrier type that this tribe uses as :class:`string`. .. attribute:: carrier2 .. deprecated:: 1.1 Use :attr:`carriers` instead. (RO) The internal name of the secondary carrier type that this tribe uses as :class:`string`. .. attribute:: ferry (RO) The internal name of the ferry type that this tribe uses as :class:`string`. .. attribute:: descname (RO) The localized name of the tribe as :class:`string` .. attribute:: geologist (RO) The internal name of the geologist type that this tribe uses as :class:`string`. .. attribute:: immovables (RO) An :class:`array` of :class:`ImmovableDescription` with all the immovables that the tribe can use. .. attribute:: resource_indicators (RO) The :class:`table` ``resource_indicators`` as defined in the tribe's ``units.lua``. See `data/tribes/initializations/atlanteans/units.lua` for more information on the table structure. .. attribute:: collectors_points_table (RO) The ``collectors_points_table`` as defined in the tribe's ``units.lua``. See `data/tribes/initializations/atlanteans/units.lua` for more information on the table structure. .. attribute:: name (RO) The internal name of the tribe as :class:`string`. .. attribute:: directory (RO) The path of the tribe's initialization scripts as :class:`string`. .. attribute:: port (RO) The internal name of the port type that this tribe uses as :class:`string`. .. attribute:: ship (RO) The internal name of the ship type that this tribe uses as :class:`string`. .. attribute:: soldier (RO) The internal name of the soldier type that this tribe uses as :class:`string`. .. attribute:: wares (RO) An :class:`array` of :class:`WareDescription` with all the wares that the tribe can use. .. attribute:: workers (RO) an :class:`array` of :class:`WorkerDescription` with all the workers that the tribe can use, casted to their appropriate subclasses. .. method:: has_building(buildingname) Returns :const:`true` if **buildingname** is a building and the tribe can use it. :returns: :const:`true` or :const:`false` :rtype: :class:`bool` .. method:: has_ware(warename) Returns :const:`true` if **warename** is a ware and the tribe uses it. :returns: :const:`true` or :const:`false` :rtype: :class:`bool` .. method:: has_worker(workername) Returns :const:`true` if **workername** is a worker and the tribe can use it. :returns: :const:`true` or :const:`false` :rtype: :class:`bool` MapObjectDescription -------------------- .. graphviz:: :alt: Dependency graph for class: MapObjectDescription graph MapObjectDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] MapObjectDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, ] "ImmovableDescription" [href="../autogen_wl_map/index.html#immovabledescription", target="_parent", label="Immovable-\nDescription", tooltip="ImmovableDescription"] "MapObjectDescription" -- "ImmovableDescription" "BuildingDescription" [href="../autogen_wl_map/index.html#buildingdescription", target="_parent", label="Building-\nDescription", tooltip="BuildingDescription"] "MapObjectDescription" -- "BuildingDescription" "WareDescription" [href="../autogen_wl_map/index.html#waredescription", target="_parent", label="Ware-\nDescription", tooltip="WareDescription"] "MapObjectDescription" -- "WareDescription" "WorkerDescription" [href="../autogen_wl_map/index.html#workerdescription", target="_parent", label="Worker-\nDescription", tooltip="WorkerDescription"] "MapObjectDescription" -- "WorkerDescription" "ShipDescription" [href="../autogen_wl_map/index.html#shipdescription", target="_parent", label="Ship-\nDescription", tooltip="ShipDescription"] "MapObjectDescription" -- "ShipDescription" "ConstructionSiteDescription" [href="../autogen_wl_map/index.html#constructionsitedescription", target="_parent", label="Construction-\nSite-\nDescription", tooltip="ConstructionSiteDescription"] "BuildingDescription" -- "ConstructionSiteDescription" "DismantleSiteDescription" [href="../autogen_wl_map/index.html#dismantlesitedescription", target="_parent", label="Dismantle-\nSite-\nDescription", tooltip="DismantleSiteDescription"] "BuildingDescription" -- "DismantleSiteDescription" "ProductionSiteDescription" [href="../autogen_wl_map/index.html#productionsitedescription", target="_parent", label="Production-\nSite-\nDescription\n… more …", tooltip="ProductionSiteDescription has more children"] "BuildingDescription" -- "ProductionSiteDescription" "MilitarySiteDescription" [href="../autogen_wl_map/index.html#militarysitedescription", target="_parent", label="Military-\nSite-\nDescription", tooltip="MilitarySiteDescription"] "BuildingDescription" -- "MilitarySiteDescription" "WarehouseDescription" [href="../autogen_wl_map/index.html#warehousedescription", target="_parent", label="Warehouse-\nDescription", tooltip="WarehouseDescription"] "BuildingDescription" -- "WarehouseDescription" "SoldierDescription" [href="../autogen_wl_map/index.html#soldierdescription", target="_parent", label="Soldier-\nDescription", tooltip="SoldierDescription"] "WorkerDescription" -- "SoldierDescription" } .. class:: MapObjectDescription A static description of a map object, so it can be used without having to access an actual object on the map. This class contains the properties that are common to all objects a tribe has, such as buildings or wares. E.g. the tribal encyclopedia is built upon this class. To access the static descriptions of this class one can use anything that return description objects. See e.g. some of the attributes of :class:`~wl.Descriptions` or :class:`~wl.bases.EditorGameBase`. Accessing the descriptions of this class during a game is done via the class :class:`MapObject` and the attribute :attr:`MapObject.descr`. .. attribute:: descname (RO) The map object's localized name as :class:`string` .. attribute:: icon_name (RO) The filename for the menu icon as :class:`string` .. attribute:: name (RO) The map object's internal name as :class:`string` .. attribute:: type_name (RO) The map object's type as :class:`string`. Map object types are organized in a hierarchy, where an element that's lower in the hierarchy has all the properties of the higher-placed types, as well as its own additional properties. Any map object's description that isn't linked below can be accessed via its higher types, e.g. a ``bob`` is a :class:`general map object `, and a ``carrier`` is a :class:`worker ` as well as a general map object. Some types do not have any static properties besides those defined in their parent type's description class, and are therefore represented by their parent class. Possible values are: * **Bobs:** Bobs are map objects that can move around the map. Bob types are: * :const:`bob`, the abstract base type for all bobs. For properties see :class:`MapObjectDescription`. * :const:`critter`, animals that aren't controlled by any tribe. For properties see :class:`MapObjectDescription`. * :class:`ship `, a sea-going vessel belonging to a tribe that can ferry wares or an expedition. * :class:`worker `, a worker belonging to a tribe. * :const:`carrier`, a specialized worker for carrying items along a road. For properties see :class:`WorkerDescription`. * :const:`ferry`, a specialized carrier for carrying items along a waterway. For properties see :class:`WorkerDescription`. * :class:`soldier `, a specialized worker that will fight for its tribe. * **Wares:** :class:`ware `, a ware used by buildings to produce other wares, workers or ships * **Immovables:** Immovables are map objects that have a fixed position on the map, like buildings or trees. Immovable types are: * :class:`immovable ` General immovables that can belong to a tribe (e.g. a wheat field) or to the world (e.g. trees or rocks). * **Buildings:** Buildings always belong to a tribe. Building types are: * :class:`building `, the base class for all buildings * :class:`constructionsite `, an actual building is being constructed here, * :class:`dismantlesite `, an actual building is being dismantled here, * :class:`warehouse `, a warehouse can store wares and workers. Headquarters and ports are special types of warehouses, but they belong to the same class, * :class:`militarysite `, a building manned by soldiers to expand a tribe's territory, * :class:`productionsite `, the most common type of building, which can produce wares, * :class:`trainingsite `, a specialized productionsite for improving soldiers. * **Other Immovables:** Specialized immovables that aren't buildings. * :const:`flag`, a flag that can hold wares for transport. For properties see :class:`MapObjectDescription`. * :const:`roadbase`, the abstract base type for roads and waterways. For properties see :class:`MapObjectDescription`. * :const:`road`, a road connecting two flags. For properties see :class:`MapObjectDescription`. * :const:`waterway`, a waterway connecting two flags. For properties see :class:`MapObjectDescription`. * :const:`portdock`, a 'parking space' on water terrain where ships can load/unload wares and workers. A portdock is invisible to the player and one is automatically placed next to each port building. For properties see :class:`MapObjectDescription`. * **Abstract:** These types are abstract map objects that are used by the engine and are not visible on the map. They are mentioned here only for completeness; no Lua interface to access such objects or descriptions currently exists. * :const:`battle`, holds information about two soldiers in a fight, * :const:`naval_invasion_base`, links a naval invasion of a port space. * :const:`ship_fleet`, holds information for managing ships and ports, * :const:`ferry_fleet`, holds information for managing ferries and waterways. * :const:`ship_fleet_yard_interface`, links a shipyard to a ship fleet. * :const:`ferry_fleet_yard_interface`, links a ferry yard to a ferry fleet. * :const:`pinned_note`, a textual note pinned to a field by the player. Example to fetch some information from a tribe's description: .. code-block:: lua -- get tribe description local tribe_descr = wl.Game():get_tribe_description("barbarians") -- get building descriptions of this tribe local buildings = tribe_descr.buildings -- iterate over all building descriptions for i, building in ipairs(buildings) do print(building.type_name, building.name) -- filter military sites if building.type_name == "militarysite" do print(building.max_number_of_soldiers) end end .. method:: helptexts(tribename) (RO) Returns a :class:`table` of helptexts if it exists for the given tribe, an empty :class:`table` otherwise. Keys are ``lore``, ``lore_author``, ``purpose``, ``note``, ``performance``, all of them optional. The :class:`table` may contain other keys as well. :arg tribename: The tribe for which we want to fetch the helptext. :type tribename: :class:`string` ImmovableDescription -------------------- .. graphviz:: :alt: Dependency graph for class: ImmovableDescription graph ImmovableDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ImmovableDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- ImmovableDescription } .. class:: ImmovableDescription Child of: :class:`MapObjectDescription` A static description of a :class:`base immovable `. See also :class:`MapObjectDescription` for more properties. .. attribute:: species (RO) The localized species name of the immovable, or an empty string if it has none. .. attribute:: buildcost (RO) A :class:`table` of ``{ware=amount}`` pairs, describing the build cost for the immovable. .. attribute:: becomes (RO) An :class:`array` of map object names that this immovable can turn into, e.g. ``{"atlanteans_ship"}`` or ``{"deadtree2","fallentree"}``. .. attribute:: terrain_affinity (RO) A :class:`table` containing numbers labeled as pickiness, preferred_fertility, preferred_humidity, and preferred_temperature, or :const:`nil` if the immovable has no terrain affinity. E.g. for a beech this will be: .. code-block:: lua { preferred_humidity = 400, preferred_temperature = 110, preferred_fertility = 600, pickiness = 60 } .. attribute:: size (RO) The size of this immovable. Can be either of * :const:`none` -- Example: mushrooms. Immovables will be destroyed when something else is built on this field. * :const:`small` -- Example: trees, flags or small sized buildings * :const:`medium` -- Example: Medium sized buildings * :const:`big` -- Example: Big sized buildings or rocks .. method:: has_attribute(attribute_name) Returns :const:`true` if the immovable has the attribute, :const:`false` otherwise. :arg attribute_name: The attribute that we are checking for. :type attribute_name: :class:`string` .. method:: probability_to_grow(terrain_description) Returns a :class:`double` describing the probability that this immovable will grow on the given terrain. Returns :const:`nil` if this immovable has no terrain affinity. Note that floating-point arithmetic is platform-dependent. Using :class:`double` values to make any decisions in the script logic might result in desyncs. :arg terrain_description: The terrain that we are checking the probability for. :type terrain_description: :class:`wl.map.TerrainDescription` BuildingDescription ------------------- .. graphviz:: :alt: Dependency graph for class: BuildingDescription graph BuildingDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] BuildingDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- BuildingDescription "ConstructionSiteDescription" [href="../autogen_wl_map/index.html#constructionsitedescription", target="_parent", label="Construction-\nSite-\nDescription", tooltip="ConstructionSiteDescription"] "BuildingDescription" -- "ConstructionSiteDescription" "DismantleSiteDescription" [href="../autogen_wl_map/index.html#dismantlesitedescription", target="_parent", label="Dismantle-\nSite-\nDescription", tooltip="DismantleSiteDescription"] "BuildingDescription" -- "DismantleSiteDescription" "ProductionSiteDescription" [href="../autogen_wl_map/index.html#productionsitedescription", target="_parent", label="Production-\nSite-\nDescription", tooltip="ProductionSiteDescription"] "BuildingDescription" -- "ProductionSiteDescription" "MilitarySiteDescription" [href="../autogen_wl_map/index.html#militarysitedescription", target="_parent", label="Military-\nSite-\nDescription", tooltip="MilitarySiteDescription"] "BuildingDescription" -- "MilitarySiteDescription" "WarehouseDescription" [href="../autogen_wl_map/index.html#warehousedescription", target="_parent", label="Warehouse-\nDescription", tooltip="WarehouseDescription"] "BuildingDescription" -- "WarehouseDescription" "TrainingSiteDescription" [href="../autogen_wl_map/index.html#trainingsitedescription", target="_parent", label="Training-\nSite-\nDescription", tooltip="TrainingSiteDescription"] "ProductionSiteDescription" -- "TrainingSiteDescription" } .. class:: BuildingDescription Child of: :class:`MapObjectDescription` A static description of a tribe's building. This class contains the properties that are common to all buildings. Further properties are implemented in the subclasses. See the parent classes for more properties. .. attribute:: buildcost (RO) A :class:`table` of ``{ware=build_cost}`` for the building. .. attribute:: buildable (RO) :const:`true` if the building can be built. .. attribute:: conquers (RO) The conquer range of the building as an :class:`int`. .. attribute:: destructible (RO) :const:`true` if the building is destructible. .. attribute:: enhanced (RO) :const:`true` if the building is enhanced from another building. .. attribute:: enhanced_from (RO) The :class:`~wl.map.BuildingDescription` that this was enhanced from, or :const:`nil` if this isn't an enhanced building. .. attribute:: enhancement_cost (RO) A :class:`table` of ``{warename=cost}`` for enhancing to this building type. .. attribute:: enhancement (RO) The :class:`~wl.map.BuildingDescription` that this building can enhance to. .. attribute:: is_mine (RO) :const:`true` if the building is a mine. .. attribute:: is_port (RO) :const:`true` if the building is a port. .. attribute:: size (RO) The size of this building as a :class:`string`. Can be either of * :const:`"small"` -- Small sized buildings * :const:`"medium"` -- Medium sized buildings * :const:`"big"` -- Big sized buildings .. attribute:: returns_on_dismantle (RO) A :class:`table` of ``{warename=amount}`` pairs returned upon dismantling. .. attribute:: enhancement_returns_on_dismantle (RO) A :class:`table` of ``{warename=amount}`` pairs returned upon dismantling an enhanced building. .. attribute:: vision_range (RO) The vision_range of the building as an :class:`integer`. .. attribute:: workarea_radius (RO) The first workarea_radius of the building as an :class:`integer`, :const:`nil` in case bulding has no workareas. ConstructionSiteDescription --------------------------- .. graphviz:: :alt: Dependency graph for class: ConstructionSiteDescription graph ConstructionSiteDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ConstructionSiteDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- BuildingDescription BuildingDescription [href="../autogen_wl_map/index.html#buildingdescription", target="_parent"] BuildingDescription -- ConstructionSiteDescription } .. class:: ConstructionSiteDescription Child of: :class:`BuildingDescription`, :class:`MapObjectDescription` A static description of a tribe's constructionsite. See the parent classes for more properties. DismantleSiteDescription --------------------------- .. graphviz:: :alt: Dependency graph for class: DismantleSiteDescription graph DismantleSiteDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] DismantleSiteDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- BuildingDescription BuildingDescription [href="../autogen_wl_map/index.html#buildingdescription", target="_parent"] BuildingDescription -- DismantleSiteDescription } .. class:: DismantleSiteDescription Child of: :class:`BuildingDescription`, :class:`MapObjectDescription` A static description of a tribe's dismantlesite. See the parent classes for more properties. ProductionSiteDescription ------------------------- .. graphviz:: :alt: Dependency graph for class: ProductionSiteDescription graph ProductionSiteDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ProductionSiteDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- BuildingDescription BuildingDescription [href="../autogen_wl_map/index.html#buildingdescription", target="_parent"] BuildingDescription -- ProductionSiteDescription "TrainingSiteDescription" [href="../autogen_wl_map/index.html#trainingsitedescription", target="_parent", label="Training-\nSite-\nDescription", tooltip="TrainingSiteDescription"] "ProductionSiteDescription" -- "TrainingSiteDescription" } .. class:: ProductionSiteDescription Child of: :class:`BuildingDescription`, :class:`MapObjectDescription` A static description of a tribe's productionsite. See the parent classes for more properties. .. attribute:: inputs (RO) An :class:`array` with :class:`WareDescription` containing the wares that the productionsite needs for its production. .. attribute:: collected_bobs (RO) An :class:`array` of :class:`MapObjectDescription` containing the bobs that this building will collect from the map. For example, a Hunters's Hut will hunt some critters for meat. **Note:** At the moment, only critters are supported here, because we don't have any other use case. .. attribute:: collected_immovables (RO) An :class:`array` of :class:`ImmovableDescription` containing the immovables that this building will collect from the map. For example, a Woodcutters's House will cut down trees to obtain logs, and the Fruit Collector's House will harvest fruit from berry bushes. .. attribute:: collected_resources (RO) An :class:`array` of :class:`ResourceDescription` containing the resources that this building will collect from the map, along with the maximum percentage mined and the chance to still find some more after depletion. E.g. for a Fisher's Hut this will be: .. code-block:: lua { { resource = , yield = 100, when_empty = 0 } } and for a Barbarian Coal Mine this will be: .. code-block:: lua { { resource = , yield = 33.33, when_empty = 5 } } .. attribute:: created_immovables (RO) An :class:`array` of :class:`ImmovableDescription` containing the immovables that this building will place on the map. For example, a Foresters's House will create trees, and the Berry Farm some berry bushes. .. attribute:: created_bobs (RO) An :class:`array` of :class:`MapObjectDescription` containing the bobs that this building will place on the map. For example, a Gamekeepers's Hut will create some critters, and the Shipyard a Ship. .. attribute:: created_resources (RO) An :class:`array` of :class:`ResourceDescription` containing the resources that this building will place on the map. For example, a Fishbreeder's House will create the resource fish. .. attribute:: output_ware_types (RO) An :class:`array` of :class:`WareDescription` containing the wares that the productionsite can produce. .. attribute:: output_worker_types (RO) An :class:`array` of :class:`WorkerDescription` containing the workers that the productionsite can produce. .. attribute:: production_programs (RO) An :class:`array` with the production program names as string. See :ref:`production site programs `. .. attribute:: supported_productionsites (RO) An :class:`array` with :class:`ProductionSiteDescription` containing the buildings that will collect the bobs, immovables or resources from the map that this building will place on it. For example, a Forester's House will support a Woodcutter's House, because it places trees on the map. .. attribute:: supported_by_productionsites (RO) An :class:`array` with :class:`ProductionSiteDescription` containing the buildings that place bobs, immovables or resources on the map that this building will collect. For example, a Woodcutter's House is supported by a Forester's House, because it needs trees to fell. .. attribute:: working_positions (RO) An :class:`array` with :class:`WorkerDescription` containing the workers that can work here with their multiplicity, i.e. for an Atlantean mine this would be ``{miner,miner,miner}``. .. method:: consumed_wares_workers(program_name) Returns an :class:`array` of ``{{ware_name,ware_amount}}`` for the wares consumed by this production program. Multiple entries of ``{ware_name,ware_amount}`` are alternatives (OR logic)). :arg program_name: The name of the production program that we want to get the consumed wares for. See :ref:`production site programs `. :type program_name: :class:`string` E.g. this will return for an Atlantean coalmine and the corresponding program: .. code-block:: Lua { 1, {smoked_meat, 2}, {smoked_fish, 2} -- 2 smoked_meat OR 2 smoked_fish 2, {atlanteans_bread, 2} -- AND 2 atlanteans_bread } .. method:: produced_wares(program_name) Returns a :class:`table` of ``{ware_name=ware_amount}`` for the wares produced by this production program. See :ref:`production site programs `. :arg program_name: The name of the production program that we want to get the produced wares for. :type program_name: :class:`string` .. method:: recruited_workers(program_name) Returns a :class:`table` of ``{worker_name=worker_amount}`` for the workers recruited by this production program. See :ref:`production site programs `. :arg program_name: the name of the production program that we want to get the recruited workers for. :type program_name: :class:`string` MilitarySiteDescription ----------------------- .. graphviz:: :alt: Dependency graph for class: MilitarySiteDescription graph MilitarySiteDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] MilitarySiteDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- BuildingDescription BuildingDescription [href="../autogen_wl_map/index.html#buildingdescription", target="_parent"] BuildingDescription -- MilitarySiteDescription } .. class:: MilitarySiteDescription Child of: :class:`BuildingDescription`, :class:`MapObjectDescription` A static description of a tribe's militarysite. A militarysite can garrison and heal soldiers, and it will expand your territory. See the parent classes for more properties. .. attribute:: heal_per_second (RO) The number of health healed per second by the militarysite. .. attribute:: max_number_of_soldiers (RO) The number of soldiers that can be garrisoned at the militarysite. TrainingSiteDescription ----------------------- .. graphviz:: :alt: Dependency graph for class: TrainingSiteDescription graph TrainingSiteDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] TrainingSiteDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- ProductionSiteDescription [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BuildingDescription"] ProductionSiteDescription [href="../autogen_wl_map/index.html#productionsitedescription", target="_parent"] ProductionSiteDescription -- TrainingSiteDescription } .. class:: TrainingSiteDescription Child of: :class:`ProductionSiteDescription`, :class:`BuildingDescription`, :class:`MapObjectDescription` A static description of a tribe's trainingsite. A training site can train some or all of a soldier's properties (attack, defense, evade and health). See the parent classes for more properties. .. attribute:: max_attack (RO) The number of attack points that a soldier can train. .. attribute:: max_defense (RO) The number of defense points that a soldier can train. .. attribute:: max_evade (RO) The number of evade points that a soldier can train. .. attribute:: max_health (RO) The number of health points that a soldier can train. .. attribute:: max_number_of_soldiers (RO) The number of soldiers that can be garrisoned at the trainingsite. .. attribute:: min_attack (RO) The number of attack points that a soldier starts training with. .. attribute:: min_defense (RO) The number of defense points that a soldier starts training with. .. attribute:: min_evade (RO) The number of evade points that a soldier starts training with. .. attribute:: min_health (RO) The number of health points that a soldier starts training with. .. method:: trained_soldiers(program_name) Returns a :class:`table` with following entries [1] = the trained skill, [2] = the starting level, [3] = the resulting level trained by this production program. See :ref:`production site programs `. :arg program_name: the name of the production program that we want to get the trained soldiers for. :type program_name: :class:`string` WarehouseDescription -------------------- .. graphviz:: :alt: Dependency graph for class: WarehouseDescription graph WarehouseDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] WarehouseDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- BuildingDescription BuildingDescription [href="../autogen_wl_map/index.html#buildingdescription", target="_parent"] BuildingDescription -- WarehouseDescription } .. class:: WarehouseDescription Child of: :class:`BuildingDescription`, :class:`MapObjectDescription` A static description of a tribe's warehouse. Note that headquarters are also warehouses. A warehouse keeps people, animals and wares. See the parent classes for more properties. .. attribute:: heal_per_second (RO) The number of health healed per second by the warehouse. ShipDescription ----------------- .. graphviz:: :alt: Dependency graph for class: ShipDescription graph ShipDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ShipDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- ShipDescription } .. class:: ShipDescription Child of: :class:`MapObjectDescription` A static description of a tribe's ship. See also :class:`MapObjectDescription` for more properties. WareDescription --------------- .. graphviz:: :alt: Dependency graph for class: WareDescription graph WareDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] WareDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- WareDescription } .. class:: WareDescription Child of: :class:`MapObjectDescription` A static description of a ware. See the parent class for more properties. .. method:: consumers(tribename) (RO) Returns an :class:`array` with :class:`~wl.map.BuildingDescription` with buildings that need this ware for their production. Loads the tribe if it hasn't been loaded yet. :arg tribename: The name of the tribe that this ware gets checked for. :type tribename: :class:`string` .. method:: is_construction_material(tribename) (RO) Returns :const:`true` if this ware is used by the tribe's construction sites. :arg tribename: The name of the tribe that this ware gets checked for. :type tribename: :class:`string` .. method:: producers(tribename) (RO) Returns an :class:`array` with :class:`BuildingDescription` with buildings that can produce this ware. Loads the tribe if it hasn't been loaded yet. :arg tribename: The name of the tribe that this ware gets checked for. :type tribename: :class:`string` WorkerDescription ----------------- .. graphviz:: :alt: Dependency graph for class: WorkerDescription graph WorkerDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] WorkerDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- WorkerDescription "SoldierDescription" [href="../autogen_wl_map/index.html#soldierdescription", target="_parent", label="Soldier-\nDescription", tooltip="SoldierDescription"] "WorkerDescription" -- "SoldierDescription" } .. class:: WorkerDescription Child of: :class:`MapObjectDescription` A static description of a tribe's worker. See the parent class for more properties. .. attribute:: becomes (RO) The :class:`WorkerDescription` of the worker this one will level up to or :const:`nil` if it never levels up. .. attribute:: buildcost (RO) A list of building requirements, e.g. for an atlateans woodcutter this is ``{"atlanteans_carrier","saw"}``. .. attribute:: employers (RO) An :class:`array` with :class:`BuildingDescription` with buildings where this worker can be employed. .. attribute:: buildable (RO) Returns :const:`true` if this worker is buildable. .. attribute:: needed_experience (RO) The experience the worker needs to reach this level. SoldierDescription -------------------- .. graphviz:: :alt: Dependency graph for class: SoldierDescription graph SoldierDescription { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] SoldierDescription [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObjectDescription [shape=house, href="../autogen_wl_map/index.html#mapobjectdescription", target="_parent"] MapObjectDescription -- WorkerDescription WorkerDescription [href="../autogen_wl_map/index.html#workerdescription", target="_parent"] WorkerDescription -- SoldierDescription } .. class:: SoldierDescription Child of: :class:`WorkerDescription`, :class:`MapObjectDescription` A static description of a tribe's soldier, so it can be used in help files without having to access an actual instance of the worker on the map. See the parent classes for more properties. .. attribute:: max_health_level (RO) The maximum health level that the soldier can have. .. attribute:: max_attack_level (RO) The maximum attack level that the soldier can have. .. attribute:: max_defense_level (RO) The maximum defense level that the soldier can have. .. attribute:: max_evade_level (RO) The maximum evade level that the soldier can have. .. attribute:: base_health (RO) The health points that the soldier starts with .. attribute:: base_min_attack (RO) The minimum random attack points that get added to a soldier's attack .. attribute:: base_max_attack (RO) The maximum random attack points that get added to a soldier's attack .. attribute:: base_defense (RO) The defense % that the soldier starts with .. attribute:: base_evade (RO) The evade % that the soldier starts with .. attribute:: health_incr_per_level (RO) The health points that the soldier will gain with each level. .. attribute:: attack_incr_per_level (RO) The attack points that the soldier will gain with each level. .. attribute:: defense_incr_per_level (RO) The defense % that the soldier will gain with each level. .. attribute:: evade_incr_per_level (RO) The evade % that the soldier will gain with each level. ResourceDescription -------------------- .. class:: ResourceDescription A static description of a resource. .. attribute:: name (RO) The internal name of this resource as :class:`string`. .. attribute:: descname (RO) The display name of this resource as :class:`string`. .. attribute:: is_detectable (RO) :const:`true` if geologists can find this resource. .. attribute:: max_amount (RO) The maximum amount of this resource that a terrain can have. .. attribute:: representative_image (RO) The path to the image representing this resource in the GUI as :class:`string`. .. method:: editor_image(amount) (RO) The path to the image representing the specified amount of this resource as :class:`string`. :arg amount: The amount of the resource what we want an overlay image for. :type amount: :class:`integer` TerrainDescription -------------------- .. class:: TerrainDescription A static description of a terrain. .. attribute:: name (RO) The internal name of this terrain as :class:`string`. .. attribute:: descname (RO) The localized name of this terrain as :class:`string`. .. attribute:: default_resource (RO) The :class:`wl.map.ResourceDescription` for the default resource provided by this terrain, or :const:`nil` if the terrain has no default resource. .. attribute:: default_resource_amount (RO) The amount of the default resource provided by this terrain as :class:`integer`. .. attribute:: fertility (RO) The fertility value for this terrain. See also: :attr:`ImmovableDescription.terrain_affinity` .. attribute:: humidity (RO) The humidity value for this terrain. See also: :attr:`ImmovableDescription.terrain_affinity` .. attribute:: representative_image (RO) The file path to a representative image as :class:`string`. .. attribute:: temperature (RO) The temperature value for this terrain. See also: :attr:`~ImmovableDescription.terrain_affinity` .. attribute:: valid_resources (RO) A list of :class:`wl.map.ResourceDescription` with all valid resources for this terrain. Economy ------- .. class:: Economy Provides access to an economy. An economy will be created each time a player places a flag on the map. As soon this flag is connected to another flag, their two economies will be merged into a single economy. A player can have multiple economies, each of which has its own set of economy target settings. You can get an economy from a :class:`Flag`. .. method:: target_quantity(name) Returns the amount of the given ware or worker that should be kept in stock for this economy. Whether this works only for wares or only for workers is determined by the type of this economy. **Warning**: Since economies can disappear when a player merges them through placing/deleting roads and flags, you must get a fresh economy object every time you use this function. :arg name: The name of the ware or worker. :type name: :class:`string` :returns: :class:`integer` .. method:: set_target_quantity(name, amount) Sets the amount of the given ware or worker type that should be kept in stock for this economy. Whether this works only for wares or only for workers is determined by the type of this economy. **Warning**: Since economies can disappear when a player merges them through placing/deleting roads and flags, you must get a fresh economy object every time you use this function. :arg workername: The name of the worker type. :type workername: :class:`string` :arg amount: The new target amount for the worker. Needs to be ``>=0``. :type amount: :class:`integer` .. method:: needs(name) Check whether the economy's stock of the given ware or worker is lower than the target setting. **Warning**: Since economies can disappear when a player merges them through placing/deleting roads and flags, you must get a fresh economy object every time you use this function. :arg name: The name of the ware or worker. :type name: :class:`string` :returns: :class:`boolean` MapObject --------- .. graphviz:: :alt: Dependency graph for class: MapObject graph MapObject { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] MapObject [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, ] "BaseImmovable" [href="../autogen_wl_map/index.html#baseimmovable", target="_parent", label="Base-\nImmovable", tooltip="BaseImmovable"] "MapObject" -- "BaseImmovable" "Bob" [href="../autogen_wl_map/index.html#bob", target="_parent", label="Bob", tooltip="Bob"] "MapObject" -- "Bob" "PlayerImmovable" [href="../autogen_wl_map/index.html#playerimmovable", target="_parent", label="Player-\nImmovable\n… more …", tooltip="PlayerImmovable has more children"] "BaseImmovable" -- "PlayerImmovable" "Worker" [href="../autogen_wl_map/index.html#worker", target="_parent", label="Worker\n… more …", tooltip="Worker has more children"] "Bob" -- "Worker" "Ship" [href="../autogen_wl_map/index.html#ship", target="_parent", label="Ship", tooltip="Ship"] "Bob" -- "Ship" "PinnedNote" [href="../autogen_wl_map/index.html#pinnednote", target="_parent", label="Pinned-\nNote", tooltip="PinnedNote"] "Bob" -- "PinnedNote" "NavalInvasionBase" [href="../autogen_wl_map/index.html#navalinvasionbase", target="_parent", label="Naval-\nInvasion-\nBase", tooltip="NavalInvasionBase"] "Bob" -- "NavalInvasionBase" "ShipFleetYardInterface" [href="../autogen_wl_map/index.html#shipfleetyardinterface", target="_parent", label="Ship-\nFleet-\nYard-\nInterface", tooltip="ShipFleetYardInterface"] "Bob" -- "ShipFleetYardInterface" "FerryFleetYardInterface" [href="../autogen_wl_map/index.html#ferryfleetyardinterface", target="_parent", label="Ferry-\nFleet-\nYard-\nInterface", tooltip="FerryFleetYardInterface"] "Bob" -- "FerryFleetYardInterface" } .. class:: MapObject This is the base class for all objects in Widelands, including :class:`immovables ` and :class:`bobs `. This class can't be instantiated directly, but provides the base for all others. .. attribute:: __hash (RO) The map object's serial. Used to identify a class in a Set. .. attribute:: serial (RO) The serial number of this object. Note that this value does not stay constant after saving/loading. .. attribute:: descr (RO) The :class:`MapObjectDescription` for this immovable. .. code-block:: lua local immovable = wl.Game().map:get_field(20,31).immovable -- always check if the immovable was found on the field if immovable then if immovable.descr.type_name == "warehouse" -- access MapObjectDescription immovable:set_wares("log", 5) end end .. attribute:: exists .. versionadded:: 1.2 (RO) Whether the map object represented by this Lua object still exists. If it does not exist, no other attributes or functions of this object may be accessed. .. method:: remove() Removes this object immediately. If you want to destroy an object as if the player had see :func:`destroy`. .. method:: destroy() Removes this object immediately. Might do special actions (like leaving a burning fire). If you want to remove an object without side effects, see :func:`remove`. .. method:: has_attribute(attribute) Returns :const:`true` if the map object has this attribute, :const:`false` otherwise. .. note:: This method does exist for all MapObjects, but its data only gets initialised for immovables and for critters. (It always returns :const:`false` for other types.) :arg attribute: The attribute to check for. :type attribute: :class:`string` BaseImmovable ------------- .. graphviz:: :alt: Dependency graph for class: BaseImmovable graph BaseImmovable { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] BaseImmovable [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- BaseImmovable "PlayerImmovable" [href="../autogen_wl_map/index.html#playerimmovable", target="_parent", label="Player-\nImmovable", tooltip="PlayerImmovable"] "BaseImmovable" -- "PlayerImmovable" "PortDock" [href="../autogen_wl_map/index.html#portdock", target="_parent", label="Port-\nDock", tooltip="PortDock"] "PlayerImmovable" -- "PortDock" "Building" [href="../autogen_wl_map/index.html#building", target="_parent", label="Building\n… more …", tooltip="Building has more children"] "PlayerImmovable" -- "Building" "Flag" [href="../autogen_wl_map/index.html#flag", target="_parent", label="Flag", tooltip="Flag"] "PlayerImmovable" -- "Flag" "Road" [href="../autogen_wl_map/index.html#road", target="_parent", label="Road", tooltip="Road"] "PlayerImmovable" -- "Road" } .. class:: BaseImmovable Child of: :class:`MapObject` This is the base class for all immovables in Widelands. More properties are available through this object's :class:`ImmovableDescription`, which you can access via :attr:`MapObject.descr`. .. attribute:: fields (RO) An :class:`array` of :class:`wl.map.Field` that is occupied by this Immovable. If the immovable occupies more than one field (roads or big buildings for example) the first entry in this list will be the main field. PlayerImmovable --------------- .. graphviz:: :alt: Dependency graph for class: PlayerImmovable graph PlayerImmovable { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] PlayerImmovable [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- BaseImmovable BaseImmovable [href="../autogen_wl_map/index.html#baseimmovable", target="_parent"] BaseImmovable -- PlayerImmovable "PortDock" [href="../autogen_wl_map/index.html#portdock", target="_parent", label="Port-\nDock", tooltip="PortDock"] "PlayerImmovable" -- "PortDock" "Building" [href="../autogen_wl_map/index.html#building", target="_parent", label="Building", tooltip="Building"] "PlayerImmovable" -- "Building" "Flag" [href="../autogen_wl_map/index.html#flag", target="_parent", label="Flag", tooltip="Flag"] "PlayerImmovable" -- "Flag" "Road" [href="../autogen_wl_map/index.html#road", target="_parent", label="Road", tooltip="Road"] "PlayerImmovable" -- "Road" "ConstructionSite" [href="../autogen_wl_map/index.html#constructionsite", target="_parent", label="Construction-\nSite", tooltip="ConstructionSite"] "Building" -- "ConstructionSite" "DismantleSite" [href="../autogen_wl_map/index.html#dismantlesite", target="_parent", label="Dismantle-\nSite", tooltip="DismantleSite"] "Building" -- "DismantleSite" "Warehouse" [href="../autogen_wl_map/index.html#warehouse", target="_parent", label="Warehouse", tooltip="Warehouse"] "Building" -- "Warehouse" "ProductionSite" [href="../autogen_wl_map/index.html#productionsite", target="_parent", label="Production-\nSite\n… more …", tooltip="ProductionSite has more children"] "Building" -- "ProductionSite" "MilitarySite" [href="../autogen_wl_map/index.html#militarysite", target="_parent", label="Military-\nSite", tooltip="MilitarySite"] "Building" -- "MilitarySite" } .. class:: PlayerImmovable Child of: :class:`BaseImmovable`, :class:`MapObject` All Immovables that belong to a Player (Buildings, Flags, ...) are based on this Class. More properties are available through this object's :class:`ImmovableDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: owner (RO) The :class:`wl.game.Player` who owns this object. Flag -------- .. graphviz:: :alt: Dependency graph for class: Flag graph Flag { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Flag [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- PlayerImmovable [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable"] PlayerImmovable [href="../autogen_wl_map/index.html#playerimmovable", target="_parent"] PlayerImmovable -- Flag } .. class:: Flag Child of: :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` One flag in the economy of this Player. See also: :ref:`has_wares`. More properties are available through this object's :class:`ImmovableDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: ware_economy (RO) Returns the ware economy that this flag belongs to. **Warning**: Since economies can disappear when a player merges them through placing/deleting roads and flags, you must get a fresh economy object every time you call another function on the resulting economy object. :returns: The :class:`Economy` associated with the flag to handle wares. .. attribute:: worker_economy (RO) Returns the worker economy that this flag belongs to. **Warning**: Since economies can disappear when a player merges them through placing/deleting roads and flags, you must get a fresh economy object every time you call another function on the resulting economy object. :returns: The :class:`Economy` associated with the flag to handle workers. .. attribute:: roads (RO) The roads which are connected to this flag, if any. Note that waterways are currently treated like roads. :returns: A :class:`table` with directions as keys. Directions can be ``"tr"``, ``"r"``, ``"br"``, ``"bl"``, ``"l"`` and ``"tl"``. If this flag has no roads, the :class:`table` will be empty. .. attribute:: building (RO) The building belonging to the flag, if any. .. method:: get_distance(flag) Returns the distance of the specified flag from this flag by roads and/or ships. More precisely, this is the time that a worker will need to get from this flag to the other flag using roads. Note that the distance from A to B is not necessarily equal to the distance from B to A. :arg flag: The flag to find. :type flag: :class:`Flag` :returns: The distance of the flags in walking time or ``nil`` if no path exists. .. method:: send_geologist() Send a geologist to explore the surroundings of this flag. Road ---- .. graphviz:: :alt: Dependency graph for class: Road graph Road { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Road [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- PlayerImmovable [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable"] PlayerImmovable [href="../autogen_wl_map/index.html#playerimmovable", target="_parent"] PlayerImmovable -- Road } .. class:: Road Child of: :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` A road connecting two flags in the economy of this Player. Waterways are currently treated like roads in scripts; however, there are significant differences. You can check whether an instance of Road is a road or waterway using :attr:`road_type`. See also: :ref:`has_workers`. More properties are available through this object's :class:`ImmovableDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: length (RO) The length of the roads in number of edges. .. attribute:: start_flag (RO) The flag were this road starts. .. attribute:: end_flag (RO) The flag were this road ends. .. attribute:: road_type (RO) Type of road. Can be any either of: * ``"normal"`` * ``"busy"`` * ``"waterway"`` PortDock -------- .. graphviz:: :alt: Dependency graph for class: PortDock graph PortDock { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] PortDock [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- PlayerImmovable [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable"] PlayerImmovable [href="../autogen_wl_map/index.html#playerimmovable", target="_parent"] PlayerImmovable -- PortDock } .. class:: PortDock Child of: :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` Each :class:`Warehouse` that is a port has a dock attached to it. The PortDock is an immovable that also occupies a field on the water near the port. More properties are available through this object's :class:`ImmovableDescription`, which you can access via :any:`MapObject.descr`. Building -------- .. graphviz:: :alt: Dependency graph for class: Building graph Building { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Building [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- PlayerImmovable [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable"] PlayerImmovable [href="../autogen_wl_map/index.html#playerimmovable", target="_parent"] PlayerImmovable -- Building "ConstructionSite" [href="../autogen_wl_map/index.html#constructionsite", target="_parent", label="Construction-\nSite", tooltip="ConstructionSite"] "Building" -- "ConstructionSite" "DismantleSite" [href="../autogen_wl_map/index.html#dismantlesite", target="_parent", label="Dismantle-\nSite", tooltip="DismantleSite"] "Building" -- "DismantleSite" "Warehouse" [href="../autogen_wl_map/index.html#warehouse", target="_parent", label="Warehouse", tooltip="Warehouse"] "Building" -- "Warehouse" "ProductionSite" [href="../autogen_wl_map/index.html#productionsite", target="_parent", label="Production-\nSite", tooltip="ProductionSite"] "Building" -- "ProductionSite" "MilitarySite" [href="../autogen_wl_map/index.html#militarysite", target="_parent", label="Military-\nSite", tooltip="MilitarySite"] "Building" -- "MilitarySite" "TrainingSite" [href="../autogen_wl_map/index.html#trainingsite", target="_parent", label="Training-\nSite", tooltip="TrainingSite"] "ProductionSite" -- "TrainingSite" } .. class:: Building Child of: :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` This represents a building owned by a player. More properties are available through this object's :class:`BuildingDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: flag (RO) The flag that belongs to this building (that is to the bottom right of it's main location). .. attribute:: destruction_blocked (RW) Whether the player is forbidden to dismantle or destroy this building. .. method:: dismantle([keep_wares = false]) Instantly turn this building into a dismantlesite. :arg keep_wares: Optional: If :const:`false` (default) the wares in this buildings stock get destroyed. If :const:`true` the wares in this buildings stock will be preserved. :type keep_wares: :const:`bool` .. method:: enhance([keep_wares = false]) .. versionadded:: 1.1 Instantly enhance this building if there is an enhancement. :arg keep_wares: Optional: If :const:`false` (default) the wares in this buildings stock get destroyed. If :const:`true` the wares in this buildings stock will be preserved. :type keep_wares: :const:`bool` ConstructionSite ----------------- .. graphviz:: :alt: Dependency graph for class: ConstructionSite graph ConstructionSite { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ConstructionSite [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Building [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable → PlayerImmovable"] Building [href="../autogen_wl_map/index.html#building", target="_parent"] Building -- ConstructionSite } .. class:: ConstructionSite Child of: :class:`Building`, :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` A construction site as it appears in the game. More properties are available through this object's :class:`ConstructionSiteDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: building (RO) The internal name of the building that is constructed here. .. attribute:: has_builder (RW) :const:`true` if this constructionsite has a builder. Changing this setting causes the worker to be instantly deleted or to be created from thin air. .. attribute:: setting_launch_expedition (RW) Only valid for ports under construction. :const:`true` if an expedition will be launched immediately upon completion. .. attribute:: setting_stopped (RW) Only valid for productionsites and trainingsites under construction. :const:`true` if this building will be initially stopped after completion. .. attribute:: setting_soldier_preference (RW) Only valid for militarysites under construction. ``"heroes"`` if this site will prefer heroes after completion; ``"rookies"`` for rookies; ``"any"`` for no predilection. .. attribute:: setting_soldier_capacity (RW) Only valid for militarysites and trainingsites under construction. The desired number of soldiers stationed here after completion as :const:`integer`. .. method:: get_setting_warehouse_policy(wareworker) Only valid for warehouses under construction. Returns the stock policy to apply to the given ware or worker after completion. :arg wareworker: The set ware or worker stock policy in this warehouse. :type wareworker: :class:`string` .. method:: set_setting_warehouse_policy(wareworker, policystring) Only valid for warehouses under construction. Sets the stock policy to apply to the given ware or worker after completion. Valid values for **policystring** are documented in :meth:`Warehouse.set_warehouse_policies`. DismantleSite ----------------- .. graphviz:: :alt: Dependency graph for class: DismantleSite graph DismantleSite { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] DismantleSite [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Building [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable → PlayerImmovable"] Building [href="../autogen_wl_map/index.html#building", target="_parent"] Building -- DismantleSite } .. class:: DismantleSite Child of: :class:`Building`, :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` A dismantle site as it appears in the game. More properties are available through this object's :class:`DismantleSiteDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: has_builder (RW) :const:`true` if this dismantlesite has a builder. Changing this setting causes the worker to be instantly deleted, or to be created from thin air. Warehouse --------- .. graphviz:: :alt: Dependency graph for class: Warehouse graph Warehouse { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Warehouse [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Building [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable → PlayerImmovable"] Building [href="../autogen_wl_map/index.html#building", target="_parent"] Building -- Warehouse } .. class:: Warehouse Child of: :class:`Building`, :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` Every Headquarter, Port or Warehouse on the Map is of this type. See also: * :ref:`has_wares` * :ref:`has_workers` * :ref:`has_soldiers` More properties are available through this object's :class:`WarehouseDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: portdock (RO) If this Warehouse is a port, returns the :class:`PortDock` attached to it, otherwise :const:`nil`. .. attribute:: expedition_in_progress (RO) If this Warehouse is a port, and an expedition is in progress, this is :const:`true`, otherwise :const:`nil`. .. method:: set_warehouse_policies(which, policy) Sets the policies how the warehouse should handle the given wares and workers. :arg which: Behaves like :meth:`wl.map.MapObject.get_wares`. :type which: :class:`string` or :class:`table` :arg policy: The policy to apply for all the wares and workers given in **which**. :type policy: A string out of ``"normal"``, ``"prefer"``, ``"dontstock"`` or ``"remove"`` Usage examples: .. code-block:: lua wh:set_warehouse_policies("all", "remove") -- remove all wares wh:set_warehouse_policies("coal", "prefer") -- prefer coal wh:set_warehouse_policies({"coal", "log"}, "dontstock") -- don't store coal and logs .. method:: get_warehouse_policies(which) Returns the policies how the warehouse should handle the given wares and workers. See :meth:`Warehouse.set_warehouse_policies` for policy strings. :arg which: Behaves like :meth:`wl.map.MapObject.get_wares`. :type which: :class:`string` or :class:`array` :returns: :class:`string` or :class:`table` Usage example: .. code-block:: lua wh:get_warehouse_policies("log") -- Returns e.g. "normal" wh:get_warehouse_policies({"ax", "coal"}) -- Returns a :class:`table` like {"ax"="normal", "coal"="prefer"} .. attribute:: warehousename .. versionadded:: 1.2 (RW) The name of the warehouse as :class:`string`. .. method:: start_expedition() Starts preparation for an expedition. .. method:: cancel_expedition() Cancels an expedition if in progress. ProductionSite -------------- .. graphviz:: :alt: Dependency graph for class: ProductionSite graph ProductionSite { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ProductionSite [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Building [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable → PlayerImmovable"] Building [href="../autogen_wl_map/index.html#building", target="_parent"] Building -- ProductionSite "TrainingSite" [href="../autogen_wl_map/index.html#trainingsite", target="_parent", label="Training-\nSite", tooltip="TrainingSite"] "ProductionSite" -- "TrainingSite" } .. class:: ProductionSite Child of: :class:`Building`, :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` Every building that produces anything. See also: * :ref:`has_inputs` * :ref:`has_workers` More properties are available through this object's :class:`ProductionSiteDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: is_stopped (RO) Returns whether this productionsite is currently active or stopped :returns: :const:`false` if the productionsite has been started, :const:`true` if it has been stopped. .. attribute:: productivity (RO) Returns the building's current productivity percentage :returns: A number between 0 and 100. .. method:: toggle_start_stop() If :attr:`ProductionSite.is_stopped`, sends a command to start this productionsite. Otherwise, sends a command to stop this productionsite. MilitarySite -------------- .. graphviz:: :alt: Dependency graph for class: MilitarySite graph MilitarySite { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] MilitarySite [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Building [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable → PlayerImmovable"] Building [href="../autogen_wl_map/index.html#building", target="_parent"] Building -- MilitarySite } .. class:: MilitarySite Child of: :class:`Building`, :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` Military buildings with stationed soldiers. See also: :ref:`has_soldiers` More properties are available through this object's :class:`MilitarySiteDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: capacity (RW) The number of soldiers meant to be stationed here. .. attribute:: soldier_preference (RW) ``"heroes"`` if this site prefers heroes; ``"rookies"`` for rookies; or ``"any"`` for no predilection. TrainingSite -------------- .. graphviz:: :alt: Dependency graph for class: TrainingSite graph TrainingSite { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] TrainingSite [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- ProductionSite [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: BaseImmovable → PlayerImmovable → Building"] ProductionSite [href="../autogen_wl_map/index.html#productionsite", target="_parent"] ProductionSite -- TrainingSite } .. class:: TrainingSite Child of: :class:`ProductionSite`, :class:`Building`, :class:`PlayerImmovable`, :class:`BaseImmovable`, :class:`MapObject` A specialized production site for training soldiers. See also: :ref:`has_soldiers` More properties are available through this object's :class:`TrainingSiteDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: capacity (RW) The number of soldiers meant to be stationed here. Bob --- .. graphviz:: :alt: Dependency graph for class: Bob graph Bob { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Bob [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob "Worker" [href="../autogen_wl_map/index.html#worker", target="_parent", label="Worker", tooltip="Worker"] "Bob" -- "Worker" "Ship" [href="../autogen_wl_map/index.html#ship", target="_parent", label="Ship", tooltip="Ship"] "Bob" -- "Ship" "PinnedNote" [href="../autogen_wl_map/index.html#pinnednote", target="_parent", label="Pinned-\nNote", tooltip="PinnedNote"] "Bob" -- "PinnedNote" "NavalInvasionBase" [href="../autogen_wl_map/index.html#navalinvasionbase", target="_parent", label="Naval-\nInvasion-\nBase", tooltip="NavalInvasionBase"] "Bob" -- "NavalInvasionBase" "ShipFleetYardInterface" [href="../autogen_wl_map/index.html#shipfleetyardinterface", target="_parent", label="Ship-\nFleet-\nYard-\nInterface", tooltip="ShipFleetYardInterface"] "Bob" -- "ShipFleetYardInterface" "FerryFleetYardInterface" [href="../autogen_wl_map/index.html#ferryfleetyardinterface", target="_parent", label="Ferry-\nFleet-\nYard-\nInterface", tooltip="FerryFleetYardInterface"] "Bob" -- "FerryFleetYardInterface" "Soldier" [href="../autogen_wl_map/index.html#soldier", target="_parent", label="Soldier", tooltip="Soldier"] "Worker" -- "Soldier" } .. class:: Bob Child of: :class:`MapObject` This is the base class for all Bobs in widelands. More properties are available through this object's :class:`MapObjectDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: field (RO) The field the bob is located on. .. method:: has_caps(swim_or_walk) (RO) Whether this bob can swim or walk. :arg swim_or_walk: Can be either of :const:`"swims"` or :const:`"walks"`. :type swim_or_walk: :class:`string` :returns: :const:`true` if this bob is able to **swim_or_walk**, otherwise :const:`false`. Ship ---- .. graphviz:: :alt: Dependency graph for class: Ship graph Ship { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Ship [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob Bob [href="../autogen_wl_map/index.html#bob", target="_parent"] Bob -- Ship } .. class:: Ship Child of: :class:`Bob`, :class:`MapObject` This represents a ship in game. More properties are available through this object's :class:`MapObjectDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: destination (RO) Either :const:`nil` if there is no current destination, otherwise the :class:`PortDock` or :class:`Ship`. .. attribute:: last_portdock (RO) Either :const:`nil` if no port was ever visited or the last portdock was destroyed, otherwise the :class:`PortDock` of the last visited port. .. attribute:: state (RO) Query which state the ship is in. Can be either of: * :const:`"transport"`, * :const:`"exp_waiting"`, :const:`"exp_scouting"`, :const:`"exp_found_port_space"`, :const:`"exp_colonizing"`, * :const:`"sink_request"`, :const:`"sink_animation"` :returns: The ship's state as :const:`string`, or :const:`nil` if there is no valid state. .. attribute:: type .. versionadded:: 1.2 (RO) The state the ship is in as :const:`string`: :const:`"transport"` or :const:`"warship"`. .. attribute:: island_explore_direction (RW) Actual direction if the ship sails around an island. Sets/returns :const:`"cw"` (clockwise), :const:`"ccw"` (counter clock wise) or :const:`nil`. .. attribute:: shipname .. versionchanged:: 1.2 Read-only in 1.1 and older. (RW) The name of the ship as :class:`string`. .. attribute:: capacity (RW) The ship's current capacity. Defaults to the capacity defined in the tribe's singleton ship description. Do not change this value if the ship is currently shipping more items than the new capacity allows. .. method:: get_wares([which = nil]) When called without arguments, returns the number of wares on this ship. When called with a ware name as argument, returns the amount of the specified ware on the ship. When called with :const:`""` as argument, returns an :class:`array` with the names of all loaded wares. :returns: The number of wares or an :class:`array` of :class:`string`. .. method:: get_workers([which = nil]) When called without arguments, returns the number of workers on this ship. When called with a worker name as argument, returns the amount of the specified worker on the ship. When called with :const:`""` as argument, returns an :class:`array` with all loaded workers. :returns: The number of workers or an :class:`array` of :class:`Worker` .. method:: build_colonization_port() Returns :const:`true` if port space construction was started (ship was in adequate status and a found portspace nearby). :returns: :const:`true` or :const:`false` .. method:: make_expedition([items]) Turns this ship into an expedition ship without a base port. Creates all necessary wares and a builder plus, if desired, the specified additional **items**. The ship must be empty and not an expedition ship when this method is called. Note that the ships :attr:`capacity` is not adjusted if you give additional **items**. If the amount of additional items exceeds the capacity, the game doesn't like it. See also :any:`launch_expeditions` which adjusts :attr:`capacity` depending on the given wares and workers. :arg items: Optional: Additional items to the ones that are needed to build a port. :type items: :class:`table` of ``{ware_or_worker=amount}`` pairs. :returns: :const:`nil` Example with check for sufficient capacity: .. code-block:: lua -- place a ship on the map ship = wl.Game().players[1]:place_ship(wl.Game().map:get_field(21,27)) -- check capacity local free_capacity = ship.capacity -- subtract buildcost for port local buildings = wl.Game().players[1].tribe.buildings for i, building in ipairs(buildings) do if building.is_port then for ware, amount in pairs(building.buildcost) do free_capacity = free_capacity - amount end -- stop iterating buildings break end end -- finally subtract one slot for the builder free_capacity = free_capacity - 1 -- adjust capacity if free_capacity < 13 then ship.capacity = ship.capacity + 13 end -- create expedition with additional 13 items ship:make_expedition({barbarians_soldier = 10, fish = 3}) .. method:: refit(type) .. versionadded:: 1.2 Order the ship to refit to the given type. :arg string type: :const:`"transport"` or :const:`"warship"` :returns: :const:`nil` Worker ------ .. graphviz:: :alt: Dependency graph for class: Worker graph Worker { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Worker [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob Bob [href="../autogen_wl_map/index.html#bob", target="_parent"] Bob -- Worker "Soldier" [href="../autogen_wl_map/index.html#soldier", target="_parent", label="Soldier", tooltip="Soldier"] "Worker" -- "Soldier" } .. class:: Worker Child of: :class:`Bob`, :class:`MapObject` All workers that are visible on the map are of this kind. More properties are available through this object's :class:`WorkerDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: owner (RO) The :class:`wl.game.Player` who owns this worker. .. attribute:: location (RO) The location where this worker is situated. This will be either a :class:`Building`, :class:`Road`, :class:`Flag` or :const:`nil`. Note that a worker that is stored in a warehouse has a location :const:`nil`. A worker that is out working (e.g. hunter) has as a location his building. A stationed soldier has his military building as location. Workers on transit usually have the Road they are currently on as location. .. method:: evict() .. versionadded:: 1.2 Evict this worker from his current workplace. Soldier ------- .. graphviz:: :alt: Dependency graph for class: Soldier graph Soldier { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Soldier [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Worker [style=tapered, arrowhead=none, arrowtail=none dir=both,penwidth=15, edgetooltip="Via: Bob"] Worker [href="../autogen_wl_map/index.html#worker", target="_parent"] Worker -- Soldier } .. class:: Soldier Child of: :class:`Worker`, :class:`Bob`, :class:`MapObject` All soldiers that are on the map are represented by this class. More properties are available through this object's :class:`SoldierDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: attack_level (RO) The current attack level of this soldier .. attribute:: defense_level (RO) The current defense level of this soldier .. attribute:: health_level (RO) The current health level of this soldier .. attribute:: evade_level (RO) The current evade level of this soldier .. attribute:: current_health (RW) This soldier's current number of hitpoints left. PinnedNote ---------- .. graphviz:: :alt: Dependency graph for class: PinnedNote graph PinnedNote { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] PinnedNote [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob Bob [href="../autogen_wl_map/index.html#bob", target="_parent"] Bob -- PinnedNote } .. class:: PinnedNote Child of: :class:`Bob`, :class:`MapObject` .. versionadded:: 1.2 This represents a note pinned to a map field. More properties are available through this object's :class:`MapObjectDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: owner (RO) The :class:`wl.game.Player` who owns this object. .. attribute:: text (RW) The text of the note. .. attribute:: color (RW) The color of the note, as an :class:`array` of three integers representing R, G, and B. NavalInvasionBase ----------------- .. graphviz:: :alt: Dependency graph for class: NavalInvasionBase graph NavalInvasionBase { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] NavalInvasionBase [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob Bob [href="../autogen_wl_map/index.html#bob", target="_parent"] Bob -- NavalInvasionBase } .. class:: NavalInvasionBase Child of: :class:`Bob`, :class:`MapObject` .. versionadded:: 1.2 This represents a naval invasion in progress. More properties are available through this object's :class:`MapObjectDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: owner (RO) The :class:`wl.game.Player` who owns this object. .. attribute:: soldiers (RO) An :class:`array` with every :class:`~wl.map.Soldier` currently stationed on this invasion base. ShipFleetYardInterface ---------------------- .. graphviz:: :alt: Dependency graph for class: ShipFleetYardInterface graph ShipFleetYardInterface { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] ShipFleetYardInterface [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob Bob [href="../autogen_wl_map/index.html#bob", target="_parent"] Bob -- ShipFleetYardInterface } .. class:: ShipFleetYardInterface Child of: :class:`Bob`, :class:`MapObject` .. versionadded:: 1.2 This represents an interface between a shipyard and a ship fleet. More properties are available through this object's :class:`MapObjectDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: owner (RO) The :class:`wl.game.Player` who owns this object. .. attribute:: building (RO) The shipyard this interface belongs to. FerryFleetYardInterface ----------------------- .. graphviz:: :alt: Dependency graph for class: FerryFleetYardInterface graph FerryFleetYardInterface { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] FerryFleetYardInterface [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] MapObject [shape=house, href="../autogen_wl_map/index.html#mapobject", target="_parent"] MapObject -- Bob Bob [href="../autogen_wl_map/index.html#bob", target="_parent"] Bob -- FerryFleetYardInterface } .. class:: FerryFleetYardInterface Child of: :class:`Bob`, :class:`MapObject` .. versionadded:: 1.2 This represents an interface between a ferry yard and a ferry fleet. More properties are available through this object's :class:`MapObjectDescription`, which you can access via :any:`MapObject.descr`. .. attribute:: owner (RO) The :class:`wl.game.Player` who owns this object. .. attribute:: building (RO) The ferry yard this interface belongs to. Field ----- .. class:: Field This class represents one Field in Widelands. The field may contain immovables like Flags or Buildings and can be connected via Roads. Every Field has two Triangles associated with itself: The right and the down one. You cannot instantiate this directly, access it via ``wl.Game().map.get_field()`` instead. .. attribute:: __hash (RO) The hashed coordinates of the field's position. Used to identify a class in a Set. .. attribute:: x, y (RO) The x/y coordinate of this field .. attribute:: height (RW) The height of this field. The default height is 10, you can increase or decrease this value to build mountains. Note though that if you change this value too much, all surrounding fields will also change their heights because the slope is constrained. If you are changing the height of many terrains at once, use :attr:`raw_height` instead and then call :any:`recalculate` afterwards. .. attribute:: raw_height (RW) The same as :attr:`height`, but setting this will not trigger a recalculation of the surrounding fields. You can use this field to change the height of many fields on a map quickly, then use :any:`recalculate` to make sure that everything is in order. .. attribute:: viewpoint_x, viewpoint_y (RO) Returns the position in pixels to move the view to to center this field for the current interactive player. .. attribute:: resource (RW) The name of the resource that is available in this field or "none". :see also: :attr:`resource_amount` .. attribute:: resource_amount (RW) How many items of the resource is available in this field. :see also: :attr:`resource` .. attribute:: initial_resource_amount .. versionchanged:: 1.2 Read-only in 1.1 and older. (RW) Starting value of resource. :see also: :attr:`resource` .. attribute:: immovable (RO) The immovable that stands on this field or :const:`nil`. If you want to remove an immovable, you can use :func:`wl.map.MapObject.remove`. .. attribute:: bobs (RO) An :class:`array` of :class:`~wl.map.Bob` that are associated with this field. .. attribute:: terr, terd (RW) The terrain of the right/down triangle. This is a string value containing the name of the terrain as it is defined in the world configuration. You can change the terrain by simply assigning another valid name to these variables. If you are changing the terrain from or to water, the map will not recalculate whether it allows seafaring, because this recalculation can take up a lot of performance. If you need this recalculated, you can do so by calling :any:`recalculate_seafaring` after you're done changing terrains. .. attribute:: rn, ln, brn, bln, trn, tln (RO) The neighbour fields of this field. The abbreviations stand for: * ``rn`` -- Right neighbour * ``ln`` -- Left neighbour * ``brn`` -- Bottom right neighbour * ``bln`` -- Bottom left neighbour * ``trn`` -- Top right neighbour * ``tln`` -- Top left neighbour Note that the widelands map wraps at its borders, that is the following holds: .. code-block:: lua wl.map.Field(wl.map.get_width()-1, 10).rn == wl.map.Field(0, 10) .. attribute:: owner (RO) The current owner of the field or :const:`nil` if noone owns it. See also :attr:`claimers`. .. attribute:: buildable (RO) Returns :const:`true` if a flag or building could be built on this field, independently of whether anybody currently owns this field. .. attribute:: has_roads (RO) Whether any roads lead to the field. Note that waterways are currently treated like roads. :returns: :const:`true` if any of the 6 directions has a road on it, :const:`false` otherwise. .. attribute:: claimers (RO) An :class:`array` of players that have military influence over this field sorted by the amount of influence they have. Note that this does not necessarily mean that claimers[1] is also the owner of the field, as a field that houses a surrounded military building is owned by the surrounded player, but others have more military influence over it. Note: The one currently owning the field is in :attr:`owner`. .. function:: region(r1[, r2]) Returns an :class:`array` of all Fields inside the given region. If one argument is given it defines the radius of the region. If both arguments are specified, the first one defines the outer radius and the second one the inner radius and a hollow region is returned, that is all fields in the outer radius region minus all fields in the inner radius region. A small example: .. code-block:: lua f:region(1) will return an :class:`array` with the following entries (Note: Ordering of the fields inside the :class:`array` is not guaranteed): .. code-block:: lua {f, f.rn, f.ln, f.brn, f.bln, f.tln, f.trn} :returns: The :class:`array` of the given fields. :rtype: :class:`array` .. method:: has_caps(capname) Returns :const:`true` if the field has this **capname** associated with it, otherwise returns :const:`false`. Note: Immovables will hide the caps. If you want to have the caps without immovables use has_max_caps instead :arg capname: Can be either of: :type capname: :class:`string` * :const:`"small"`: Can a small building be built here? * :const:`"medium"`: Can a medium building be built here? * :const:`"big"`: Can a big building be built here? * :const:`"mine"`: Can a mine be built here? * :const:`"port"`: Can a port be built here? * :const:`"flag"`: Can a flag be built here? * :const:`"walkable"`: Is this field passable for walking bobs? * :const:`"swimmable"`: Is this field passable for swimming bobs? .. method:: has_max_caps(capname) Returns :const:`true` if the field has this maximum caps (not taking immovables into account) associated with it, otherwise returns :const:`false`. :arg capname: For possible values see :meth:`has_caps` :type capname: :class:`string` PlayerSlot ---------- .. class:: PlayerSlot A player description as it is in the map. This contains information about the start position, the name of the player if this map is played as scenario and it's tribe. Note that these information can be different than the players actually valid in the game as in single player games, the player can choose most parameters freely. .. attribute:: tribe_name .. versionchanged:: 1.2 Read-only in 1.1 and older. (RW) The name of the tribe suggested for this player in this map. .. attribute:: name .. versionchanged:: 1.2 Read-only in 1.1 and older. (RW) The name for this player as suggested in this map. .. attribute:: starting_field .. versionchanged:: 1.2 Read-only in 1.1 and older. (RW) The starting_field for this player as set in the map. Note that it is not guaranteed that the HQ of the player is on this field as scenarios and starting conditions are free to place the HQ wherever it want. This field is only centered when the game starts.