wl.bases

The wl.bases module contains Base functions on which the classes of wl.game and wl.editor are based. You will not need to create any of the functions in this module directly, but you might use their functionality via the child classes:

local map = wl.Game().map     -- the map object of a game currently running
local map = wl.Editor().map   -- the map object in the editor

Module Classes

EditorGameBase

class wl.bases.EditorGameBase

Common functionality between Editor and Game.

map

(RO) The Map, either in a game or in the editor.

players

(RO) An array with the defined players. The players are either of type wl.game.Player or wl.editor.Player.

In game, there might be less players then defined in wl.map.Map.player_slots because some slots might not be taken. Also note that for the same reason you cannot index this array with wl.bases.PlayerBase.number, but the players are ordered with increasing number in this array.

The editor always creates all players that are defined by the map.

get_immovable_description(immovable_name)

Returns the ImmovableDescription of the named immovable. To get descriptions for buildings use get_building_description().

Parameters:

immovable_name (string) – The internal name of the immovable.

immovable_exists(immovable_name)

Returns whether the descriptions know about an ImmovableDescription for the named object. This is true if the named immovable exists, false otherwise.

Parameters:

immovable_name (string) – The internal name of the immovable.

get_building_description(building_name)

Returns the description for the given building depending on the type of building. See the point Buildings in the list of type_name.

Parameters:

building_name (string) – The internal name of the building.

get_ship_description(ship_name)

Returns the ShipDescription for the given ship.

Parameters:

ship_name (string) – The name of the ship.

get_tribe_description(tribe_name)

Returns the TribeDescription of the given tribe. Loads the tribe if it hasn’t been loaded yet.

Parameters:

tribe_name (string) – The name of the tribe.

get_ware_description(ware_name)

Returns the WareDescription for the given ware.

Parameters:

ware_name (string) – The internal name of the ware.

get_worker_description(worker_name)

Returns the WorkerDescription for the given worker.

Parameters:

worker_name (string) – The internal name of the worker.

get_resource_description(resource_name)

Returns the ResourceDescription for the given resource.

Parameters:

resource_name (string) – The internal name of the resource.

get_terrain_description(terrain_name)

Returns the TerrainDescription for the given terrain.

Parameters:

terrain_name (string) – The internal name of the terrain.

save_campaign_data(campaign_name, scenario_name, data)

Saves information that can be read by other scenarios. See also read_campaign_data().

Parameters:

• campaign_name (string) – The name of the current campaign, e.g. “empiretut” or “frisians”.

• scenario_name (string) – The name of the current scenario, e.g. “emp04” or “fri03”.

• data (array or table) – If an array is used, the data will be saved in the correct order. Arrays may not contain nil values. If a table is used, all keys have to be strings. Tables may contain subtables of any depth. Cyclic dependencies will cause Widelands to crash. Values have to be of type string, integer, boolean or table.

read_campaign_data(campaign_name, scenario_name)

Reads information that was saved by save_campaign_data().

Parameters:

• campaign_name (string) – The name of the campaign, e.g. “empiretut” or “frisians”.

• scenario_name (string) – The name of the scenario that saved the data, e.g. “emp04” or “fri03”.

Returns:

The data is returned as a table of key-value pairs. The table is not guaranteed to be in any particular order, unless it is an array, in which case it will be returned in the same order as it was saved. This function returns nil if the file cannot be opened for reading.

set_loading_message(text)

Changes the progress message on the loading screen. May be used from the init.lua files for tribe/world loading only.

Parameters:

text (string) – The text to display.

PlayerBase

class wl.bases.PlayerBase

The base class for the Player objects in Editor and Game.

number

(RO) The number of this Player.

tribe_name

(RO) The name of the tribe of this player.

place_flag(field[, force])

Builds a flag on a given field if it is legal to do so. If not, reports an error.

Parameters:

• field (Field) – where the flag should be created

• force (boolean) –

  (Optional) If this is true the flag is created with pure force:

  • if there is an immovable on this field, it will be removed

  • if there are flags too close by to this field, they will be ripped

  • if the player does not own the territory, it is conquered for him.

Returns:

The Flag object created or nil.

place_road(roadtype, start_flag, dirs, ...[, force=false])

Start a road or waterway at the given flag, then walk the dirs given. Places a flag at the last field.

See also the convenience function connected_road() in infrastructure.lua.

Parameters:

• roadtype (string) – One of: "normal", "busy", or "waterway".

• start_flag (Flag) – The flag where to start the road.

• dirs (string) –

  Comma separated directions of the road. Allowed values for each direction are either:

  • directions: "r", "l", "br", "bl", "tr", "tl"

  • cardinal directions: "e", "w", "ne", "nw", "se", "sw"

• force (boolean) – (Optional) If true the road will be created by force: All immovables in the way are removed and land is conquered. Defaults to false.

Returns:

The Road created.

Example:

local plr = wl.Game().players[1]
local start_field = wl.Game().map:get_field(20,10)
local start_flag = pl:place_flag(start_field, true)
plr:place_road("normal", start_flag, "br", "br", "r", "r", true)

place_building(name, field[, cs = false, force = false])

Immediately creates a building on the given field. The building starts out completely empty.

See also the functions place_building_in_region() and prefilled_buildings() in “infrastructure.lua”.

Parameters:

• name (string) – The internal name of the building to create.

• field (Field) – The field to place the building.

• cs (boolean) – (Optional) If true the building is not created directly, instead a constructionsite for this building is placed.

• force (boolean) – (Optional) If true the building is forced into existence: The same action is taken as for place_flag() when force is true. Additionally, all buildings that are too close to the new one are ripped. If you want to use force you have to set cs also.

Returns:

The object of the building created.

place_ship(field)

Places a ship for the player’s tribe, which will be owned by the player.

Parameters:

field (Field) – The field where the ship should be placed.

Returns:

The new Ship that was created.

place_pinned_note(field, text[, r, g, b])

Added in version 1.2.

Place a pinned note on the map for this player.

Parameters:

• field (Field) – The field where the note should be placed.

• text (string) – The text of the note.

• r (integer) – The Red component of the note’s color.

• g (integer) – The Green component of the note’s color.

• b (integer) – The Blue component of the note’s color.

Returns:

The new PinnedNote that was created.

conquer(f[, radius=1])

Conquer an area around the given field if it does not belong to the player already. This will conquer the fields no matter who owns it at the moment.

Parameters:

• f (Field) – Center field for conquering.

• radius (integer) – (Optional) Radius to conquer around. The default of 1 results in 7 fields conquered.

Returns:

nil

get_workers(name)

Returns the number of workers of this name in the players stock.

Parameters:

name (string.) – The internal name of the worker to get.

Returns:

The number of workers.

get_wares(name)

Returns the number of wares of this name in the players stock.

Parameters:

name (string.) – The name of the worker to get.

Returns:

The number of wares.