LuaAPI/types/map

The map userdata provides direct access to the Wesnoth map. Functions in the map module that take a map as the first parameter can also be called as methods on the map userdata.

Terrain

• map[location] ↔ terrain code
• map[location] ← wesnoth.map.replace_base(terrain code)
• map[location] ← wesnoth.map.replace_overlay(terrain code)
• map[location] ← wesnoth.map.replace_both(terrain code)
• map[location] ← wesnoth.map.replace_if_failed(terrain code, mode)

Look up or modify the terrain on the given hex. When assigning a terrain code, the replacement method is determined by the ^ character in the code. If the terrain code starts with ^, only the overlay will be replaced. If the code ends with ^, only the base will be replaced. If it has ^ in the middle or does not have ^ at all, then both layers will be replaced (in the latter case, any existing overlay is removed). If the assignment ends up producing an invalid combination, it will be ignored.

The functions replace_base, replace_overlay, and replace_both simply add or remove a ^ to get the intended effect, so you don't need to remember the above rules. It's especially useful if the input terrain isn't under your control.

Although most overlays are defined to be placeable on any base terrain, there can also be cases where an overlay is only defined to be valid on certain base terrains. This occurs when TerrainWML is defined for the base+overlay combination instead of for the overlay alone. Assigning terrain using the replace_if_failed function modifies the behaviour when an invalid combination is produced. In this case you should not use a terrain code that begins or ends with ^. The mode can be either "base" or "overlay", and if the replacement fails because of an invalid combination, it will replace both layers instead. You can also pass "both" as the mode, though this is not very useful.

local replacement_terrain = 'Gg^Ve'
-- On (3,3), replace both layers
wesnoth.current.map[{3,3}] = wesnoth.map.replace_both(replacement_terrain)
-- On (4,7), replace only the overlay
wesnoth.current.map[{4,7}] = wesnoth.map.replace_overlay(replacement_terrain)
-- On (21,12), replace only the base
wesnoth.current.map[{21,12}] = wesnoth.map.replace_base(replacement_terrain)
-- On (15,9), replace only the overlay if possible, otherwise both
wesnoth.current.map[{15,9}] = wesnoth.map.replace_if_failed(replacement_terrain, 'overlay')

Map Size

• map.width → size
• map.height → size
• map.playable_width → size
• map.playable_height → size
• map.border_size → size

Get the size of the map. These satisfy the following identities:

width = playable_width + 2 * border_size
height = playable_height + 2 * border_size

Special Locations

• map.special_locations[id] ↔ location

This is a table containing all the special locations set in the map data, including side starting locations, indexed by their key. (Side starting locations are indexed by the side number.) It's writable, so you can modify them or add new ones on the fly.

-- Get the starting position of side 3
local enemy_start = wesnoth.current.map.special_locations[3]
-- Get a named location, "spire", from the map data
local destination = wesnoth.current.map.special_locations.spire

Map Data

• map.data → string

Convert the map to a string. This is usually needed by map generation scripts to pass the map on to the engine once the generation has completed.