LuaWML/Pathfinder - Revision history

Celtic Minstrel: Add move notice

2021-02-12T13:32:28Z

Add move notice

Pentarctagon: /* wesnoth.find_path */

2020-12-14T16:31:53Z

‎wesnoth.find_path

Pentarctagon: /* wesnoth.find_path */

2020-12-14T16:08:42Z

‎wesnoth.find_path

Mattsc: /* wesnoth.find_path */ add new syntax for cost function

2018-12-31T15:41:32Z

‎wesnoth.find_path: add new syntax for cost function

Mattsc: /* wesnoth.find_cost_map */ add comment on ignore_units

2018-01-01T15:39:46Z

‎wesnoth.find_cost_map: add comment on ignore_units

Mattsc: /* wesnoth.find_cost_map */ minor change to an example

2018-01-01T15:32:03Z

‎wesnoth.find_cost_map: minor change to an example

Mattsc: /* wesnoth.find_cost_map */ add examples

2018-01-01T15:31:09Z

‎wesnoth.find_cost_map: add examples

Mattsc: /* wesnoth.find_cost_map */ formatting changes

2018-01-01T15:22:36Z

‎wesnoth.find_cost_map: formatting changes

Mattsc: /* wesnoth.find_cost_map */ Trying to clarify how to use the function and fix some mistakes

2018-01-01T15:20:42Z

‎wesnoth.find_cost_map: Trying to clarify how to use the function and fix some mistakes

Mattsc: Added comments about hidden units

2016-10-03T14:38:01Z

Added comments about hidden units

← Older revision		Revision as of 13:32, 12 February 2021
Line 1:		Line 1:
		+	{{Template:LuaMove}}
		+
	This page describes the [[LuaWML]] functions and helpers for finding paths.		This page describes the [[LuaWML]] functions and helpers for finding paths.

@@ Line 8: / Line 8: @@
 Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
-* '''stop_at''': if set, the pathfinder will ignore paths longer than its value
+* '''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

@@ Line 8: / Line 8: @@
 Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its options are:
-* '''max_cost''': if set, the pathfinder will ignore paths longer than its value
+* '''stop_at''': 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

@@ Line 3: / Line 3: @@
 ==== wesnoth.find_path ====
-* '''wesnoth.find_path(''x1'', ''y1'', ''x2'', ''y2'', [''path_options'' | ''cost_function''])'''
+* '''Wesnoth 1.14 and earlier: wesnoth.find_path(''x1'', ''y1'', ''x2'', ''y2'', [''path_options'' | ''cost_function''])'''
 * '''wesnoth.find_path(''x1'', ''y1'', ''x2'', ''y2'', ''cost_function'', ''width'', ''height'')''', in map generation code. (see [[MapGeneratorWML#The_lua_generator]])
@@ Line 11: / Line 12: @@
 * '''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 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.
@@ Line 25: / Line 27: @@
   end
-Instead of a parameter table, a cost function can be passed to the pathfinder. It will be 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.
+As part of the parameter table (Wesnoth 1.15 and later) or instead of it (Wesnoth 1.14 and earlier), 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.
   -- Count how many turns it would take, assuming the worst case (3 movement points per tile)
   local max_moves = wesnoth.get_units({ x = x1, y = y1 })[1].max_moves
@@ Line 35: / Line 38: @@
           return current_cost + 3
       end)
   wesnoth.message(string.format("It would take %d turns.", math.ceil(cost / 3)))

@@ Line 89: / Line 89: @@
 ** '''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
 * 4. (optional) A [[StandardLocationFilter|Standard Location Filter]].  If given, the cost map will be calculated only for the locations satisfying this SLF.

@@ Line 98: / Line 98: @@
   local cost_map = wesnoth.find_cost_map(19, 4)
   local cost_map = wesnoth.find_cost_map({ side = wesnoth.current.side, canrecruit = 'yes' })
-  local cost_map = wesnoth.find_cost_map({ side = 999 }, { { 24, 7, 1, "Vampire Bat" } })
+  local cost_map = wesnoth.find_cost_map({ side = 999 }, { { 24, 7, wesnoth.current.side, "Vampire Bat" } })
 ==== helper.distance_between ====

@@ Line 92: / Line 92: @@
 '''Return value''':
-A array of quadruples (coordinates + summed cost + reach count)
+A array of quadruples (coordinates + summed cost + reach count).  The cost is set to -1 if not unit can reach the hex.
 ==== helper.distance_between ====

@@ Line 78: / Line 78: @@
 The costs consider movement lost during turn changes.
-Input arguments:
+'''Input arguments''':
 * 1. The unit(s) for which to calculate the cost map.  This can be
 ** a proxy unit
@@ Line 90: / Line 90: @@
 * 3. (optional) A table with options: ignore_units, ignore_teleport, viewing_side, debug, use_max_moves
 * 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)

@@ Line 71: / Line 71: @@
 ==== wesnoth.find_cost_map ====
-Builds a cost map for one, multiple units or unit types.
+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 will consider movement lost during turn changes. (So with simple calculus it is possible to get the turns to reach a hex)
+The costs consider movement lost during turn changes.
 Input arguments:
-* 1 + 2. A units location
+* 1. The unit(s) for which to calculate the cost map.  This can be
-* '''OR''' 1. A unit
+** a proxy unit
-* '''OR''' 1. A unit filter
+** '''or''' a unit filter
-* 2. (optional) A array of triples (coordinates + unit type as string)
+** '''or''' a unit's coordinates (in this case this is actually 2 arguments)
 * 3. (optional) A table with options: ignore_units, ignore_teleport, viewing_side, debug, use_max_moves
-* 4. (optional) A [[StandardLocationFilter|Standard Location Filter]].
+* 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 + a summed cost + reach count)
+A array of quadruples (coordinates + summed cost + reach count)
 ==== helper.distance_between ====

@@ Line 8: / Line 8: @@
 Returns the shortest path from one location to another. The source location is given either by coordinates as two arguments x and y; there must be a unit at the source location when using the standard path calculator. The source location can also be given by a unit as a single argument (as returned by the functions from [[LuaWML:Units]]). The second location is given by its coordinates. The last argument is an optional table that can be used to parametrize the pathfinder. Its 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
+* '''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; if left unset, the viewing side will be the unit side
+* '''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 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.
@@ Line 41: / Line 41: @@
 * '''wesnoth.find_vacant_tile(''x'', ''y'', [''unit''])'''
-Returns the two coordinates of an empty tile the closest to the tile 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.
+Returns the two coordinates of an empty tile the closest to the tile 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.
   function teleport(src_x, src_y, dst_x, dst_y)
@@ Line 57: / Line 57: @@
 Returns all the locations reachable by a unit. The unit is given either by its two coordinates or by a proxy object.  The last argument is an optional table that can be used to parametrize 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
+* '''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; if left unset, the viewing side will be the unit side
+* '''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.