`wl.map`¶

Module Interfaces¶

HasWares¶

class wl.map.HasWares¶

HasWares is an interface that most PlayerImmovable objects that can contain wares implement. This is at the time of this writing Flag and Warehouse.

get_wares(which)¶

Gets the number of wares that currently reside here.

Parameters: which – can be either of

the string all.
In this case the function will return a 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 lumberjacks_hut for the number of granite he has and he will return 0.
an array of ware names.
In this case a table of (ware name,amount) pairs is returned where only the requested wares are listed. All other entries are nil.

Returns: integer or table

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 table of (ware name, amount) pairs. Wares are created and added to an economy out of thin air.

Parameters

which (string or table) – name of ware or (ware_name, amount) table
amount (integer) – this many units will be available after the call

valid_wares¶

(RO) A table of (ware_name, count) if storage is somehow constrained in this location. For example for a ProductionSite this is the information what wares and how much can be stored as inputs. For unconstrained storage (like Warehouse) this is nil.

You can use this to quickly fill a building:

if b.valid_wares then b:set_wares(b.valid_wares) end

HasInputs¶

class wl.map.HasInputs¶

HasInputs is an interface that some PlayerImmovable objects implement. At the time of this writing these are ProductionSite and TrainingSite. This interface is similar to HasWares but additionally allows to set workers as inputs. These workers are consumed by the production or trainings programm.

get_inputs(which)¶

Gets the number of wares and workers that currently reside here for consumption.

Parameters: which – can be either of

the string all.
In this case the function will return a 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 lumberjacks_hut for the number of granite he has and he will return 0.
an array of ware and worker names.
In this case a table of (ware/worker name,amount) pairs is returned where only the requested wares/workers are listed. All other entries are nil.

Returns: integer or table

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 table of (ware/worker name, amount) pairs. Wares are created and added to an economy out of thin air.

Parameters

which (string or table) – name of ware/worker or (ware/worker name, amount) table
amount (integer) – this many units will be available after the call

valid_inputs¶

(RO) A table of (ware/worker name, count) which describes how many wares/workers can be stored here for consumption. For example for a 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:

if b.valid_inputs then b:set_inputs(b.valid_inputs) end

HasWorkers¶

class wl.map.HasWorkers¶

Analogon to HasWares, but for Workers. Supported at the time of this writing by Road, Warehouse and ProductionSite. In the case of ProductionSites, these methods allow access to the workers which do the work instead of workers which are consumed as accessed by the methods of HasInputs.

get_workers(which)¶: Similar to HasWares.get_wares().

set_workers(which[, amount])¶: Similar to HasWares.set_wares().

valid_workers¶: (RO) Similar to HasWares.valid_wares but for workers in this location.

HasSoldiers¶

class wl.map.HasSoldiers¶

Analogon to HasWorkers, but for Soldiers. Due to differences in Soldiers and implementation details in Lua this class has a slightly different interface than HasWorkers. Supported at the time of this writing by Warehouse, MilitarySite and TrainingSite.

get_soldiers(descr)¶

Gets information about the soldiers in a location.

Parameters: descr – can be either of

a soldier description.
Returns an integer which is the number of soldiers of this kind in this building.

A soldier description is a array that contains the level for health, attack, defense and evade (in this order). A usage example:
w:get_soldiers({0,0,0,0})
would return the number of soldiers of level 0 in this location.

the string all.

In this case a table of (soldier descriptions, count) is returned. Note that the following will not work, because Lua indexes tables by identity:

w:set_soldiers({0,0,0,0}, 100)
w:get_soldiers({0,0,0,0}) -- works, returns 100
w: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(w: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 table containing all soldiers
Return type: integer or table.

set_soldiers(which[, amount])¶

Analogous to HasWorkers.set_workers(), but for soldiers. Instead of a name a array is used to define the soldier. See get_soldiers() for an example.

Usage example:

l:set_soldiers({0,0,0,0}, 100)

would add 100 level 0 soldiers. While

l: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).

Parameters: which (table or array.) – either a table of (description, count) pairs or one description. In that case amount has to be specified as well.

max_soldiers¶: (RO) The maximum number of soldiers that can be inside this building at one time. If it is not constrained, like for Warehouse this will be nil.

Module Classes¶

Map¶

class wl.map.Map¶

Access to the map and its objects. You cannot instantiate this directly, instead access it via wl.Game.map.

allows_seafaring¶

