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

grid:new (map[, processOnDemand]) Inits a new grid object
grid:isWalkableAt (x, y, walkable) Checks walkability.
grid:getWidth () Gets the grid width.
grid:getHeight () Gets the grid height.
grid:getMap () Gets the collision map.
grid:getNodes () Gets the grid nodes.
grid:getNeighbours (node, walkable[, allowDiagonal[, tunnel]]) Returns the neighbours of a given node on a grid
grid:iter ([lx[, ly[, ex[, ey]]]]) Iterates on nodes on the grid.
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[x,y] on a grid .

Tables

grid The grid class


Functions

grid: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

Returns:

    grid a new grid object
grid: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
grid:getWidth ()
Gets the grid width.

Returns:

    int the grid object width
grid:getHeight ()
Gets the grid height.

Returns:

    int the grid object height
grid:getMap ()
Gets the collision map.

Returns:

    {{value},...} the collision map previously passed to the grid object on initalization
grid:getNodes ()
Gets the grid nodes.

Returns:

    {{node},...} the grid nodes
grid: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
  • tunnel bool Whether or not the pathfinder can tunnel though walls diagonally

Returns:

    {node,...} an array of nodes neighbouring a passed-in node on the collision map
grid: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
  • 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

Returns:

    node a node on the collision map, upon each iteration step
grid: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
grid: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
grid: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
grid:imapRange (lx, ly, ex, ey, f[, ...])
Map in range transformation. Maps f(node,...) on each node 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
grid: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 on a preprocessed grid

Tables

grid
The grid class

Fields:

  • width The grid width
  • height The grid height
  • map A reference to the collision map
  • nodes A 2D array of nodes, each node matching a cell on the collision map
generated by LDoc 1.3