Jumper

Node:getX ()

Returns x-coordinate of a node

Usage:

local x = node:getX()

Returns:

number

Node:getY ()

Returns y-coordinate of a node

Usage:

local y = node:getY()

Returns:

number

Node:getPos ()

Returns x and y coordinates of a node

Usage:

local x, y = node:getPos()

Returns:

number the x-coordinate of the node
number the y-coordinate of the node

Node:getClearance (walkable)

Returns the amount of true clearance for a given node

Parameters:

walkable string, int or func the value for walkable locations in the collision map array.

Usage:

  -- Assuming walkable was 0
 local clearance = node:getClearance(0)

Returns:

int

Node:removeClearance (walkable)

Removes the clearance value for a given walkable.

Parameters:

walkable string, int or func the value for walkable locations in the collision map array.

Usage:

  -- Assuming walkable is defined
 node:removeClearance(walkable)

Returns:

Node:reset ()

Clears temporary cached attributes of a node . Deletes the attributes cached within a given node after a pathfinding call. This function is internally used by the search algorithms, so you should not use it explicitely.

Usage:

 local thisNode = Node(1,2)
 thisNode:reset()

Returns:

generated by LDoc 1.2

================================================ FILE: docs/modules/core.path.html ================================================ Jumper documentation

Module `core.path`

The Path class.

The path class is a structure which represents a path (ordered set of nodes) from a start location to a goal. An instance from this class would be a result of a request addressed to Pathfinder:getPath.

This module is internally used by the library on purpose. It should normally not be used explicitely, yet it remains fully accessible.

Class Path

Path:new ()	Inits a new path .
Path:iter ()	Iterates on each single node along a path .
Path:nodes ()	Iterates on each single node along a path .
Path:getLength ()	Evaluates the path length
Path:addNode (node [, index])	Counts the number of steps.
Path:fill ()	Path filling modifier.
Path:filter ()	Path compression modifier.
Path:clone ()	Clones a path .
Path:isEqualTo (p2)	Checks if a path is equal to another.
Path:reverse ()	Reverses a path .
Path:append (p)	Appends a given path to self.

Class Path

The Path class.
This class is callable. Therefore, Path(...) acts as a shortcut to Path:new(...).

Path:new ()

Inits a new path .

Usage:

local p = Path()

Returns:

Path:iter ()

Iterates on each single node along a path . At each step of iteration, returns the node plus a count value. Aliased as Path:nodes

Usage:

 for node, count in p:iter() do
   ...
 end

Returns:

node a node
int the count for the number of nodes

Usage:

 for node, count in p:nodes() do
   ...
 end

Returns:

node a node
int the count for the number of nodes

Usage:

local len = p:getLength()

Returns:

number

Path:addNode (node [, index])

Counts the number of steps. Returns the number of waypoints (nodes) in the current path.

Parameters:

node node a node to be added to the path
index int the index at which the node will be inserted. If omitted, the node will be appended after the last node in the path.

Usage:

local nSteps = p:countSteps()

Returns:

Path:fill ()

Path filling modifier. Interpolates between non contiguous nodes along a path to build a fully continuous path . This maybe useful when using search algorithms such as Jump Point Search. Does the opposite of Path:filter

Usage:

p:fill()

Returns:

Usage:

p:filter()

Returns:

Usage:

local p = path:clone()

Returns:

Path:isEqualTo (p2)

Checks if a path is equal to another. It also supports filtered paths (see Path:filter).

Parameters:

p2 path a path

Usage:

print(myPath:isEqualTo(anotherPath))

Returns:

boolean

Path:reverse ()

Reverses a path .

Usage:

myPath:reverse()

Returns:

Path:append (p)

Appends a given path to self.

Parameters:

p path a path

Usage:

myPath:append(anotherPath)

Returns:

generated by LDoc 1.2

================================================ FILE: docs/modules/grid.html ================================================ Jumper documentation

Module `grid`

The Grid class.

Implementation of the grid class. The grid is a implicit graph which represents the 2D world map layout on which the pathfinder object will run. During a search, the pathfinder object needs to save some critical values. These values are cached within each node object, and the whole set of nodes are tight inside the grid object itself.