(RO) Whether the map currently allows seafaring.

Returns: True if there are at least two port spaces that can be reached from each other.

number_of_port_spaces¶

(RO) The amount of port spaces on the map.

Returns: An integer with the number of port spaces.

port_spaces¶

(RO) A list of coordinates for all port spaces on the map.

Returns: A table of port space coordinates, like this: {{x = 0, y = 2}, {x = 54, y = 23}}.

width¶: (RO) The width of the map in fields.

height¶: (RO) The height of the map in fields.

player_slots¶: (RO) This is an array that contains PlayerSlots for each player defined in the map.

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.

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.

count_owned_valuable_fields([immovable_attribute])¶

(RO) Counts the number of owned valuable fields for all players.

arg name

Optional. If this is set, only count fields that have an immovable with the given atttribute.

type name

string

Returns: A table mapping player numbers to their number of owned fields.

find_ocean_fields(number)¶

Returns an 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.

Returns: array of wl.map.Field

place_immovable(name, field)¶

Creates an immovable on a given field. If there is already an immovable on the field, an error is reported.

Parameters

name (string) – The name of the immovable to create
field (wl.map.Field) – The immovable is created on this field.

Returns

The created immovable.

get_field(x, y)¶: Returns a wl.map.Field object of the given index.

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 raw_height in any way.

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.

set_port_space(x, y, allowed)¶

Sets whether a port space is allowed at the coordinates (x, y). Returns false if the port space couldn’t be set.

Parameters

x (int) – The x coordinate of the port space to set/unset.
y (int) – The y coordinate of the port space to set/unset.
allowed (bool) – Whether building a port will be allowed here.

Returns

true on success, or false otherwise

Return type

bool

sea_route_exists(field, port)¶

Returns whether a sea route exists from the given field to the given port space.

Parameters

field (wl.map.Field) – The field where to start
port (wl.map.Field) – The port space to find

Return type

bool

TribeDescription¶

class wl.map.TribeDescription¶

A static description of a tribe. This class contains information about which buildings, wares, workers etc. a tribe uses.

buildings¶: (RO) an array of LuaBuildingDescription with all the buildings that the tribe can use, casted to their appropriate subclasses.

builder¶: (RO) the string internal name of the builder type that this tribe uses

carrier¶: (RO) the string internal name of the carrier type that this tribe uses

carrier2¶

(RO) the string internal name of the carrier2 type that this tribe uses.: e.g. ‘atlanteans_horse’

ferry¶

(RO) the string internal name of the ferry type that this tribe uses.: e.g. ‘atlanteans_ferry’

descname¶: (RO) a string with the tribe’s localized name

geologist¶: (RO) the string internal name of the geologist type that this tribe uses

immovables¶: (RO) an array of LuaImmovableDescription with all the immovables that the tribe can use.

resource_indicators¶: (RO) the table resource_indicators as defined in the tribe’s tribename.lua. See data/tribes/atlanteans.lua for more information on the table structure.

name¶: (RO) a string with the tribe’s internal name

port¶: (RO) the string internal name of the port type that this tribe uses

ship¶: (RO) the string internal name of the ship type that this tribe uses

soldier¶: (RO) the string internal name of the soldier type that this tribe uses

wares¶: (RO) an array of LuaWareDescription with all the wares that the tribe can use.

workers¶

(RO) an array of LuaWorkerDescription with all the workers that the tribe can use,: casted to their appropriate subclasses.

has_building(buildingname)¶

Returns true if buildingname is a building and the tribe can use it.

Returns: true or false
Return type: bool

has_ware(warename)¶

Returns true if warename is a ware and the tribe uses it.

Returns: true or false
Return type: bool

has_worker(workername)¶

Returns true if workername is a worker and the tribe can use it.

Returns: true or false
Return type: bool

MapObjectDescription¶

class wl.map.MapObjectDescription¶

A static description of a tribe’s map object, so it can be used in help files without having to access an actual object on the map. This class contains the properties that are common to all map objects such as buildings or wares.

The dynamic MapObject class corresponding to this class is the base class for all Objects in widelands, including immovables and Bobs. This class can’t be instantiated directly, but provides the base for all others.

descname¶: (RO) a string with the map object’s localized name

icon_name¶: (RO) the filename for the menu icon.

name¶: (RO) a string with the map object’s internal name

type_name¶

(RO) the map object’s type as a 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 general map object, and a carrier is a worker as well as a general map object. Possible values are:

Bobs: Bobs are map objects that can move around the map. Bob types are:
- bob, the abstract base type for all bobs,
- critter, animals that aren’t controlled by any tribe,
- ship, a sea-going vessel belonging to a tribe that can ferry wares or an expedition,
- worker, a worker belonging to a tribe,
- carrier, a specialized worker for carrying items along a road,
- soldier, a specialized worker that will fight for its tribe.
Wares: 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:
- 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:
  - building, the base class for all buildings
  - constructionsite, an actual building is being constructed here,
  - dismantlesite, an actual building is being dismantled here,
  - warehouse, a warehouse can store wares and workers. Headquarters and ports are special tapes of warehouses, but they belong to the same class,
  - militarysite, a building manned by soldiers to expand a tribe’s territory,
  - productionsite, the most common type of building, which can produce wares,
  - trainingsite, a specialized productionsite for improving soldiers.
- Other Immovables: Specialized immovables that aren’t buildings:
  - flag, a flag that can hold wares for transport,
  - road, a road or waterway connecting two flags,
  - 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.
Abstract: These types are abstract map objects that are used by the engine and are not visible on the map.
- battle, holds information about two soldiers in a fight,
- fleet, holds information for managing ships.

helptext(tribename)¶

Returns the tribe-specific helptexts for this object.

Parameters: tribename – The tribe for which we want to fetch the helptext.

ImmovableDescription¶

class wl.map.ImmovableDescription¶

Child of: MapObjectDescription

A static description of a base immovable, so it can be used in help files without having to access an actual immovable on the map. See also MapObjectDescription for more properties.

species¶

the species name of a tree for editor lists

(RO) the localized species name of the immovable, or an empty string if it has none.

buildcost¶: (RO) a table of ware-to-count pairs, describing the build cost for the immovable.

becomes¶: (RO) a table of map object names that this immovable can turn into, e.g. {"atlanteans_ship"} or {"deadtree2", "fallentree"}.

terrain_affinity¶

returns the terrain affinity values for this immovable

(RO) a table containing numbers labeled as pickiness (uint), preferred_fertility (uint), preferred_humidity (uint), and preferred_temperature (uint), or nil if the immovable has no terrain affinity.

size¶

(RO) The size of this immovable. Can be either of

none – Example: mushrooms. Immovables will be destroyed when
something else is built on this field.
small – Example: trees or flags
medium – Example: Medium sized buildings
big – Example: Big sized buildings or rocks

has_attribute()¶

whether the immovable has the given attribute

Parameters: attribute_name – The attribute that we are checking for.

probability_to_grow()¶

Parameters: terrain (wl.map.TerrainDescription) – The terrain that we are checking the probability for.

(RO) A double describing the probability that this tree will grow on the given terrain.: Returns nil if this immovable tree has no terrain affinity (all trees should have one).

BuildingDescription¶

class wl.map.BuildingDescription¶

Child of: MapObjectDescription, ImmovableDescription

A static description of a tribe’s building, so it can be used in help files without having to access an actual building on the map. 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.

buildcost¶: (RO) a list of ware build cost for the building.

buildable¶: (RO) true if the building can be built.

conquers¶: (RO) the conquer range of the building as an int.

destructible¶: (RO) true if the building is destructible.

enhanced¶: (RO) true if the building is enhanced from another building.

enhanced_from¶: (RO) returns the building that this was enhanced from, or nil if this isn’t an enhanced building.

enhancement_cost¶: (RO) a list of ware cost for enhancing to this building type.

enhancement¶: (RO) a building description that this building can enhance to.

is_mine¶: (RO) true if the building is a mine.

is_port¶: (RO) true if the building is a port.

size¶

(RO) The size of this building. Can be either of

small – Small sized buildings
medium – Medium sized buildings
big – Big sized buildings

returns_on_dismantle¶: (RO) a list of wares returned upon dismantling.

enhancement_returns_on_dismantle¶: (RO) a list of wares returned upon dismantling an enhanced building.

vision range: (RO) the vision_range of the building as an int.

workarea_radius¶

(RO) the first workarea_radius of the building as an int,: nil in case bulding has no workareas

ConstructionSiteDescription¶

class wl.map.ConstructionSiteDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription

A static description of a tribe’s constructionsite, so it can be used in help files without having to access an actual building on the map. See the parent classes for more properties.

