LuaAPI/wesnoth/paths - Revision history

Laela at 17:53, 18 April 2024

2024-04-18T17:53:52Z

Egallager: missing space

2023-02-07T04:42:50Z

missing space

Celtic Minstrel: /* wesnoth.paths.find_reach */ Update example to used named fields, and update documentation to refer to them too

2023-02-07T02:02:39Z

‎wesnoth.paths.find_reach: Update example to used named fields, and update documentation to refer to them too

Celtic Minstrel: /* wesnoth.paths.find_reach */ ignore_teleport doesn't just affect teleporting units!

2021-07-27T13:41:47Z

‎wesnoth.paths.find_reach: ignore_teleport doesn't just affect teleporting units!

Celtic Minstrel: Add context specifiers to each entry

2021-07-04T23:39:02Z

Add context specifiers to each entry

Celtic Minstrel: Document find_vision_range

2021-07-03T02:29:42Z

Document find_vision_range

Celtic Minstrel: Categorize

2021-06-30T02:32:19Z

Categorize

Celtic Minstrel: Move the documentation of pathfinding functions from LuaWML/Pathfinder

2021-06-27T22:38:15Z

Move the documentation of pathfinding functions from LuaWML/Pathfinder

New page

The <tt>wesnoth.paths</tt> module contains functions for calculating paths and reach on the map.

=== wesnoth.paths.find_path ===

* '''wesnoth.paths.find_path'''(''start location'', ''end location'', [''path_options'']) → ''path'', ''cost''

Returns the shortest path from one location to another. There must be a unit at the source location when using the standard path calculator. A unit can also be used as the locations, but you should not use a unit as the end location unless you are ignoring units, as it will cause no path to be found. The last argument is an optional table that can be used to parameterize the pathfinder. This argument is required in the map generation context, but optional in the game context.

In the game context, the path options are:
* '''max_cost''': if set, the pathfinder will ignore paths longer than its value
* '''ignore_units''': if set, the path will go through units and ignore zones of control. Note: hidden enemies are always ignored, whether this parameter is set or not, unless viewing_side (below) is set to an invalid side.
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored and hidden units will be taken into account as well; if left unset, the viewing side will be the unit side
* '''calculate''': a cost function to be passed to the pathfinder (see below).

In the map generation context, the path options are:
* '''width''', '''height''': specify the size of the map. Pathfinding in the mapgen kernel is done without reference to a map, so this is needed to prevent paths from going off the map.
* '''include_borders''': an optional boolean indicating whether map borders should be included. If true, (0,0) and (width+1,height+1) are considered valid locations.
* '''calculate''': a cost function to be passed to the pathfinder (see below).

The path is returned as a table of coordinate pairs. It contains both the source and destination tile if a path was found. The total cost of the path is also available as a second return value, if needed.

<syntaxhighlight lang=lua>
-- Display some items along the path from (x1,y1) to (x2,y2).
local u = wesnoth.units.get(x1, y1)
local path, cost = wesnoth.paths.find_path(u, x2, y2, { ignore_units = true, viewing_side = 0 })
if cost > u.moves then
wesnoth.interface.add_chat_message("That's too far!")
else
for i, loc in ipairs(path) do
wml.fire("item", { x = loc[1], y = loc[2], image = "items/buckler.png" })
end
end
</syntaxhighlight>

* ''cost_function''(''x'', ''y'', ''current cost'') → ''cost to enter''

As part of the parameter table, a '''cost function''' can be passed to the pathfinder. It is called for all the tiles the computed path may possibly go through. It receives three arguments. The first two are the coordinates of the tile, the last one is the current cost for reaching that tile. The function should return a floating-point value that is the cost for entering the given tile. This cost should be greater or equal to one.

<syntaxhighlight lang=lua>
-- Count how many turns it would take, assuming the worst case (3 movement points per tile)
local max_moves = wesnoth.units.get(x1, y1).max_moves
local path, cost = wesnoth.paths.find_path(x1, y2, x2, y2, {
calculate = function(x, y, current_cost)
local remaining_moves = max_moves - (current_cost % max_moves)
if remaining_moves < 3 then current_cost = current_cost + remaining_moves end
return current_cost + 3
end })
wesnoth.interface.add_chat_message(string.format("It would take %d turns.", math.ceil(cost / 3)))
</syntaxhighlight>

=== wesnoth.paths.find_vacant_hex ===

* '''wesnoth.paths.find_vacant_hex'''(''x'', ''y'', [''unit'']) → ''x'', ''y''

Returns the two coordinates of an empty hex the closest to the hex passed by coordinates. An optional unit (either a WML table or a proxy object) can be passed as a third argument; if so, the returned tile has terrain which is passable for the passed unit. Note: hidden units are always seen by this function, no matter whether they are visible to the side of the passed unit.