Class Grid

Grid:new (map [, cacheNodeAtRuntime])	Inits a new grid
Grid:isWalkableAt (x, y [, walkable [, clearance]])	Checks if `node` at [x,y] is walkable.
Grid:getWidth ()	Returns the grid width.
Grid:getHeight ()	Returns the grid height.
Grid:getMap ()	Returns the collision map.
Grid:getNodes ()	Returns the set of nodes.
Grid:getBounds ()	Returns the grid bounds.
Grid:getNeighbours (node [, walkable [, allowDiagonal [, tunnel [, clearance]]]])	Returns neighbours.
Grid:iter ( [lx [, ly [, ex [, ey]]]])	Grid iterator.
Grid:around (node [, radius])	Grid iterator.
Grid:each (f [, ...])	Each transformation.
Grid:eachRange (lx, ly, ex, ey, f [, ...])	Each (in range) transformation.
Grid:imap (f [, ...])	Map transformation.
Grid:imapRange (lx, ly, ex, ey, f [, ...])	Map in range transformation.
Grid:getNodeAt (x, y)	Returns the `node` at location [x,y].

Class Grid

The Grid class.
This class is callable. Therefore,_ Grid(...) acts as a shortcut to Grid:new(...).

Grid:new (map [, cacheNodeAtRuntime])

Inits a new grid

Parameters:

map table or string A collision map - (2D array) with consecutive indices (starting at 0 or 1) or a string with line-break chars (\n or \r) as row delimiters.
cacheNodeAtRuntime bool When true, returns an empty grid instance, so that later on, indexing a non-cached node will cause it to be created and cache within the grid on purpose (i.e, when needed). This is a memory-safe option, in case your dealing with some tight memory constraints. Defaults to false when omitted.

Usage:

 -- A simple 3x3 grid
 local myGrid = Grid:new({{0,0,0},{0,0,0},{0,0,0}})

 -- A memory-safe 3x3 grid
 myGrid = Grid('000\n000\n000', true)

Returns:

Grid:isWalkableAt (x, y [, walkable [, clearance]])

Checks if node at [x,y] is walkable. Will check if node at location [x,y] both exists on the collision map and is walkable

Parameters:

x int the x-location of the node
y int the y-location of the node
walkable string, int or func the value for walkable locations in the collision map array (see Grid:new). Defaults to false when omitted. If this parameter is a function, it should be prototyped as f(value) and return a boolean : true when value matches a walkable node, false otherwise. If this parameter is not given while location [x,y] is valid, this actual function returns true.
clearance int the amount of clearance needed. Defaults to 1 (normal clearance) when not given.

Usage:

 -- Always true
 print(myGrid:isWalkableAt(2,3))

 -- True if node at [2,3] collision map value is 0
 print(myGrid:isWalkableAt(2,3,0))

 -- True if node at [2,3] collision map value is 0 and has a clearance higher or equal to 2
 print(myGrid:isWalkableAt(2,3,0,2))

Returns:

bool

true

node

walkable

false

Grid:getWidth ()

Returns the grid width.

Usage:

print(myGrid:getWidth())

Returns:

int

Grid:getHeight ()

Returns the grid height.

Usage:

print(myGrid:getHeight())

Returns:

int

Grid:getMap ()

Returns the collision map.

Usage:

local map = myGrid:getMap()

Returns:

map

Grid:new

Grid:getNodes ()

Returns the set of nodes.

Usage:

local nodes = myGrid:getNodes()

Returns:

{{node,...},...}

Grid:getBounds ()

Returns the grid bounds. Returned values corresponds to the upper-left and lower-right coordinates (in tile units) of the actual grid instance.

Usage:

local left_x, left_y, right_x, right_y = myGrid:getBounds()

Returns:

int the upper-left corner x-coordinate
int the upper-left corner y-coordinate
int the lower-right corner x-coordinate
int the lower-right corner y-coordinate

Grid:getNeighbours (node [, walkable [, allowDiagonal [, tunnel [, clearance]]]])