DismantleSiteDescription¶

class wl.map.DismantleSiteDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription

A static description of a tribe’s dismantlesite, so it can be used in help files without having to access an actual building on the map. See the parent classes for more properties.

ProductionSiteDescription¶

class wl.map.ProductionSiteDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription

A static description of a tribe’s productionsite, so it can be used in help files without having to access an actual building on the map. This class contains the properties for productionsites that have workers. For militarysites and trainingsites, please use the subclasses. See the parent classes for more properties.

inputs¶: (RO) An array with WareDescription containing the wares that the productionsite needs for its production.

collected_bobs¶

(RO) An array with 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.

collected_immovables¶: (RO) An array with 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.

collected_resources¶

(RO) An array with 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. For example, a Fishers’s House will collect:

{
     {
        resource = <resource description for fish>,
        yield = 100,
        when_empty = 0
     }
  }

and a Barbarian Coal Mine will collect:

{
   {
      resource = <resource description for coal>,
      yield = 33.33,
      when_empty = 5
   }
}

created_immovables¶: (RO) An array with 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.

created_bobs¶: (RO) An array with 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.

created_resources¶: (RO) An array with ResourceDescription containing the resources that this building will place on the map. For example, a Fishbreeder’s House will create the “fish” resource.

output_ware_types¶: (RO) An array with LuaWareDescription containing the wares that the productionsite can produce.

output_worker_types¶: (RO) An array with LuaWorkerDescription containing the workers that the productionsite can produce.

production_programs¶: (RO) An array with the production program names as string.

supported_productionsites¶: (RO) An array with 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.

supported_by_productionsites¶: (RO) An array with 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.

working_positions¶: (RO) An array with WorkerDescription containing the workers that can work here with their multiplicity, i.e. for a atlantean mine this would be { miner, miner, miner }.

consumed_wares_workers¶

Parameters: program_name – the name of the production program that we want to get the consumed wares for :type tribename: string

(RO) Returns a table of {{ware name}, ware amount} for the wares consumed by this production program. Multiple entries in {ware name} are alternatives (OR logic)).

produced_wares¶

Parameters

program_name –

the name of the production program that we want to get the produced wares for :type tribename: string

(RO) Returns a table of {ware name, ware amount} for the wares produced by this production program

recruited_workers¶

Parameters

program_name –

the name of the production program that we want to get the recruited workers for :type tribename: string

(RO) Returns a table of {worker name, worker amount} for the workers recruited by this production program

MilitarySiteDescription¶

class wl.map.MilitarySiteDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription

A static description of a tribe’s militarysite, so it can be used in help files without having to access an actual building on the map. A militarysite can garrison and heal soldiers, and it will expand your territory. See the parent classes for more properties.

heal_per_second¶: (RO) The number of health healed per second by the militarysite

max_number_of_soldiers¶: (RO) The number of soldiers that can be garrisoned at the militarysite

TrainingSiteDescription¶

class wl.map.TrainingSiteDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription, ProductionSiteDescription

A static description of a tribe’s trainingsite, so it can be used in help files without having to access an actual building on the map. 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.

food_attack¶

(RO) A table of tables with food ware names used for Attack training,: e.g. {{“barbarians_bread”}, {“fish”, “meat”}}

food_defense¶

(RO) A table of tables with food ware names used for Defense training,: e.g. {{“barbarians_bread”}, {“fish”, “meat”}}

food_evade¶

(RO) A table of tables with food ware names used for Evade training,: e.g. {{“barbarians_bread”}, {“fish”, “meat”}}

food_health¶

(RO) A table of tables with food ware names used for Health training,: e.g. {{“barbarians_bread”}, {“fish”, “meat”}}

max_attack¶: (RO) The number of attack points that a soldier can train

max_defense¶: (RO) The number of defense points that a soldier can train

max_evade¶: (RO) The number of evade points that a soldier can train

max_health¶: (RO) The number of health points that a soldier can train

max_number_of_soldiers¶: (RO) The number of soldiers that can be garrisoned at the trainingsite

min_attack¶: (RO) The number of attack points that a soldier starts training with

min_defense¶: (RO) The number of defense points that a soldier starts training with

min_evade¶: (RO) The number of evade points that a soldier starts training with

min_health¶: (RO) The number of health points that a soldier starts training with

weapons_attack¶: (RO) A table with weapon ware names used for Attack training

