Module jumper.grid
The grid class API.
Implementation of a `grid` class, which represents the 2D map (graph) on which a `pathfinder` will perform.
During a search, the pathfinder evaluates __costs values__ for each node being processed, in order to select, after each step of iteration, what node should be expanded next to reach the target optimally. Those values are cached within an array of nodes inside the `grid` object.
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
-- Creates a grid object
local grid = Grid(map)
Info:
- Copyright: 2012-2013
- License: MIT
- Author: Roland Yonaba
Functions
| new (map[, processOnDemand]) | Inits a new `grid` object |
| isWalkableAt (x, y, walkable) | Checks walkability. |
| getWidth () | Gets the `grid` width. |
| getHeight () | Gets the `grid` height. |
| getMap () | Gets the collision map. |
| getNodes () | Gets the `grid` nodes. |
| getNeighbours (node, walkable[, allowDiagonal[, tunnel]]) | Returns the neighbours of a given `node` on a `grid` |
| iter ([lx[, ly[, ex[, ey]]]]) | Iterates on nodes on the grid. |
| each (f[, ...]) | Each transformation. |
| eachRange (lx, ly, ex, ey, f[, ...]) | Each in range transformation. |
| imap (f[, ...]) | Map transformation. |
| imapRange (lx, ly, ex, ey, f[, ...]) | Map in range transformation. |
| getNodeAt (x, y) | Returns the `node`[x,y] on a `grid`. |
Tables
| grid | The `grid` class |
Functions
- new (map[, processOnDemand])
-
Inits a new `grid` object
Parameters:
- map table or string A collision map - (2D array) with consecutive integer indices or a string with line-break symbol as a row delimiter.
- processOnDemand bool whether or not caching nodes in the internal grid should be processed on-demand (optional)
Returns:
-
grid
a new `grid` object
- isWalkableAt (x, y, walkable)
-
Checks walkability. Tests if `node` [x,y] exists on the collision map and is walkable
Parameters:
- x int the x-coordinate of the node
- y int the y-coordinate of the node
- 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. If this parameter is not given and node [x,y] exists, this function return `true`.
Returns:
-
bool
`true` if the node exist and is walkable, `false` otherwise
- getWidth ()
-
Gets the `grid` width.
Returns:
-
int
the `grid` object width
- getHeight ()
-
Gets the `grid` height.
Returns:
-
int
the `grid` object height
- getMap ()
-
Gets the collision map.
Returns:
-
{{value},...}
the collision map previously passed to the `grid` object on initalization
- getNodes ()
-
Gets the `grid` nodes.
Returns:
-
{{node},...}
the `grid` nodes
- getNeighbours (node, walkable[, allowDiagonal[, tunnel]])
-
Returns the neighbours of a given `node` on a `grid`
Parameters:
- node node `node` object
- 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.
- allowDiagonal bool whether or not adjacent nodes (8-directions moves) are allowed (optional)
- tunnel bool Whether or not the pathfinder can tunnel though walls diagonally (optional)
Returns:
-
{node,...}
an array of nodes neighbouring a passed-in node on the collision map
- iter ([lx[, ly[, ex[, ey]]]])
-
Iterates on nodes on the grid. When given no args, will iterate on every single node
on the grid, in case the grid is pre-processed. Passing `lx, ly, ex, ey` args will iterate
on nodes inside a bounding-rectangle delimited by those coordinates.
Parameters:
- lx int the leftmost x-coordinate coordinate of the rectangle (optional)
- ly int the topmost y-coordinate of the rectangle (optional)
- ex int the rightmost x-coordinate of the rectangle (optional)
- ey int the bottom-most y-coordinate of the rectangle (optional)
Returns:
-
node
a node on the collision map, upon each iteration step
- each (f[, ...])
-
Each transformation. Executes a function on each `node` in the `grid`, passing the `node` as the first arg to function `f`.
Parameters:
- f function a function prototyped as `f(node,...)`
- ... vararg args to be passed to function `f` (optional)
- eachRange (lx, ly, ex, ey, f[, ...])
-
Each in range transformation. Executes a function on each `node` in the range of a rectangle of cells, passing the `node` as the first arg 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 function a function prototyped as `f(node,...)`
- ... vararg args to be passed to function `f` (optional)
- imap (f[, ...])
-
Map transformation. Maps function `f(node,...)` on each `node` in a given range, passing the `node` as the first arg to function `f`. The passed-in function should return a `node` object.
Parameters:
- f function a function prototyped as `f(node,...)`
- ... vararg args to be passed to function `f` (optional)
- imapRange (lx, ly, ex, ey, f[, ...])
-
Map in range transformation. Maps `f(node,...)` on each `nod`e in the range of a rectangle of cells, passing the `node` as the first arg to function `f`. The passed-in function should return a `node` object.
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 function a function prototyped as `f(node,...)`
- ... vararg args to be passed to function `f` (optional)
- getNodeAt (x, y)
-
Returns the `node`[x,y] on a `grid`.
Parameters:
- x int the x-coordinate coordinate
- y int the y-coordinate coordinate
Returns:
-
node
a `node` object
Gets the node at location