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 writingFlag
andWarehouse
.-
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.
- the string
- 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 ofgranite
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 arenil
.
- an
- Returns
integer
ortable
-
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
ortable
) – name of ware or (ware_name, amount) tableamount (
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 aProductionSite
this is the information what wares and how much can be stored as inputs. For unconstrained storage (likeWarehouse
) this isnil
.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 areProductionSite
andTrainingSite
. This interface is similar toHasWares
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.
- the string
- 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 ofgranite
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 arenil
.
- an
- Returns
integer
ortable
-
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
ortable
) – name of ware/worker or (ware/worker name, amount) tableamount (
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 aProductionSite
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 byRoad
,Warehouse
andProductionSite
. 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 ofHasInputs
.-
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 thanHasWorkers
. Supported at the time of this writing byWarehouse
,MilitarySite
andTrainingSite
.-
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
- the string
- Returns
Number of soldiers that match descr or the
table
containing all soldiers- Return type
integer
ortable
.
-
set_soldiers
(which[, amount])¶ Analogous to
HasWorkers.set_workers()
, but for soldiers. Instead of a name aarray
is used to define the soldier. Seeget_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
orarray
.) – either a table of (description, count) pairs or one description. In that case amount has to be specified as well.
-
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 containsPlayerSlots
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
ofwl.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 createfield (
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, orfalse
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 startport (
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’
- (RO) the
-
ferry
¶ - (RO) the
string
internal name of the ferry type that this tribe uses. e.g. ‘atlanteans_ferry’
- (RO) the
-
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.
- (RO) an array of
-
has_building
(buildingname)¶ Returns true if buildingname is a building and the tribe can use it.
- Returns
true
orfalse
- Return type
bool
-
has_ware
(warename)¶ Returns true if warename is a ware and the tribe uses it.
- Returns
true
orfalse
- Return type
bool
-
has_worker
(workername)¶ Returns true if workername is a worker and the tribe can use it.
- Returns
true
orfalse
- 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 ageneral map object
, and acarrier
is aworker
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 shipsImmovables: 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 buildingsconstructionsite
, 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 alsoMapObjectDescription
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 whensomething else is built on this field.
small
– Example: trees or flagsmedium
– Example: Medium sized buildingsbig
– 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 buildingsmedium
– Medium sized buildingsbig
– 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 ornil
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
andbobs
. 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 viaMapObject.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 viaMapObject.descr
.
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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.descr
.-
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
ortable
-
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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.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 viaMapObject.descr
.-
last_portdock
¶ (RO) Either
nil
if no port was ever visited or the last portdock was destroyed, otherwise thePortDock
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, ornil
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
ofstring
-
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
ofWorker
-
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 viaMapObject.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
ornil
. Note that a worker that is stored in a warehouse has a locationnil
. 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 viaMapObject.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 callrecalculate
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 userecalculate
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
-
initial_resource_amount
¶ (RO) Starting value of resource. It is set be resource_amount
- See also
-
immovable
¶ (RO) The immovable that stands on this field or
nil
. If you want to remove an immovable, you can usewl.map.MapObject.remove()
.
-
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)
-
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.
-