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:
- map
table or string
A collision map - (2D array) with consecutive indices (starting at 0 or 1)
or a string with line-break chars (
- Grid:isWalkableAt (x, y [, walkable [, clearance]])
-
Checks if
node
at [x,y] is walkable. Will check ifnode
at location [x,y] both exists on the collision map and is walkableParameters:
- 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 if
node
exists and is walkable, false otherwise - Grid:getWidth ()
-
Returns the grid width.
Usage:
print(myGrid:getWidth())
Returns:
- Grid:getHeight ()
-
Returns the grid height.
Usage:
print(myGrid:getHeight())
Returns:
- Grid:getMap ()
-
Returns the collision map.
Usage:
local map = myGrid:getMap()
Returns:
-
map
the collision map (see Grid:new)
- Grid:getNodes ()
-
Returns the set of nodes.
Usage:
local nodes = myGrid:getNodes()
Returns:
-
{{node,...},...}
an array of nodes
- 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:
- 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,...}
an array of nodes neighbouring a given node
- node
node
a given
- 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
a
node
at each iteration step - node
node
a given
- Grid:each (f [, ...])
-
Each transformation. Calls the given function on each
node
in the grid , passing thenode
as the first argument to function f.Parameters:
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 thenode
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 thenode
as the first arg to function f and replaces it with the returned value. Therefore, the function should return anode
.Parameters:
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 thenode
as the first argument to the function and replaces it with the returned value. Therefore, the function should return anode
.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:
Usage:
local aNode = myGrid:getNodeAt(2,2)
Returns:
-
node
a
node