weapons_defense¶: (RO) A table with weapon ware names used for Defense training

weapons_evade¶: (RO) A table with weapon ware names used for Evade training

weapons_health¶: (RO) A table with weapon ware names used for Health training

WarehouseDescription¶

class wl.map.WarehouseDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription

A static description of a tribe’s warehouse, so it can be used in help files without having to access an actual building on the map. Note that headquarters are also warehouses. A warehouse keeps people, animals and wares. See the parent classes for more properties.

heal_per_second¶: (RO) The number of health healed per second by the warehouse

MarketDescription¶

class wl.map.MarketDescription¶

Child of: MapObjectDescription, ImmovableDescription, BuildingDescription

A static description of a tribe’s market, so it can be used in help files without having to access an actual building on the map. A Market is used for trading over land with other players. See the parent classes for more properties.

ShipDescription¶

class wl.map.ShipDescription¶

Child of: MapObjectDescription

A static description of a tribe’s ship, so it can be used in help files without having to access an actual instance of the ship on the map. See also MapObjectDescription for more properties.

WareDescription¶

class wl.map.WareDescription¶

Child of: MapObjectDescription

A static description of a tribe’s ware, so it can be used in help files without having to access an actual instance of the ware on the map. See also MapObjectDescription for more properties.

consumers(tribename)¶

Returns a list of buildings for the ‘tribe’ that consume this ware. Loads the tribe if it hasn’t been loaded yet.

Parameters: tribename (string) – the name of the tribe that this ware gets checked for

(RO) An array with LuaBuildingDescription with buildings that need this ware for their production.

is_construction_material(tribename)¶

Parameters: tribename (string) – the name of the tribe that this ware gets checked for

(RO) A bool that is true if this ware is used by the tribe’s construction sites.

producers(tribename)¶

Returns a list of buildings for the ‘tribe’ that produce this ware. Loads the tribe if it hasn’t been loaded yet.

Parameters: tribename (string) – the name of the tribe that this ware gets checked for

(RO) An array with LuaBuildingDescription with buildings that can procude this ware.

WorkerDescription¶

class wl.map.WorkerDescription¶

Child of: MapObjectDescription

A static description of a tribe’s worker, so it can be used in help files without having to access an actual instance of the worker on the map. See also MapObjectDescription for more properties.

becomes¶: (RO) The WorkerDescription of the worker this one will level up to or nil if it never levels up.

buildcost¶: (RO) a list of building requirements, e.g. {“atlanteans_carrier”, “ax”}

employers¶: (RO) An array with LuaBuildingDescription with buildings where this worker can be employed.

buildable¶: (RO) returns true if this worker is buildable

needed_experience¶: (RO) the experience the worker needs to reach this level.

SoldierDescription¶

class wl.map.SoldierDescription¶

Child of: MapObjectDescription, WorkerDescription

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.

get_max_health_level¶: (RO) The maximum health level that the soldier can have.

max_attack_level¶: (RO) The maximum attack level that the soldier can have.

max_defense_level¶: (RO) The maximum defense level that the soldier can have.

max_evade_level¶: (RO) The maximum evade level that the soldier can have.

get_base_health¶: (RO) The health points that the soldier starts with

base_min_attack¶: (RO) The minimum random attack points that get added to a soldier’s attack

base_max_attack¶: (RO) The maximum random attack points that get added to a soldier’s attack

base_defense¶: (RO) The defense % that the soldier starts with

base_evade¶: (RO) The evade % that the soldier starts with

get_health_incr_per_level¶: (RO) The health points that the soldier will gain with each level.

attack_incr_per_level¶: (RO) The attack points that the soldier will gain with each level.

defense_incr_per_level¶: (RO) The defense % that the soldier will gain with each level.

evade_incr_per_level¶: (RO) The evade % that the soldier will gain with each level.

ResourceDescription¶

class wl.map.ResourceDescription¶

A static description of a resource.

name¶: (RO) the string internal name of this resource

descname¶: (RO) the string display name of this resource

is_detectable¶: (RO) true if geologists can find this resource

max_amount¶: (RO) the maximum amount of this resource that a terrain can have

representative_image¶: (RO) the string path to the image representing this resource in the GUI

editor_image(amount)¶

Parameters

amount –

The amount of the resource what we want an overlay image for

(RO) the string path to the image representing the specified amount of this resource

TerrainDescription¶

class wl.map.TerrainDescription¶

A static description of a terrain.

