* Rename the vector operations to hex_vector (to emphasize that they are NOT standard vector ops) and document them as official API
* Add new get_hexes_at_radius, which returns an unfilled ring (as opposed to get_hexes_in_radius which returns a filled circle)
* Expose the new cubic coordinate conversions
These may be less efficient in some cases, and there's even a couple of degenerate cases, but it's definitely easier to use like this.
This also adds an example of the original method, using a string to reference a separate list.
- place_shroud and remove_shroud no longer accept a shroud data string or the special string "all"
- new functions are added to convert between lists of locations and shroud data strings
- place_fog, remove_fog, is_fogged, and is_shrouded aren't changed, only moved
The method of accessing terrain on the map has drastically changed.
- wesnoth.get_terrain and wesnoth.set_terrain are both deprecated
- wesnoth.terrain_mask still works but is moved into the wesnoth.map module and now takes the map object as the first parameter
- The map's terrain is now accessed exclusively via indexing on the map object, ie map[{x,y}]
- You set terrain by assigning a terrain code; the position of ^ in the terrain code now determines the merge mode
- The replace_if_failed option is now manifested as a function that converts any terrain code into a special value that, when assigned to a location on the map, uses the replace if failed logic.
The map object has a few attributes in it:
- width and height are the total size, including borders
- playable_width and playable_height are the values returned from wesnoth.get_map_size, which is now deprecated
- border_size is the third value from wesnoth.get_map_size
- data converts the map to a string
- Special locations are now part of the map object. The length operator is deprecated.
- other than that, wesnoth.map is treated as if it were the metatable of the map object
The purpose of this is to make it easy for functions implemented in Lua to handle locations
in the same way as functions implemented in C++.
The location_set module has been updated to make use of this functionality in its setter functions.
Usage example:
Imagine a function foo with the following signature:
foo(bar : string, home : location, mode : string, target : location, moo : boolean) -> boolean
With the new read_location function it could be implemented as follows:
function foo(...)
-- First argument goes in bar
local bar = ...
-- Read location starting at the second argument
local home, n = wesnoth.mP.read_location(select(2, ...))
-- note: n will be 0 if a location wasn't found at that position
-- This could be an error, or it could be handled as an optional parameter
-- Next argument after that goes in mode
local mode = select(n + 2, ...)
-- Then read a location into target
local target, m = wesnoth.map.read_location(select(n + 2, ...))
-- Finally, read a parameter into moo
local moo = select(m + n + 2, ...)
-- Do stuff with all these parameters
return true
end
With that code, all the following invocations of foo work:
foo('a', 'b', true) -- both optional locations omitted
foo('a', 1, 2, 'q', 5, 6, false) -- locations given as separate integer parameters
foo('a', 'm', {1, 7}, true) -- first location omitted, second given as 2-element array
foo('a', some_unit, 'z', {x = 5, y = 10}, false) -- a unit also functions as a location
foo('a', 7, 12, 'q', my_leader, true) -- mixing different forms also works