Returns neighbours. The returned value is an array of walkable nodes neighbouring a given node.

Parameters:

node node a given node
walkable string, int or func the value for walkable locations in the collision map array (see Grid:new). Defaults to false when omitted.
allowDiagonal bool when true, allows adjacent nodes are included (8-neighbours). Defaults to false when omitted.
tunnel bool When true, allows the pathfinder to tunnel through walls when heading diagonally.
clearance int When given, will prune for the neighbours set all nodes having a clearance value lower than the passed-in value Defaults to false when omitted.

Usage:

 local aNode = myGrid:getNodeAt(5,6)
 local neighbours = myGrid:getNeighbours(aNode, 0, true)

Returns:

{node,...}

Grid:iter ( [lx [, ly [, ex [, ey]]]])

Grid iterator. Iterates on every single node in the grid . Passing lx, ly, ex, ey arguments will iterate only on nodes inside the bounding-rectangle delimited by those given coordinates.

Parameters:

lx int the leftmost x-coordinate of the rectangle. Default to the grid leftmost x-coordinate (see Grid:getBounds).
ly int the topmost y-coordinate of the rectangle. Default to the grid topmost y-coordinate (see Grid:getBounds).
ex int the rightmost x-coordinate of the rectangle. Default to the grid rightmost x-coordinate (see Grid:getBounds).
ey int the bottom-most y-coordinate of the rectangle. Default to the grid bottom-most y-coordinate (see Grid:getBounds).

Usage:

 for node, count in myGrid:iter() do
   print(node:getX(), node:getY(), count)
 end

Returns:

node a node on the collision map, upon each iteration step
int the iteration count

Grid:around (node [, radius])

Grid iterator. Iterates on each node along the outline (border) of a squared area centered on the given node.

Parameters:

node node a given node
radius int the area radius (half-length). Defaults to 1 when not given.

Usage:

 for node in myGrid:around(node, 2) do
   ...
 end

Returns:

node

node

Grid:each (f [, ...])

Each transformation. Calls the given function on each node in the grid , passing the node as the first argument to function f.

Parameters:

f func a function prototyped as f(node,...)
... vararg args to be passed to function f

Usage:

 local function printNode(node)
   print(node:getX(), node:getY())
 end
 myGrid:each(printNode)

Returns:

Grid:eachRange (lx, ly, ex, ey, f [, ...])

Each (in range) transformation. Calls a function on each node in the range of a rectangle of cells, passing the node as the first argument to function f.

Parameters:

lx int the leftmost x-coordinate coordinate of the rectangle
ly int the topmost y-coordinate of the rectangle
ex int the rightmost x-coordinate of the rectangle
ey int the bottom-most y-coordinate of the rectangle
f func a function prototyped as f(node,...)
... vararg args to be passed to function f

Usage:

 local function printNode(node)
   print(node:getX(), node:getY())
 end
 myGrid:eachRange(1,1,8,8,printNode)

Returns:

Grid:imap (f [, ...])

Map transformation. Calls function f(node,...) on each node in a given range, passing the node as the first arg to function f and replaces it with the returned value. Therefore, the function should return a node.

Parameters:

f func a function prototyped as f(node,...)
... vararg args to be passed to function f

Usage:

 local function nothing(node)
   return node
 end
 myGrid:imap(nothing)

Returns:

Grid:imapRange (lx, ly, ex, ey, f [, ...])

Map in range transformation. Calls function f(node,...) on each node in a rectangle range, passing the node as the first argument to the function and replaces it with the returned value. Therefore, the function should return a node.

Parameters:

lx int the leftmost x-coordinate coordinate of the rectangle
ly int the topmost y-coordinate of the rectangle
ex int the rightmost x-coordinate of the rectangle
ey int the bottom-most y-coordinate of the rectangle
f func a function prototyped as f(node,...)
... vararg args to be passed to function f

Usage:

 local function nothing(node)
   return node
 end
 myGrid:imap(1,1,6,6,nothing)

Returns:

Grid:getNodeAt (x, y)