name¶: (RO) the string internal name of this terrain

descname¶: (RO) the string display name of this terrain

get_default_resource¶: (RO) the wl.map.ResourceDescription for the default resource provided by this terrain, or nil if the terrain has no default resource.

default_resource_amount¶: (RO) the int amount of the default resource provided by this terrain.

fertility¶: (RO) the uint fertility value for this terrain

humidity¶: (RO) the uint humidity value for this terrain

representative_image¶: (RO) the string file path to a representative image

temperature¶: (RO) the uint temperature value for this terrain

valid_resources¶: (RO) a list of wl.map.ResourceDescription with all valid resources for this terrain.

Economy¶

class wl.map.LuaEconomy¶

Provides access to an economy. A player can have multiple economies; you can get an economy from a Flag.

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.

Parameters: name (string) – the name of the ware or worker.

set_target_quantity(name)¶

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.

Parameters

workername (string) – the name of the worker type.
amount (integer) – the new target amount for the worker. Needs to be >= 0.

MapObject¶

class wl.map.MapObject¶

This is the base class for all objects in Widelands, including immovables and bobs. This class can’t be instantiated directly, but provides the base for all others.

More properties are available through this object’s MapObjectDescription, which you can access via MapObject.descr.

__hash¶: (RO) The map object’s serial. Used to identify a class in a Set.

serial¶: (RO) The serial number of this object. Note that this value does not stay constant after saving/loading.

descr¶: (RO) The description object for this immovable, e.g. BuildingDescription.

remove()¶: Removes this object immediately. If you want to destroy an object as if the player had see destroy().

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

has_attribute(string)¶: returns true, if the map object has this attribute, else false

BaseImmovable¶

class wl.map.BaseImmovable¶

Child of: MapObject

This is the base class for all immovables in Widelands.

More properties are available through this object’s ImmovableDescription, which you can access via MapObject.descr.

fields¶: (RO) An array of 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¶

class wl.map.PlayerImmovable¶

Child of: BaseImmovable

All Immovables that belong to a Player (Buildings, Flags, …) are based on this Class.

More properties are available through this object’s ImmovableDescription, which you can access via MapObject.descr.

owner¶: (RO) The wl.game.Player who owns this object.

Flag¶

class wl.map.Flag¶

Child of: PlayerImmovable, HasWares

One flag in the economy of this Player.

More properties are available through this object’s ImmovableDescription, which you can access via MapObject.descr.

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 Economy associated with the flag to handle wares.

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 Economy associated with the flag to handle workers.

roads¶

(RO) Array of roads leading to the flag. Directions can be tr,r,br,bl,l and tl Note that waterways are currently treated like roads.

Returns: The array of ‘direction:road’, if any

building¶: (RO) building belonging to the flag

Road¶

class wl.map.Road¶

Child of: PlayerImmovable, HasWorkers

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

More properties are available through this object’s ImmovableDescription, which you can access via MapObject.descr.

length¶: (RO) The length of the roads in number of edges.

start_flag¶: (RO) The flag were this road starts

end_flag¶: (RO) The flag were this road ends

road_type¶

(RO) Type of road. Can be any either of:

normal
busy
waterway

PortDock¶

class wl.map.PortDock¶

Child of: PlayerImmovable

Each 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 ImmovableDescription, which you can access via MapObject.descr.

Building¶

class wl.map.Building¶

Child of: PlayerImmovable

This represents a building owned by a player.

More properties are available through this object’s BuildingDescription, which you can access via MapObject.descr.

flag¶: (RO) The flag that belongs to this building (that is to the bottom right of it’s main location).

ConstructionSite¶

class wl.map.ConstructionSite¶

Child of: Building

A ConstructionSite as it appears in Game. This is only a minimal wrapping at the moment.

More properties are available through this object’s ConstructionSiteDescription, which you can access via MapObject.descr.

building¶: (RO) The name of the building that is constructed here

Warehouse¶

class wl.map.Warehouse¶

Child of: Building, HasWares, HasWorkers, HasSoldiers

Every Headquarter, Port or Warehouse on the Map is of this type.

More properties are available through this object’s WarehouseDescription, which you can access via MapObject.descr.

portdock¶: (RO) If this Warehouse is a port, returns the PortDock attached to it, otherwise nil.

expedition_in_progress¶: (RO) If this Warehouse is a port, and an expedition is in progress, returns true, otherwise nil

