`wl.map`¶

Common functions¶

Some map objects share the same functions and attributes:

Common properties for objects with ware storage

Common properties for objects requiring workers

Common properties for objects garrisoning soldiers

Common properties for objects requiring production inputs

Common properties for objects with ware storage¶

Functions for objects which can store wares. Supported at the time of this writing by Flag and Warehouse.

For objects which consume wares, see: Common properties for objects requiring production inputs.

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

wl.map.MapObject.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 a table of {ware_name=amount}` pairs.
amount (integer) – This many units will be available after the call.

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

Common properties for objects requiring production inputs¶

Supported at the time of this writing by ProductionSite and 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: Common properties for objects requiring workers.

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

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

wl.map.MapObject.valid_inputs¶

(RO) A table of {ware/worker_name=amount} 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

wl.map.MapObject.set_priority(ware, prio[, cs_setting = false])¶

Sets the priority for the given ware inputqueue.

Parameters

ware (string) – ware name
prio (string) – The new priority. One of "very_low", "low", "normal", "high", or "very_high".
cs_setting (bool) – Only valid for productionsite-constructionsites. If true, refers to the settings to apply after construction.

wl.map.MapObject.get_priority(ware[, cs_setting = false])¶

Returns the priority for the given ware inputqueue. See also set_priority().

Parameters

ware (string) – A ware name.
cs_setting (bool) – Only valid for productionsite-constructionsites. If true, refers to the settings to apply after construction.

Returns

string

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

Parameters

item (string) – Ware or worker name.
fill (integer) – The desired fill.
cs_setting (bool) – Only valid for productionsite-constructionsites. If true, refers to the settings to apply after construction.

wl.map.MapObject.get_desired_fill(item, fill[, cs_setting = false])¶

Returns the desired fill for the given ware or worker inputqueue. See also set_desired_fill().

Parameters

item (string) – Ware or worker name.
cs_setting (bool) – Only valid for productionsite-constructionsites. If true, refers to the settings to apply after construction.

Returns

integer

Common properties for objects requiring 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. For workers which are consumed, see: Common properties for objects requiring production inputs.

wl.map.MapObject.get_workers(which)¶: Similar to wl.map.MapObject.get_wares().

wl.map.MapObject.set_workers(which[, amount])¶: Similar to wl.map.MapObject.set_wares().

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

Common properties for objects garrisoning soldiers¶

Supported at the time of this writing by Warehouse, MilitarySite and TrainingSite.

wl.map.MapObject.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 an array that contains the level for health, attack, defense and evade (in this order). A usage example:
building: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:

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 table containing all soldiers
Return type: integer or table.

wl.map.MapObject.set_soldiers(which[, amount])¶

Analogous to wl.map.MapObject.set_workers(), but for soldiers. Instead of a name an array is used to define the soldier. See below for an example.

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.

Usage example:

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

would add 100 level 0 soldiers. While

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

wl.map.MapObject.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 a PlayerSlot 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.

Parameters: immovable_attribute (string) – Optional: If this is set, only count fields that have an immovable with the given attribute.
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.

Parameters: number (integer) – 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 (integer) – The x coordinate of the port space to set/unset.
y (integer) – 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

Returns

true if a sea route exists, or false otherwise

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 BuildingDescription with all the buildings that the tribe can use, casted to their appropriate subclasses.

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

carriers¶: New in version 1.1.

(RO) An array of the internal names of the carrier types that this tribe uses as string.

carrier¶: Deprecated since version 1.1: Use carriers instead.

(RO) The internal name of the carrier type that this tribe uses as string.

carrier2¶: Deprecated since version 1.1: Use carriers instead.

(RO) The internal name of the secondary carrier type that this tribe uses as string.

ferry¶: (RO) The internal name of the ferry type that this tribe uses as string.

descname¶: (RO) The localized name of the tribe as string

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

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

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

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.

name¶: (RO) The internal name of the tribe as string.

directory¶: (RO) The path of the tribe’s initialization scripts as string.

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

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

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

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

workers¶: (RO) an array of WorkerDescription 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 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 Descriptions or EditorGameBase.

Accessing the descriptions of this class during a game is done via the class MapObject and the attribute MapObject.descr.

descname¶: (RO) The map object’s localized name as string

icon_name¶: (RO) The filename for the menu icon as string

name¶: (RO) The map object’s internal name as string

type_name¶

(RO) The map object’s type as 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. 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:
- bob, the abstract base type for all bobs. For properties see MapObjectDescription.
- critter, animals that aren’t controlled by any tribe. For properties see MapObjectDescription.
- 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. For properties see WorkerDescription.
- ferry, a specialized carrier for carrying items along a waterway. For properties see WorkerDescription.
- 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 types 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. For properties see MapObjectDescription.
  - roadbase, the abstract base type for roads and waterways. For properties see MapObjectDescription.
  - road, a road connecting two flags. For properties see MapObjectDescription.
  - waterway, a waterway connecting two flags. For properties see MapObjectDescription.
  - 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 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.
- battle, holds information about two soldiers in a fight,
- ship_fleet, holds information for managing ships and ports,
- ferry_fleet, holds information for managing ferries and waterways.

Example to fetch some information from a tribe’s description:

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

helptexts(tribename)¶

(RO) Returns a table of helptexts if it exists for the given tribe, an empty table otherwise.

Keys are lore, lore_author, purpose, note, performance, all of them optional. The table may contain other keys as well.

Parameters: tribename (string) – 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. See also MapObjectDescription for more properties.

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

buildcost¶: (RO) A table of {ware=amount} pairs, describing the build cost for the immovable.

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

terrain_affinity¶

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

E.g. for a beech this will be:

{
   preferred_humidity = 400,
   preferred_temperature = 110,
   preferred_fertility = 600,
   pickiness = 60
}

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, flags or small sized buildings
medium – Example: Medium sized buildings
big – Example: Big sized buildings or rocks

has_attribute(attribute_name)¶

Returns true if the immovable has the attribute, false otherwise.

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

probability_to_grow(terrain_description)¶

Returns a double describing the probability that this immovable will grow on the given terrain. Returns nil if this immovable has no terrain affinity.

Note that floating-point arithmetic is platform-dependent. Using double values to make any decisions in the script logic might result in desyncs.

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

BuildingDescription¶

class wl.map.BuildingDescription¶

Child of: 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.

buildcost¶: (RO) A table 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) The BuildingDescription that this was enhanced from, or nil if this isn’t an enhanced building.

enhancement_cost¶: (RO) A table of {warename=cost} for enhancing to this building type.

enhancement¶: (RO) The BuildingDescription 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 as a string. Can be either of

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

returns_on_dismantle¶: (RO) A table of {warename=amount} pairs returned upon dismantling.

enhancement_returns_on_dismantle¶: (RO) A table of {warename=amount} pairs returned upon dismantling an enhanced building.

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

workarea_radius¶: (RO) The first workarea_radius of the building as an integer, nil in case bulding has no workareas.

ConstructionSiteDescription¶

class wl.map.ConstructionSiteDescription¶

Child of: BuildingDescription, MapObjectDescription

A static description of a tribe’s constructionsite. See the parent classes for more properties.

DismantleSiteDescription¶

class wl.map.DismantleSiteDescription¶

Child of: BuildingDescription, MapObjectDescription

A static description of a tribe’s dismantlesite. See the parent classes for more properties.

ProductionSiteDescription¶

class wl.map.ProductionSiteDescription¶

Child of: BuildingDescription, MapObjectDescription

A static description of a tribe’s productionsite.

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 of 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 of 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 of 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:

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

and for a Barbarian Coal Mine this will be:

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

created_immovables¶: (RO) An array of 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 of 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 of ResourceDescription containing the resources that this building will place on the map. For example, a Fishbreeder’s House will create the resource fish.

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

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

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

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(program_name)¶

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

Parameters: program_name (string) – The name of the production program that we want to get the consumed wares for. See production site programs.

E.g. this will return for an atlanteans coalmine and the corresponding program:

{
  1, {smoked_meat, 2}, {smoked_fish, 2}  -- 2 smoked_meat OR 2 smoked_fish
  2, {atlanteans_bread, 2}               -- AND 2 atlanteans_bread
}

produced_wares(program_name)¶

Returns a table of {ware_name=ware_amount} for the wares produced by this production program. See production site programs.

Parameters: program_name (string) – The name of the production program that we want to get the produced wares for.

recruited_workers(program_name)¶

Returns a table of {worker_name=worker_amount} for the workers recruited by this production program. See production site programs.

Parameters: program_name (string) – the name of the production program that we want to get the recruited workers for.

MilitarySiteDescription¶

class wl.map.MilitarySiteDescription¶

Child of: BuildingDescription, 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.

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: ProductionSiteDescription, BuildingDescription, 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.

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.

trained_soldiers(program_name)¶

Returns a table with following entries [1] = the trained skill, [2] = the starting level,

[3] = the resulting level trained by this production program. See production site programs.

arg program_name: the name of the production program that we want to get the trained soldiers for.
type program_name: string

WarehouseDescription¶

class wl.map.WarehouseDescription¶

Child of: BuildingDescription, 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.

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

ShipDescription¶

class wl.map.ShipDescription¶

Child of: MapObjectDescription

A static description of a tribe’s ship. See also MapObjectDescription for more properties.

WareDescription¶

class wl.map.WareDescription¶

Child of: MapObjectDescription

A static description of a ware. See the parent class for more properties.

consumers(tribename)¶

(RO) Returns an array with BuildingDescription with buildings that need this ware for their production. Loads the tribe if it hasn’t been loaded yet.

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

is_construction_material(tribename)¶

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

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

producers(tribename)¶

(RO) Returns an array with BuildingDescription with buildings that can 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.

WorkerDescription¶

class wl.map.WorkerDescription¶

Child of: MapObjectDescription

A static description of a tribe’s worker. See the parent class 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. for an atlateans woodcutter this is {"atlanteans_carrier","saw"}.

employers¶: (RO) An array with BuildingDescription 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: WorkerDescription, 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.

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.

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

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 internal name of this resource as string.

descname¶: (RO) The display name of this resource as string.

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 path to the image representing this resource in the GUI as string.

editor_image(amount)¶

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

Parameters: amount (integer) – The amount of the resource what we want an overlay image for.

TerrainDescription¶

class wl.map.TerrainDescription¶

A static description of a terrain.

name¶: (RO) The internal name of this terrain as string.

descname¶: (RO) The localized name of this terrain as string.

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 amount of the default resource provided by this terrain as integer.

fertility¶

(RO) The fertility value for this terrain.

humidity¶

(RO) The humidity value for this terrain.

representative_image¶: (RO) The file path to a representative image as string.

temperature¶

(RO) The temperature value for this terrain.

Economy¶

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

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.

__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 MapObjectDescription for this immovable.

local immovable = wl.Game().map:get_field(20,31).immovable

-- always check if the immovable still exists
if immovable then
   if immovable.descr.type_name == "warehouse"  -- access MapObjectDescription
      immovable:set_wares("log", 5)
   end
end

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(attribute)¶

Returns true if the map object has this attribute, false otherwise.

Parameters: attribute (string) – The attribute to check for.

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 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¶

class wl.map.PlayerImmovable¶

Child of: BaseImmovable, MapObject

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, BaseImmovable, MapObject

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) The roads which are connected to this flag, if any.

Note that waterways are currently treated like roads.

Returns: A table with directions as keys. Directions can be "tr", "r", "br", "bl", "l" and "tl". If this flag has no roads, the table will be empty.

building¶: (RO) The building belonging to the flag, if any.

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.

Parameters: flag (Flag) – The flag to find.
Returns: The distance of the flags in walking time or nil if no path exists.

send_geologist()¶: Send a geologist to explore the surroundings of this flag.

Road¶

class wl.map.Road¶

Child of: PlayerImmovable, BaseImmovable, 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 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, BaseImmovable, MapObject

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, BaseImmovable, MapObject

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

destruction_blocked¶: (RW) Whether the player is forbidden to dismantle or destroy this building.

dismantle([keep_wares = false])¶

Instantly turn this building into a dismantlesite.

Parameters: keep_wares (bool) – Optional: If false (default) the wares in this buildings stock get destroyed. If true the wares in this buildings stock will be preserved.

enhance([keep_wares = false])¶

New in version 1.1.

Instantly enhance this building if there is an enhancement.

Parameters: keep_wares (bool) – Optional: If false (default) the wares in this buildings stock get destroyed. If true the wares in this buildings stock will be preserved.

ConstructionSite¶

class wl.map.ConstructionSite¶

Child of: Building, PlayerImmovable, BaseImmovable, MapObject

A construction site as it appears in the game.

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

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

has_builder¶: (RW) true if this constructionsite has a builder. Changing this setting causes the worker to be instantly deleted or to be created from thin air.

setting_launch_expedition¶: (RW) Only valid for ports under construction. true if an expedition will be launched immediately upon completion.

setting_stopped¶: (RW) Only valid for productionsites and trainingsites under construction. true if this building will be initially stopped after completion.

setting_soldier_preference¶: (RW) Only valid for militarysites under construction. "heroes" if this site will prefer heroes after completion; "rookies" otherwise.

setting_soldier_capacity¶: (RW) Only valid for militarysites and trainingsites under construction. The desired number of soldiers stationed here after completion as integer.

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.

Parameters: wareworker (string) – The set ware or worker stock policy in this warehouse.

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 Warehouse.set_warehouse_policies().

DismantleSite¶

class wl.map.DismantleSite¶

Child of: Building, PlayerImmovable, BaseImmovable, MapObject

A dismantle site as it appears in the game.

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

has_builder¶: (RW) 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¶

class wl.map.Warehouse¶

Child of: Building, PlayerImmovable, BaseImmovable, MapObject

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

See also:

Common properties for objects with ware storage
Common properties for objects requiring workers
Common properties for objects garrisoning soldiers

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, this is true, otherwise nil.

set_warehouse_policies(which, policy)¶

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

Parameters

which (string or table) – Behaves like wl.map.MapObject.get_wares().
policy (A string out of "normal", "prefer", "dontstock" or "remove") – The policy to apply for all the wares and workers given in which.

Usage examples:

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

get_warehouse_policies(which)¶

Returns the policies how the warehouse should handle the given wares and workers. See Warehouse.set_warehouse_policies() for policy strings.

Parameters: which (string or array) – Behaves like wl.map.MapObject.get_wares().
Returns: string or table

Usage example:

wh:get_warehouse_policies("log")
   -- Returns e.g. "normal"

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

start_expedition()¶: Starts preparation for an expedition.

cancel_expedition()¶: Cancels an expedition if in progress.

ProductionSite¶

class wl.map.ProductionSite¶

Child of: Building, PlayerImmovable, BaseImmovable, MapObject

Every building that produces anything.

See also:

Common properties for objects requiring production inputs
Common properties for objects requiring workers

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: false if the productionsite has been started, true 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.

MilitarySite¶

class wl.map.MilitarySite¶

Child of: Building, PlayerImmovable, BaseImmovable, MapObject

Military buildings with stationed soldiers.

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

capacity¶: (RW) The number of soldiers meant to be stationed here.

soldier_preference¶: (RW) "heroes" if this site prefers heroes; "rookies" otherwise.

TrainingSite¶

class wl.map.TrainingSite¶

Child of: ProductionSite, Building, PlayerImmovable, BaseImmovable, MapObject

A specialized production site for training soldiers.

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

capacity¶: (RW) The number of soldiers meant to be stationed here.

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(swim_or_walk)¶

(RO) Whether this bob can swim or walk.

Parameters: swim_or_walk (string) – Can be either of "swims" or "walks".
Returns: true if this bob is able to swim_or_walk, otherwise false.

Ship¶

class wl.map.Ship¶

Child of: Bob, MapObject

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¶

(RO) Query which state the ship is in. Can be either of:

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

Returns: The ship’s state as string, or nil if there is no valid state.

island_explore_direction¶: (RW) Actual direction if the ship sails around an island. Sets/returns "cw" (clockwise), "ccw" (counter clock wise) or nil.

shipname¶

(RO) The name of the ship as string.

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.

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 nearby).

Returns: true or 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. The ship must be empty and not an expedition ship when this method is called.

Note that the ships 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 launch_expeditions which adjusts capacity depending on the given wares and workers.

Parameters: items (table of {ware_or_worker=amount} pairs.) – Optional: Additional items to the ones that are needed to build a port.
Returns: nil

Example with check for sufficient capacity:

-- 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})

Worker¶

class wl.map.Worker¶

Child of: Bob, MapObject

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, Bob, MapObject

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

current_health¶: (RW) This soldier’s current number of hitpoints left.

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 capname 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 (string) – 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 (string) – For possible values see has_caps()

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¶

Common functions¶

Common properties for objects with ware storage¶

Common properties for objects requiring production inputs¶

Common properties for objects requiring workers¶

Common properties for objects garrisoning soldiers¶

Module Classes¶

Map¶

TribeDescription¶

MapObjectDescription¶

ImmovableDescription¶

BuildingDescription¶

ConstructionSiteDescription¶

DismantleSiteDescription¶

ProductionSiteDescription¶

MilitarySiteDescription¶

TrainingSiteDescription¶

WarehouseDescription¶

ShipDescription¶

WareDescription¶

WorkerDescription¶

SoldierDescription¶

ResourceDescription¶

TerrainDescription¶

Economy¶

MapObject¶

BaseImmovable¶

PlayerImmovable¶

Flag¶

Road¶

PortDock¶

Building¶

ConstructionSite¶

DismantleSite¶

Warehouse¶

ProductionSite¶

MilitarySite¶

TrainingSite¶

Bob¶

Ship¶

Worker¶

Soldier¶

Field¶

PlayerSlot¶

`wl.map`¶