<syntaxhighlight lang=lua>
function teleport(src_x, src_y, dst_x, dst_y)
local u = wesnoth.units.get(src_x, src_y)
dst_x, dst_y = wesnoth.paths.find_vacant_hex(dst_x, dst_y, u)
u:to_map(dst_x, dst_y)
end
</syntaxhighlight>

=== wesnoth.paths.find_reach ===

* '''wesnoth.paths.find_reach'''(''unit'', [''path_options'']) → ''array of locations''

Returns all the locations reachable by a unit. The unit is given either by its coordinates or by a proxy object. The last argument is an optional table that can be used to parameterize the pathfinder. Its options are:
* '''additional_turns''': if set to an integer n, the pathfinder will consider tiles that can be reached in n+1 turns
* '''ignore_units''': if set, the paths will go through units and ignore zones of control. Note: hidden enemies are always ignored, whether this parameter is set or not, unless viewing_side (below) is set to an invalid side.
* '''ignore_teleport''': if set, the teleport ability of the unit is ignored
* '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored and hidden units will be taken into account as well; if left unset, the viewing side will be the unit side
The locations are stored as triples in an array. The first two elements of a triple are the coordinates of a reachable tile, the third one is the number of movement points left when reaching the tile.

<syntaxhighlight lang=lua>
-- overlay the number of turns needed to reach each tile
local t = wesnoth.paths.find_reach(u, { additional_turns = 8 })
local m = u.max_moves
for i,l in ipairs(t) do
wml.fire("label", { x = l[1], y = l[2], text = math.ceil(9 - l[3]/m) })
end
</syntaxhighlight>

=== wesnoth.paths.find_cost_map ===

* '''wesnoth.paths.find_cost_map'''(''unit'') → ''cost map''

Builds a cost map for one unit, multiple units and/or one or multiple unit types.
In a cost map each hex is mapped to two values:
a) The summed cost to reach this hex for all input units
b) A value which indicates how many units can reach this hex
The caller can divide a) with b) to get a average cost to reach this hex for the input units.
The costs consider movement lost during turn changes.

'''Input arguments''':
* 1. The unit(s) for which to calculate the cost map. This can be
** a proxy unit
** '''or''' a unit filter
** '''or''' a unit's coordinates (in this case this is actually 2 arguments)
* 2. (optional) The unit type(s) for which to calculate the cost map. This argument must be an array of quadruples, each with the following elements:
** 1. + 2.: coordinates from which to calculate the cost map
** 3.: side of the unit
** 4.: unit type as a string
** '''Note''': If the array of unit types is given the units will be added to the first parameter. Use an empty filter or an invalid location for the first argument to add only unit types.
* 3. (optional) A table with options: ignore_units, ignore_teleport, viewing_side, debug, use_max_moves
** '''Note''': unlike most other Wesnoth Lua functions, ignore_units defaults to true.
* 4. (optional) A [[StandardLocationFilter|Standard Location Filter]]. If given, the cost map will be calculated only for the locations satisfying this SLF.

'''Return value''':
A array of quadruples (coordinates + summed cost + reach count). The cost is set to -1 if no unit can reach the hex.

<syntaxhighlight lang=lua>
local leader = wesnoth.units.find{ side = wesnoth.current.side, canrecruit = 'yes' }[1]
local cost_map = wesnoth.paths.find_cost_map(leader)
local cost_map = wesnoth.paths.find_cost_map(19, 4)
local cost_map = wesnoth.paths.find_cost_map({ side = wesnoth.current.side, canrecruit = 'yes' })
local cost_map = wesnoth.paths.find_cost_map({ side = 999 }, { { 24, 7, wesnoth.current.side, "Vampire Bat" } })
</syntaxhighlight>

← Older revision		Revision as of 17:53, 18 April 2024
Line 1:		Line 1:

	The <tt>wesnoth.paths</tt> module contains functions for calculating paths and reach on the map.		The <tt>wesnoth.paths</tt> module contains functions for calculating paths and reach on the map.
		+
		+	== Functions ==

	=== wesnoth.paths.find_path ===		=== wesnoth.paths.find_path ===

@@ Line 74: / Line 74: @@
 * '''ignore_teleport''': if set, the teleport ability of the unit is ignored, as well as any tunnels on the map
 * '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored and hidden units will be taken into account as well; if left unset, the viewing side will be the unit side
-The locations are stored as triples in an array, with members ''x'' and ''y'' thathold the coordinates of a reachable tile, and ''moves_left'' which is the number of movement points left when reaching the tile.
+The locations are stored as triples in an array, with members ''x'' and ''y'' that hold the coordinates of a reachable tile, and ''moves_left'' which is the number of movement points left when reaching the tile.
 <syntaxhighlight lang=lua>