set_warehouse_policies(which, policy)¶

Sets the policies how the warehouse should handle the given wares and workers.

Usage example:

wh:set_warehouse_policies("coal", "prefer")

Parameters

which – behaves like for HasWares.get_wares().
policy (a string out of "normal", "prefer", "dontstock", "remove".) – the policy to apply for all the wares and workers given in which.

get_warehouse_policies(which)¶

Gets the policies how the warehouse should handle the given wares and workers. The method to handle is one of the strings “normal”, “prefer”, “dontstock”, “remove”.

Usage example:

wh:get_warehouse_policies({"ax", "coal"})
-- Returns a table like {ax="normal", coal="prefer"}

Parameters: which – behaves like for HasWares.get_wares().
Returns: string or table

start_expedition()¶: Starts preparation for expedition

cancel_expedition()¶: Cancels an expedition if in progress

ProductionSite¶

class wl.map.ProductionSite¶

Child of: Building, HasInputs, HasWorkers

Every building that produces anything.

More properties are available through this object’s ProductionSiteDescription, which you can access via MapObject.descr.

is_stopped¶

(RO) Returns whether this productionsite is currently active or stopped

Returns: true if the productionsite has been started, false if it has been stopped.

productivity¶

(RO) Returns the building’s current productivity percentage

Returns: A number between 0 and 100.

toggle_start_stop()¶: If ProductionSite.is_stopped, sends a command to start this productionsite. Otherwise, sends a command to stop this productionsite.

Market¶

class wl.map.Market¶

Child of: Building, HasWares, HasWorkers

A Market used for trading with other players.

More properties are available through this object’s MarketDescription, which you can access via MapObject.descr.

propose_trade(other_market, num_batches, items_to_send, items_to_receive)¶

TODO(sirver,trading): document

Returns: nil

MilitarySite¶

class wl.map.MilitarySite¶

Child of: Building, HasSoldiers

Miltary Buildings

More properties are available through this object’s MilitarySiteDescription, which you can access via MapObject.descr.

TrainingSite¶

class wl.map.TrainingSite¶

Child of: ProductionSite, HasSoldiers

A specialized production site for training soldiers.

More properties are available through this object’s TrainingSiteDescription, which you can access via MapObject.descr.

Bob¶

class wl.map.Bob¶

Child of: MapObject

This is the base class for all Bobs in widelands.

More properties are available through this object’s MapObjectDescription, which you can access via MapObject.descr.

field¶: (RO) The field the bob is located on

has_caps(capname)¶

Similar to Field::has_caps().

Parameters: capname – can be either of

swims: This bob can swim.
walks: This bob can walk.

Ship¶

class wl.map.Ship¶

This represents a ship in game.

More properties are available through this object’s MapObjectDescription, which you can access via MapObject.descr.

destination¶: (RO) Either nil if there is no current destination, otherwise the PortDock.

last_portdock¶: (RO) Either nil if no port was ever visited or the last portdock was destroyed, otherwise the PortDock of the last visited port.

state¶

Query which state the ship is in:

transport,
exp_waiting, exp_scouting, exp_found_port_space, exp_colonizing,
sink_request, sink_animation

(RW) returns the string ship’s state, or nil if there is no valid state.

island_explore_direction¶: (RW) actual direction if the ship sails around an island. Sets/returns cw, ccw or nil

shipname¶

Get name of ship:

(RO) returns the string ship’s name.

capacity¶

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.

(RW) returns the current capacity of this ship

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 "" as argument, returns an array with the names of all loaded wares.

Returns: the number of wares or an array of string

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 "" as argument, returns an array with all loaded workers.

Returns: the number of workers or an array of Worker

build_colonization_port()¶

Returns true if port space construction was started (ship was in adequate status and a found portspace was nearby)

Returns: true/false

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. Any items previously present in the ship will be deleted.

The ship must be empty and not an expedition ship when this method is called.

Returns: nil

Worker¶

class wl.map.Worker¶

Child of: Bob

All workers that are visible on the map are of this kind.

More properties are available through this object’s WorkerDescription, which you can access via MapObject.descr.

owner¶: (RO) The wl.game.Player who owns this worker.

location¶: (RO) The location where this worker is situated. This will be either a Building, Road, Flag or nil. Note that a worker that is stored in a warehouse has a location 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.

Soldier¶

class wl.map.Soldier¶

Child of: Worker

All soldiers that are on the map are represented by this class.

