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 a new grid instance
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 if node exists and is walkable, false otherwise
Grid:getWidth ()
Returns the grid width.

Usage:

    print(myGrid:getWidth())

Returns:

    int the grid width
Grid:getHeight ()
Returns the grid height.

Usage:

    print(myGrid:getHeight())

Returns:

    int the grid height
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:

  1. int the upper-left corner x-coordinate
  2. int the upper-left corner y-coordinate
  3. int the lower-right corner x-coordinate
  4. 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,...} an array of nodes neighbouring a given 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:

  1. node a node on the collision map, upon each iteration step
  2. 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
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 self (the calling grid itself, can be chained)
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 self (the calling grid itself, can be chained)
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 self (the calling grid itself, can be chained)
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 self (the calling grid itself, can be chained)
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 a node
generated by LDoc 1.2