LuaAPI/types/map - Revision history

Celtic Minstrel: /* Terrain */ Give a bit more explanation of the replace_if_failed case

2023-12-17T22:19:55Z

‎Terrain: Give a bit more explanation of the replace_if_failed case

Celtic Minstrel: /* Terrain */ Fix formatting

2021-07-02T06:26:39Z

‎Terrain: Fix formatting

Celtic Minstrel: Categorize

2021-06-30T02:34:55Z

Categorize

Celtic Minstrel: Document the map userdata

2021-06-24T17:59:21Z

Document the map userdata

New page

The '''map''' userdata provides direct access to the Wesnoth map. Functions in the [[LuaAPI/wesnoth/map|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 <tt>^</tt> character in the code. If the terrain code starts with <tt>^</tt>, only the overlay will be replaced. If the code ends with <tt>^</tt>, only the base will be replaced. If it has <tt>^</tt> in the middle or does not have <tt>^</tt> 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 <tt>^</tt> 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.

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 <tt>^</tt>. 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.

<syntaxhighlight lang=lua>
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')
</syntaxhighlight>

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

<syntaxhighlight lang=lua>
-- 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
</syntaxhighlight>

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

← Older revision		Revision as of 02:34, 30 June 2021
Line 59:		Line 59:

	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.		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.
		+
		+	[[Category:Lua Reference]]

@@ Line 14: / Line 14: @@
 The functions '''replace_base''', '''replace_overlay''', and '''replace_both''' simply add or remove a <tt>^</tt> 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.
-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 <tt>^</tt>. 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.
+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 <tt>^</tt>. 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.
 <syntaxhighlight lang=lua>

@@ Line 8: / Line 8: @@
 * ''map''[''location''] &larr; '''wesnoth.map.replace_overlay'''(''terrain code'')
 * ''map''[''location''] &larr; '''wesnoth.map.replace_both'''(''terrain code'')
-* ''map''[''location''] &larr; '''wesnoth.map.replace_if_failed(''terrain code'', ''mode'')
+* ''map''[''location''] &larr; '''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 <tt>^</tt> character in the code. If the terrain code starts with <tt>^</tt>, only the overlay will be replaced. If the code ends with <tt>^</tt>, only the base will be replaced. If it has <tt>^</tt> in the middle or does not have <tt>^</tt> 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.