@@ Line 4: / Line 4: @@
 === wesnoth.paths.find_path ===
-* '''wesnoth.paths.find_path'''(''start location'', ''end location'', [''path_options'']) &rarr; ''path'', ''cost''
+* {{LuaGameOnly}}{{LuaMapOnly}} '''wesnoth.paths.find_path'''(''start location'', ''end location'', [''path_options'']) &rarr; ''path'', ''cost''
 Returns the shortest path from one location to another. There must be a unit at the source location when using the standard path calculator. A unit can also be used as the locations, but you should not use a unit as the end location unless you are ignoring units, as it will cause no path to be found. The last argument is an optional table that can be used to parameterize the pathfinder. This argument is required in the map generation context, but optional in the game context.
@@ Line 53: / Line 53: @@
 === wesnoth.paths.find_vacant_hex ===
-* '''wesnoth.paths.find_vacant_hex'''(''x'', ''y'', [''unit'']) &rarr; ''x'', ''y''
+* {{LuaGameOnly}} '''wesnoth.paths.find_vacant_hex'''(''x'', ''y'', [''unit'']) &rarr; ''x'', ''y''
 Returns the two coordinates of an empty hex the closest to the hex passed by coordinates. An optional unit (either a WML table or a proxy object) can be passed as a third argument; if so, the returned tile has terrain which is passable for the passed unit.  Note: hidden units are always seen by this function, no matter whether they are visible to the side of the passed unit.
@@ Line 67: / Line 67: @@
 === wesnoth.paths.find_reach ===
-* '''wesnoth.paths.find_reach'''(''unit'', [''path_options'']) &rarr; ''array of locations''
+* {{LuaGameOnly}} '''wesnoth.paths.find_reach'''(''unit'', [''path_options'']) &rarr; ''array of locations''
 Returns all the locations reachable by a unit. The unit is given either by its coordinates or by a proxy object.  The last argument is an optional table that can be used to parameterize the pathfinder. Its options are:
@@ Line 87: / Line 87: @@
 === wesnoth.paths.find_vision_range ===
-* '''wesnoth.paths.find_vision_range'''(''unit'') &rarr; ''array of locations''
+* {{LuaGameOnly}} '''wesnoth.paths.find_vision_range'''(''unit'') &rarr; ''array of locations''
 Returns the hexes visible to that unit according to the unit's vision costs and vision points combined with any nearby units with jamming costs and points. The returned hexes include border hexes that would not be considered reachable if the unit's move points and vision points are the same.
@@ Line 93: / Line 93: @@
 === wesnoth.paths.find_cost_map ===
-* '''wesnoth.paths.find_cost_map'''(''unit'') &rarr; ''cost map''
+* {{LuaGameOnly}} '''wesnoth.paths.find_cost_map'''(''unit'') &rarr; ''cost map''
 Builds a cost map for one unit, multiple units and/or one or multiple unit types.

← Older revision		Revision as of 02:32, 30 June 2021
Line 120:		Line 120:
	local cost_map = wesnoth.paths.find_cost_map({ side = 999 }, { { 24, 7, wesnoth.current.side, "Vampire Bat" } })		local cost_map = wesnoth.paths.find_cost_map({ side = 999 }, { { 24, 7, wesnoth.current.side, "Vampire Bat" } })
	</syntaxhighlight>		</syntaxhighlight>
		+
		+	[[Category:Lua Reference]]

@@ Line 74: / Line 74: @@
 * '''ignore_teleport''': if set, the teleport ability of the unit is ignored, as well as any tunnels on the map
 * '''viewing_side''': if set to a valid side number, fog and shroud for this side will be taken into account; if set to an invalid number (e.g. 0), fog and shroud will be ignored and hidden units will be taken into account as well; if left unset, the viewing side will be the unit side
-The locations are stored as triples in an array. The first two elements of a triple are the coordinates of a reachable tile, the third one is the number of movement points left when reaching the tile.
+The locations are stored as triples in an array, with members ''x'' and ''y'' thathold the coordinates of a reachable tile, and ''moves_left'' which is the number of movement points left when reaching the tile.
 <syntaxhighlight lang=lua>
@@ Line 81: / Line 81: @@
 local m = u.max_moves
 for i,l in ipairs(t) do
-   wml.fire("label", { x = l[1], y = l[2], text = math.ceil(9 - l[3]/m) })
+   wml.fire("label", { x = l.x, y = l.y, text = math.ceil(9 - l.moves_left / m) })
 end
 </syntaxhighlight>