Returns the node at location [x,y].

Parameters:

x int the x-coordinate coordinate
y int the y-coordinate coordinate

Usage:

local aNode = myGrid:getNodeAt(2,2)

Returns:

node

node

generated by LDoc 1.2

================================================ FILE: docs/modules/pathfinder.html ================================================ Jumper documentation

Module `pathfinder`

The Pathfinder class

Finders

Finders (search algorithms implemented).

Modes

Search modes.

Class Pathfinder

Pathfinder:new (grid [, finderName [, walkable]])	Inits a new pathfinder
Pathfinder:annotateGrid ()	Evaluates clearance for the whole grid .
Pathfinder:clearAnnotations ()	Removes clearancevalues.
Pathfinder:setGrid (grid)	Sets the grid .
Pathfinder:getGrid ()	Returns the grid .
Pathfinder:setWalkable (walkable)	Sets the walkable value or function.
Pathfinder:getWalkable ()	Gets the walkable value or function.
Pathfinder:setFinder (finderName)	Defines the `finder`.
Pathfinder:getFinder ()	Returns the name of the `finder` being used.
Pathfinder:getFinders ()	Returns the list of all available finders names.
Pathfinder:setHeuristic (heuristic)	Sets a heuristic.
Pathfinder:getHeuristic ()	Returns the `heuristic` used.
Pathfinder:getHeuristics ()	Gets the list of all available `heuristics`.
Pathfinder:setMode (mode)	Defines the search `mode`.
Pathfinder:getMode ()	Returns the search mode.
Pathfinder:getModes ()	Gets the list of all available search modes.
Pathfinder:setTunnelling (bool)	Enables tunnelling.
Pathfinder:getTunnelling ()	Returns tunnelling feature state.
Pathfinder:getPath (startX, startY, endX, endY, clearance)	Calculates a `path`.
Pathfinder:reset ()	Resets the pathfinder .

Finders

Finders

Finders (search algorithms implemented). Refers to the search algorithms actually implemented in Jumper.

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

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 to ASTAR 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: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:clearAnnotations ()

Removes clearancevalues. Clears cached clearance values for the current walkable.

Usage:

myFinder:clearAnnotations()

Returns:

Pathfinder:setGrid (grid)

Sets the grid . Defines the given grid as the one on which the pathfinder will perform the search.

Parameters:

grid grid a grid

Usage:

myFinder:setGrid(myGrid)

Returns:

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:

walkable string, int or func the value for walkable nodes.

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:getWalkable ()

Gets the walkable value or function.

Usage:

local walkable = myFinder:getWalkable()

Returns:

string, int or func

walkable

Pathfinder:setFinder (finderName)

Defines the finder. It refers to the search algorithm used by the pathfinder . 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.

Usage:

 --To use Breadth-First-Search
 myFinder:setFinder('BFS')

Returns:

Usage:

local finderName = myFinder:getFinder()

Returns:

string

finder

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,...}

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 own heuristic function.

Parameters:

heuristic func or string heuristic function, prototyped as f(dx,dy) or as a string .

Usage:

myFinder:setHeuristic('MANHATTAN')

Returns:

Usage:

local h = myFinder:getHeuristic()

Returns:

func

heuristic

Usage:

 local heur = myFinder:getHeuristic()
 for i, heuristicName in ipairs(heur) do
   ...
 end

Returns:

{string,...}

Parameters:

mode string the new search mode.

Usage:

myFinder:setMode('ORTHOGNAL')

Returns:

Usage:

local mode = myFinder:getMode()

Returns:

string

Usage:

 local modes = myFinder:getModes()
 for modeName in ipairs(modes) do
   ...
 end

Returns:

{string,...}

Parameters:

bool bool a boolean

Usage:

myFinder:setTunnelling(true)

Returns:

Pathfinder:getTunnelling ()

Returns tunnelling feature state.

Usage:

local isTunnellingEnabled = myFinder:getTunnelling()

Returns:

bool

Pathfinder:getPath (startX, startY, endX, endY, clearance)

Calculates a path. Returns the path 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

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: