Module jumper.pathfinder
The pathfinder class API.
Implementation of the `pathfinder` class.
Usage:
-- Usage Example
-- First, set a collision map
local map = {
{0,1,0,1,0},
{0,1,0,1,0},
{0,1,1,1,0},
{0,0,0,0,0},
}
-- Value for walkable tiles
local walkable = 0
-- Library setup
local Grid = require ("jumper.grid") -- The grid class
local Pathfinder = require ("jumper.pathfinder") -- The pathfinder lass
-- Creates a grid object
local grid = Grid(map)
-- Creates a pathfinder object using Jump Point Search
local myFinder = Pathfinder(grid, 'JPS', walkable)
-- Define start and goal locations coordinates
local startx, starty = 1,1
local endx, endy = 5,1
-- Calculates the path, and its length
local path, length = myFinder:getPath(startx, starty, endx, endy)
if path then
print(('Path found! Length: %.2f'):format(length))
for node, count in path:iter() do
print(('Step: %d - x: %d - y: %d'):format(count, node.x, node.y))
end
end
--> Output:
--> Path found! Length: 8.83
--> Step: 1 - x: 1 - y: 1
--> Step: 2 - x: 1 - y: 3
--> Step: 3 - x: 2 - y: 4
--> Step: 4 - x: 4 - y: 4
--> Step: 5 - x: 5 - y: 3
--> Step: 6 - x: 5 - y: 1
Info:
- Copyright: 2012-2013
- License: MIT
- Author: Roland Yonaba
Functions
| new (grid[, finderName[, walkable]]) | Inits a new `pathfinder` object |
| setGrid (grid) | Sets a `grid` object. |
| getGrid () | Returns the `grid` object. |
| setWalkable (walkable) | Sets the `walkable` value or function. |
| getWalkable () | Gets the `walkable` value or function. |
| setFinder (finderName) | Sets a finder. |
| getFinder () | Gets the name of the finder being used. |
| getFinders () | Gets the list of all available finders names. |
| setHeuristic (heuristic) | Set a heuristic. |
| getHeuristic () | Gets the heuristic used. |
| getHeuristics () | Gets the list of all available heuristics. |
| setMode (mode) | Changes the search mode. |
| getMode () | Gets the search mode. |
| getModes () | Gets the list of all available search modes. |
| version () | Returns version and release date. |
| getPath (startX, startY, endX, endY[, tunnel]) | Calculates a path. |
Tables
| pathfinder | The `pathfinder` class |
Functions
- new (grid[, finderName[, walkable]])
-
Inits a new `pathfinder` object
Parameters:
- grid grid a `grid` object
- finderName string the name of the `finder` (search algorithm) to be used for further searches. Defaults to `ASTAR` when not given. Use pathfinder:getFinders to get the full list of available finders.. (optional)
- walkable string, int or function the value for walkable nodes on the passed-in map array. If this parameter is a function, it should be prototyped as `f(value)`, returning a boolean: `true` when value matches a *walkable* node, `false` otherwise. (optional)
Returns:
-
pathfinder
a new `pathfinder` object
- setGrid (grid)
-
Sets a `grid` object. Defines the `grid` on which the `pathfinder` will make path searches.
Parameters:
- grid grid a `grid` object
- getGrid ()
-
Returns the `grid` object. Returns a reference to the internal `grid` object used by the `pathfinder` object.
Returns:
-
grid
the `grid` object
- setWalkable (walkable)
-
Sets the `walkable` value or function.
Parameters:
- walkable string, int or function the value for walkable nodes on the passed-in map array. If this parameter is a function, it should be prototyped as `f(value)`, returning a boolean: `true` when value matches a *walkable* node, `false` otherwise.
- getWalkable ()
-
Gets the `walkable` value or function.
Returns:
-
string, int or function
the `walkable` previously set
- setFinder (finderName)
-
Sets a finder. The finder refers to the search algorithm used by the `pathfinder` object.
The default finder is `ASTAR`. Use pathfinder:getFinders to get the list of available finders.
Parameters:
- finderName string the name of the finder to be used for further searches.
See also:
- getFinder ()
-
Gets the name of the finder being used. The finder refers to the search algorithm used by the `pathfinder` object.
Returns:
-
string
the name of the finder to be used for further searches.
- getFinders ()
-
Gets the list of all available finders names.
Returns:
-
{string,...}
array of finders names.
- setHeuristic (heuristic)
-
Set a heuristic. This is a function internally used by the `pathfinder` to get the optimal path during a search.
Use pathfinder:getHeuristics to get the list of all available heuristics. One can also defined
his own heuristic function.
Parameters:
- heuristic function or string a heuristic function, prototyped as `f(dx,dy)` or a string.
See also:
- getHeuristic ()
-
Gets the heuristic used. Returns the function itself.
Returns:
-
function
the heuristic function being used by the `pathfinder` object
- getHeuristics ()
-
Gets the list of all available heuristics.
Returns:
-
{string,...}
array of heuristic names.
- setMode (mode)
-
Changes the search mode. Defines a new search mode for the `pathfinder` object.
The default search mode is `DIAGONAL`, which implies 8-possible directions when moving (north, south, east, west and diagonals).
In `ORTHOGONAL` mode, only 4-directions are allowed (north, south, east and west).
Use pathfinder:getModes to get the list of all available search modes.
Parameters:
- mode string the new search mode.
See also:
- getMode ()
-
Gets the search mode.
Returns:
-
string
the current search mode
- getModes ()
-
Gets the list of all available search modes.
Returns:
-
{string,...}
array of search modes.
- version ()
-
Returns version and release date.
Returns:
- getPath (startX, startY, endX, endY[, tunnel])
-
Calculates a path. Returns the path from location `
Parameters:
- startX number the x-coordinate for the starting location
- startY number the y-coordinate for the starting location
- endX number the x-coordinate for the goal location
- endY number the y-coordinate for the goal location
- tunnel bool Whether or not the pathfinder can tunnel though walls diagonally (not compatible with `Jump Point Search`) (optional)
Returns:
- {node,...} a path (array of `nodes`) when found, otherwise `nil`
- number the path length when found, `0` otherwise