More properties are available through this object’s SoldierDescription, which you can access via MapObject.descr.

attack_level¶: (RO) The current attack level of this soldier

defense_level¶: (RO) The current defense level of this soldier

health_level¶: (RO) The current health level of this soldier

evade_level¶: (RO) The current evade level of this soldier

Field¶

class wl.map.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.

__hash¶: (RO) The hashed coordinates of the field’s position. Used to identify a class in a Set.

x, y: (RO) The x/y coordinate of this field

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 raw_height instead and then call recalculate afterwards.

raw_height¶: (RW) The same as 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 recalculate to make sure that everything is in order.

viewpoint_x, viewpoint_y: (RO) Returns the position in pixels to move the view to to center this field for the current interactive player

resource¶

(RW) The name of the resource that is available in this field or “none”

See also: resource_amount

resource_amount¶

(RW) How many items of the resource is available in this field.

See also: resource

initial_resource_amount¶

(RO) Starting value of resource. It is set be resource_amount

See also: resource

immovable¶: (RO) The immovable that stands on this field or nil. If you want to remove an immovable, you can use wl.map.MapObject.remove().

bobs¶: (RO) An array of Bob that are associated with this field

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 recalculate_seafaring after you’re done changing terrains.

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:

wl.map.Field(wl.map.get_width()-1, 10).rn == wl.map.Field(0, 10)

owner¶: (RO) The current owner of the field or nil if noone owns it. See also claimers.

buildable¶: (RO) Returns true if a flag or building could be built on this field, independently of whether anybody currently owns this field.

has_roads¶

(RO) Whether any roads lead to the field. Note that waterways are currently treated like roads.

Returns: true if any of the 6 directions has a road on it, false otherwise.

claimers¶

(RO) An 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 owner.

region(r1[, r2])¶

Returns an 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:

f:region(1)

will return an array with the following entries (Note: Ordering of the fields inside the array is not guaranteed):

{f, f.rn, f.ln, f.brn, f.bln, f.tln, f.trn}

Returns: The array of the given fields.
Return type: array

has_caps(capname)¶

Returns true if the field has this caps associated with it, otherwise returns false. Note: Immovables will hide the caps. If you want to have the caps without immovables use has_max_caps instead

Parameters: capname – can be either of

small: Can a small building be built here?
medium: Can a medium building be built here?
big: Can a big building be built here?
mine: Can a mine be built here?
port: Can a port be built here?
flag: Can a flag be built here?
walkable: Is this field passable for walking bobs?
swimmable: Is this field passable for swimming bobs?

has_max_caps(capname)¶

Returns true if the field has this maximum caps (not taking immovables into account) associated with it, otherwise returns false.

Parameters: capname – can be either of

small: Can a small building be built here?
medium: Can a medium building be built here?
big: Can a big building be built here?
mine: Can a mine be built here?
port: Can a port be built here?
flag: Can a flag be built here?
walkable: Is this field passable for walking bobs?
swimmable: Is this field passable for swimming bobs?

indicate(on)¶

Show/Hide an arrow that points to this field. You can only point to 1 field at the same time.

Parameters: on (boolean) – Whether to show or hide the arrow

PlayerSlot¶

class wl.map.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.

tribe_name¶: (RO) The name of the tribe suggested for this player in this map

name¶: (RO) The name for this player as suggested in this map

starting_field¶: (RO) 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.

wl.map¶

Module Interfaces¶

HasWares¶

HasInputs¶

HasWorkers¶

HasSoldiers¶

Module Classes¶

Map¶

TribeDescription¶

MapObjectDescription¶

ImmovableDescription¶

BuildingDescription¶

ConstructionSiteDescription¶

DismantleSiteDescription¶

ProductionSiteDescription¶

MilitarySiteDescription¶

TrainingSiteDescription¶

WarehouseDescription¶

MarketDescription¶

ShipDescription¶

WareDescription¶

WorkerDescription¶

SoldierDescription¶

ResourceDescription¶

TerrainDescription¶

Economy¶

MapObject¶

BaseImmovable¶

PlayerImmovable¶

Flag¶

Road¶

PortDock¶

Building¶

ConstructionSite¶

Warehouse¶

ProductionSite¶

Market¶

MilitarySite¶

TrainingSite¶

Bob¶

Ship¶

Worker¶

Soldier¶

Field¶

PlayerSlot¶

`wl.map`¶