Module pathfinder
The Pathfinder class
Finders
Finders | Finders (search algorithms implemented). |
Modes
Modes | Search modes. |
Class Pathfinder
Finders
- Finders
-
Finders (search algorithms implemented). Refers to the search algorithms actually implemented in Jumper.
- A*
- Dijkstra
- Theta Astar
- BFS
- DFS
- JPS
see also:
Modes
- Modes
-
Search modes. Refers to the search modes. In ORTHOGONAL mode, 4-directions are only possible when moving,
including North, East, West, South. In DIAGONAL mode, 8-directions are possible when moving,
including North, East, West, South and adjacent directions.
- ORTHOGNAL
- DIAGONAL
see also:
Class Pathfinder
The Pathfinder class.This class is callable. Therefore,_
Pathfinder(...)
acts as a shortcut to Pathfinder:new(...)
.
- Pathfinder:new (grid [, finderName [, walkable]])
-
Inits a new pathfinder
Parameters:
- grid grid a grid
- finderName
string
the name of the
Finder
(search algorithm) to be used for search. Defaults toASTAR
when not given (see Pathfinder:getFinders). - walkable
string, int or func
the value for walkable nodes.
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.
Usage:
-- Example one local finder = Pathfinder:new(myGrid, 'ASTAR', 0) -- Example two local function walkable(value) return value > 0 end local finder = Pathfinder(myGrid, 'JPS', walkable)
Returns:
-
pathfinder
a new pathfinder instance
- Pathfinder:annotateGrid ()
-
Evaluates clearance
for the whole grid . It should be called only once, unless the collision map or the
walkable attribute changes. The clearance values are calculated and cached within the grid nodes.
Usage:
myFinder:annotateGrid()
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
- Pathfinder:clearAnnotations ()
-
Removes clearancevalues.
Clears cached clearance values for the current walkable.
Usage:
myFinder:clearAnnotations()
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
- Pathfinder:setGrid (grid)
-
Sets the grid . Defines the given grid as the one on which the pathfinder will perform the search.
Parameters:
Usage:
myFinder:setGrid(myGrid)
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
- Pathfinder:getGrid ()
-
Returns the grid . This is a reference to the actual grid used by the pathfinder .
Usage:
local myGrid = myFinder:getGrid()
Returns:
- Pathfinder:setWalkable (walkable)
-
Sets the walkable value or function.
Parameters:
Usage:
-- Value '0' is walkable myFinder:setWalkable(0) -- Any value greater than 0 is walkable myFinder:setWalkable(function(n) return n>0 end
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
- Pathfinder:getWalkable ()
-
Gets the walkable value or function.
Usage:
local walkable = myFinder:getWalkable()
Returns:
- Pathfinder:setFinder (finderName)
-
Defines the
finder
. It refers to the search algorithm used by the pathfinder . Default finder isASTAR
. Use Pathfinder:getFinders to get the list of available finders.Parameters:
- finderName
string
the name of the
finder
to be used for further searches.
Usage:
--To use Breadth-First-Search myFinder:setFinder('BFS')
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
see also:
- finderName
string
the name of the
- Pathfinder:getFinder ()
-
Returns the name of the
finder
being used.Usage:
local finderName = myFinder:getFinder()
Returns:
-
string
the name of the
finder
to be used for further searches. - Pathfinder:getFinders ()
-
Returns the list of all available finders names.
Usage:
local finders = myFinder:getFinders() for i, finderName in ipairs(finders) do print(i, finderName) end
Returns:
-
{string,...}
array of built-in finders names.
- Pathfinder:setHeuristic (heuristic)
-
Sets a heuristic. This is a function internally used by the pathfinder to find the optimal path during a search.
Use Pathfinder:getHeuristics to get the list of all available
heuristics
. One can also define his ownheuristic
function.Parameters:
Usage:
myFinder:setHeuristic('MANHATTAN')
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
see also:
- Pathfinder:getHeuristic ()
-
Returns the
heuristic
used. Returns the function itself.Usage:
local h = myFinder:getHeuristic()
Returns:
-
func
the
heuristic
function being used by the pathfindersee also:
- Pathfinder:getHeuristics ()
-
Gets the list of all available
heuristics
.Usage:
local heur = myFinder:getHeuristic() for i, heuristicName in ipairs(heur) do ... end
Returns:
-
{string,...}
array of heuristic names.
see also:
- Pathfinder:setMode (mode)
-
Defines the search
mode
. The default search mode is theDIAGONAL
mode, which implies 8-possible directions when moving (north, south, east, west and diagonals). InORTHOGONAL
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
.
Usage:
myFinder:setMode('ORTHOGNAL')
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
see also:
- mode
string
the new search
- Pathfinder:getMode ()
-
Returns the search mode.
Usage:
local mode = myFinder:getMode()
Returns:
-
string
the current search mode
see also:
- Pathfinder:getModes ()
-
Gets the list of all available search modes.
Usage:
local modes = myFinder:getModes() for modeName in ipairs(modes) do ... end
Returns:
-
{string,...}
array of search modes.
see also:
- Pathfinder:setTunnelling (bool)
-
Enables tunnelling. Defines the ability for the pathfinder to tunnel through walls when heading diagonally.
This feature is not compatible with Jump Point Search algorithm (i.e. enabling it will not affect Jump Point Search)
Parameters:
- bool bool a boolean
Usage:
myFinder:setTunnelling(true)
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)
- Pathfinder:getTunnelling ()
-
Returns tunnelling feature state.
Usage:
local isTunnellingEnabled = myFinder:getTunnelling()
Returns:
-
bool
tunnelling feature actual state
- Pathfinder:getPath (startX, startY, endX, endY, clearance)
-
Calculates a
path
. Returns thepath
from location [startX, startY] to location [endX, endY]. Both locations must exist on the collision map. The starting location can be unwalkable.Parameters:
- startX int the x-coordinate for the starting location
- startY int the y-coordinate for the starting location
- endX int the x-coordinate for the goal location
- endY int the y-coordinate for the goal location
- clearance int the amount of clearance (i.e the pathing agent size) to consider
Usage:
local path = myFinder:getPath(1,1,5,5)
Returns:
-
path
a path (array of nodes) when found, otherwise nil
- Pathfinder:reset ()
-
Resets the pathfinder . This function is called internally between successive pathfinding calls, so you should not
use it explicitely, unless under specific circumstances.
Usage:
local path, len = myFinder:getPath(1,1,5,5)
Returns:
-
pathfinder
self (the calling pathfinder itself, can be chained)