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

pathfinder:new (grid[, finderName[, walkable]]) Inits a new pathfinder object
pathfinder:setGrid (grid) Sets a grid object.
pathfinder:getGrid () Returns the grid object.
pathfinder:setWalkable (walkable) Sets the walkable value or function.
pathfinder:getWalkable () Gets the walkable value or function.
pathfinder:setFinder (finderName) Sets a finder.
pathfinder:getFinder () Gets the name of the finder being used.
pathfinder:getFinders () Gets the list of all available finders names.
pathfinder:setHeuristic (heuristic) Set a heuristic.
pathfinder:getHeuristic () Gets the heuristic used.
pathfinder:getHeuristics () Gets the list of all available heuristics.
pathfinder:setMode (mode) Changes the search mode.
pathfinder:getMode () Gets the search mode.
pathfinder:getModes () Gets the list of all available search modes.
pathfinder:version () Returns version and release date.
pathfinder:getPath (startX, startY, endX, endY[, tunnel]) Calculates a path.

Tables

pathfinder The pathfinder class


Functions

pathfinder: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..
  • 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.

Returns:

    pathfinder a new pathfinder object
pathfinder:setGrid (grid)
Sets a grid object. Defines the grid on which the pathfinder will make path searches.

Parameters:

pathfinder:getGrid ()
Returns the grid object. Returns a reference to the internal grid object used by the pathfinder object.

Returns:

    grid the grid object
pathfinder: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.
pathfinder:getWalkable ()
Gets the walkable value or function.

Returns:

    string, int or function the walkable previously set
pathfinder: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:

pathfinder: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.
pathfinder:getFinders ()
Gets the list of all available finders names.

Returns:

    {string,...} array of finders names.
pathfinder: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:

pathfinder:getHeuristic ()
Gets the heuristic used. Returns the function itself.

Returns:

    function the heuristic function being used by the pathfinder object
pathfinder:getHeuristics ()
Gets the list of all available heuristics.

Returns:

    {string,...} array of heuristic names.
pathfinder: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:

pathfinder:getMode ()
Gets the search mode.

Returns:

    string the current search mode
pathfinder:getModes ()
Gets the list of all available search modes.

Returns:

    {string,...} array of search modes.
pathfinder:version ()
Returns version and release date.

Returns:

  1. string the version of the current implementation
  2. string the release of the current implementation
pathfinder:getPath (startX, startY, endX, endY[, tunnel])
Calculates a path. Returns the path from location <startX, startY> to location <endX, endY>. Both locations must exist on the collision map.

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)

Returns:

  1. {node,...} a path (array of nodes) when found, otherwise nil
  2. number the path length when found, 0 otherwise

Tables

pathfinder
The pathfinder class
generated by LDoc 1.3