annotatedpathing.lua\n-- Tests sample for clearance metrics calculation\n-- See Figure 10 at http://aigamedev.com/open/tutorial/clearance-based-pathfinding/\n-- Jump Point Search still has some flaws with clearance based pathfinding\n\nlocal Grid = require 'jumper.grid'\nlocal PF = require 'jumper.pathfinder'\nlocal map = {\n\t{0,0,0,0,0,0,0,0,0,0},\n\t{0,0,0,0,0,0,0,0,1,0},\n\t{0,0,0,0,0,0,0,0,0,0},\n\t{0,0,0,1,0,0,0,0,0,0},\n\t{0,0,1,0,0,0,0,0,2,0},\n\t{0,0,1,1,1,0,0,2,0,0},\n\t{0,0,0,1,1,0,2,0,0,2},\n\t{0,0,0,0,1,0,0,0,0,2},\n\t{0,0,0,0,0,0,0,0,0,0},\n\t{0,0,0,0,0,0,0,0,0,0}\n}\nlocal grid = Grid(map)\nlocal walkable = function(v) return v~=2 end\nlocal finder = PF(grid, 'ASTAR',walkable)\nfinder:annotateGrid()\nlocal finderNames = PF:getFinders()\n\nlocal sx, sy = 1,1\nlocal ex, ey = 9,9\nlocal agent_size = 2\n\nfor i = 1,#finderNames do\n\tfinder:setFinder(finderNames[i])\n\tlocal path = finder:getPath(sx, sy, ex, ey, agent_size)\n\tprint(('Algorithm used: %s - Path %s')\n\t\t:format(finder:getFinder(), path and 'found' or 'not found'))\n\tif path then\n\t\tfor node, count in path:nodes() do\n\t\t\tprint((' Step %d. (%d,%d)')\n\t\t\t\t:format(count, node:getPos()))\n\t\tend\n\tend\nend\n\n\n
customheuristics.lua\n--- Example of use for Heuristics\n\nlocal Grid = require (\"jumper.grid\")\nlocal Pathfinder = require (\"jumper.pathfinder\")\n\nlocal map = {\n {0,0,0,0,0,0},\n {0,0,0,0,0,0},\n {0,1,1,1,1,0},\n {0,0,0,0,0,0},\n {0,0,0,0,0,0},\n}\n\nlocal walkable = 0\nlocal grid = Grid(map)\nlocal myFinder = Pathfinder(grid, 'ASTAR', walkable)\n\n-- Use Euclidian heuristic to evaluate distance\nmyFinder:setHeuristic('EUCLIDIAN')\nmyFinder:setHeuristic('DIAGONAL')\nmyFinder:setHeuristic('MANHATTAN')\n\n-- Custom\nlocal h = function(nodeA, nodeB)\n\treturn (0.1 * (math.abs(nodeA:getX() - nodeB:getX()))\n\t + 0.9 * (math.abs(nodeA:getY() - nodeB:getY())))\nend\nmyFinder:setHeuristic(h)\n\nlocal p = myFinder:getPath(1,1, 6,5)\nfor node, count in p:nodes() do\n print(('%d. Node(%d,%d)'):format(count, node:getX(), node:getY()))\nend\nprint(('Path length: %.2f'):format(p:getLength()))\n\n-- etc ...\n\n\n\n
makeclearance.lua\n-- Tests sample for clearance metrics calculation\n-- See Figure 10 at http://aigamedev.com/open/tutorial/clearance-based-pathfinding/\nlocal Grid = require 'jumper.grid'\nlocal PF = require 'jumper.pathfinder'\nlocal map = {\n\t{0,0,0,0,0,0,0,0,0,0},\n\t{0,0,0,0,0,0,0,0,1,0},\n\t{0,0,0,0,0,0,0,0,0,0},\n\t{0,0,0,1,0,0,0,0,0,0},\n\t{0,0,1,0,0,0,0,0,2,0},\n\t{0,0,1,1,1,0,0,2,0,0},\n\t{0,0,0,1,1,0,2,0,0,2},\n\t{0,0,0,0,1,0,0,0,0,2},\n\t{0,0,0,0,0,0,0,0,0,0},\n\t{0,0,0,0,0,0,0,0,0,0}\n}\nlocal grid = Grid(map)\nlocal walkable = function(v) return v~=2 end\nlocal finder = PF(grid, 'ASTAR',walkable)\nfinder:annotateGrid()\n\nfor y = 1, #map do\n\tlocal s = ''\n\tfor x = 1, #map[y] do\n\t local node = grid:getNodeAt(x,y)\n\t\ts = (s .. ' ' .. node:getClearance(walkable))\n\tend\n\tprint(s)\nend\n\n-- Expected output\n-- 6 6 5 5 4 4 4 3 2 1\n-- 6 5 5 4 4 3 3 3 2 1\n-- 6 5 4 4 3 3 2 2 2 1\n-- 6 5 4 3 3 2 2 1 1 1\n-- 6 5 4 3 2 2 1 1 0 1\n-- 5 5 4 3 2 1 1 0 1 1\n-- 4 4 4 3 2 1 0 2 1 0\n-- 3 3 3 3 3 3 3 2 1 0\n-- 2 2 2 2 2 2 2 2 2 1\n-- 1 1 1 1 1 1 1 1 1 1\n\n\n\n
simpleexample.lua\n--- Very minimal usage example for Jumper\n\n-- Set up a collision map\nlocal map = {\n\t{0,1,0,1,0},\n\t{0,1,0,1,0},\n\t{0,1,1,1,0},\n\t{0,0,0,0,0},\n}\n-- Value for walkable tiles\nlocal walkable = 0\n\n-- Library setup\n-- Calls the grid class\nlocal Grid = require (\"jumper.grid\")\n-- Calls the pathfinder class\nlocal Pathfinder = require (\"jumper.pathfinder\")\n\n-- Creates a grid object\nlocal grid = Grid(map)\n\n-- Creates a pathfinder object using Jump Point Search algorithm\nlocal myFinder = Pathfinder(grid, 'JPS', walkable)\n\n-- Define start and goal locations coordinates\nlocal startx, starty = 1,1\nlocal endx, endy = 5,1\n\n-- Calculates the path, and its length\nlocal path = myFinder:getPath(startx, starty, endx, endy)\n\n-- Pretty-printing the results\nif path then\n print(('Path found! Length: %.2f'):format(path:getLength()))\n\tfor node, count in path:nodes() do\n\t print(('Step: %d - x: %d - y: %d'):format(count, node:getX(), node:getY()))\n\tend\nend\n\n\n
| core.bheap | \n\t\tA light implementation of Binary heaps data structure. | \n\t
| core.heuristics | \n\t\tHeuristic functions for search algorithms. | \n\t
| core.node | \n\t\tThe Node class. | \n\t
| core.path | \n\t\tThe Path class. | \n\t
| grid | \n\t\tThe Grid class. | \n\t
| pathfinder | \n\t\tThe Pathfinder class | \n\t
| annotatedpathing.lua | \n\t\t\n\t |
| customheuristics.lua | \n\t\t\n\t |
| makeclearance.lua | \n\t\t\n\t |
| simpleexample.lua | \n\t\t\n\t |
core.bheapA light implementation of Binary heaps data structure.
\nWhile running a search, some search algorithms (Astar, Dijkstra, Jump Point Search) have to maintains\n a list of nodes called open list. Retrieve from this list the lowest cost node can be quite slow,\n as it normally requires to skim through the full set of nodes stored in this list. This becomes a real\n problem especially when dozens of nodes are being processed (on large maps).
\n\nThe current module implements a binary heap\n data structure, from which the search algorithm will instantiate an open list, and cache the nodes being\n examined during a search. As such, retrieving the lower-cost node is faster and globally makes the search end\n up quickly.
\n\nThis module is internally used by the library on purpose.\n It should normally not be used explicitely, yet it remains fully accessible.
\n\n| heap:empty () | \n\tChecks if a heap is empty | \n\t
| heap:clear () | \n\tClears the heap (removes all items queued in the heap) | \n\t
| heap:push (item) | \n\tAdds a new item in the heap | \n\t
| heap:pop () | \n\tPops from the heap . | \n\t
| heap:heapify ( [item]) | \n\tRestores the heap property. | \n\t
heap(...) is used to instantiate new heaps.\n \n if myHeap:empty() then\n print('Heap is empty!')\n end\n \n\n myHeap:clear()\n \n\n
\n myHeap:push(1)\n -- or, with chaining\n myHeap:push(1):push(2):push(4)\n \n\n
\n while not myHeap:empty() do\n local lowestValue = myHeap:pop()\n ...\n end\n \n\n
myHeap:heapify()\n \n\n
core.heuristicsHeuristic functions for search algorithms.
\nA distance heuristic\n provides an estimate of the optimal distance cost from a given location to a target.\n As such, it guides the pathfinder to the goal, helping it to decide which route is the best.
\n\nThis script holds the definition of some built-in heuristics available through jumper.
\n\nDistance functions are internally used by the pathfinder to evaluate the optimal path\n from the start location to the goal. These functions share the same prototype:
\n local function myHeuristic(nodeA, nodeB)\n -- function body\n end\n Jumper features some built-in distance heuristics, namely MANHATTAN, EUCLIDIAN, DIAGONAL, CARDINTCARD.\n You can also supply your own heuristic function, following the same template as above.
| Heuristics.MANHATTAN (nodeA, nodeB) | \n\tManhattan distance. | \n\t
| Heuristics.EUCLIDIAN (nodeA, nodeB) | \n\tEuclidian distance. | \n\t
| Heuristics.DIAGONAL (nodeA, nodeB) | \n\tDiagonal distance. | \n\t
| Heuristics.CARDINTCARD (nodeA, nodeB) | \n\tCardinal/Intercardinal distance. | \n\t
distance = |dx|+|dy|\n\n \n -- First method\n pathfinder:setHeuristic('MANHATTAN')\n -- Second method\n local Distance = require ('jumper.core.heuristics')\n pathfinder:setHeuristic(Distance.MANHATTAN)\n \n\n distance = squareRoot(dxdx+dydy)\n\n \n -- First method\n pathfinder:setHeuristic('EUCLIDIAN')\n -- Second method\n local Distance = require ('jumper.core.heuristics')\n pathfinder:setHeuristic(Distance.EUCLIDIAN) \n \n\n distance = max(|dx|, abs|dy|)\n\n \n -- First method\n pathfinder:setHeuristic('DIAGONAL')\n -- Second method\n local Distance = require ('jumper.core.heuristics')\n pathfinder:setHeuristic(Distance.DIAGONAL)\n \n\n distance = min(dx, dy)*squareRoot(2) + max(dx, dy) - min(dx, dy)\n\n \n -- First method\n pathfinder:setHeuristic('CARDINTCARD')\n -- Second method\n local Distance = require ('jumper.core.heuristics')\n pathfinder:setHeuristic(Distance.CARDINTCARD)\n \n\n core.nodeThe Node class.
\nThe node represents a cell (or a tile) on a collision map. Basically, for each single cell (tile)\n in the collision map passed-in upon initialization, a node object will be generated\n and then cached within the grid .
\n\n In the following implementation, nodes can be compared using the < operator. The comparison is\n made with regards of their f cost. From a given node being examined, the pathfinder will expand the search\n to the next neighbouring node having the lowest f cost. See core.bheap for more details.\n
| Node:new (x, y) | \n\tInits a new node | \n\t
| Node:getX () | \n\tReturns x-coordinate of a node | \n\t
| Node:getY () | \n\tReturns y-coordinate of a node | \n\t
| Node:getPos () | \n\tReturns x and y coordinates of a node | \n\t
| Node:getClearance (walkable) | \n\tReturns the amount of true clearance\n for a given node | \n\t
| Node:removeClearance (walkable) | \n\tRemoves the clearance value for a given walkable. | \n\t
| Node:reset () | \n\tClears temporary cached attributes of a node . | \n\t
Node(...) acts as a shortcut to Node:new(...).\n local node = Node(3,4)\n \n\n
local x = node:getX()\n \n\n
local y = node:getY()\n \n\n
local x, y = node:getPos()\n \n\n
\n -- Assuming walkable was 0\n local clearance = node:getClearance(0)\t\t\n \n\n
\n -- Assuming walkable is defined\n node:removeClearance(walkable)\t\n \n\n
\n local thisNode = Node(1,2)\n thisNode:reset()\n \n\n
core.pathThe Path class.
\n The path class is a structure which represents a path (ordered set of nodes) from a start location to a goal.\n 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.\n It should normally not be used explicitely, yet it remains fully accessible.
\n\n| Path:new () | \n\tInits a new path . | \n\t
| Path:iter () | \n\tIterates on each single node along a path . | \n\t
| Path:nodes () | \n\tIterates on each single node along a path . | \n\t
| Path:getLength () | \n\tEvaluates the path length | \n\t
| Path:addNode (node [, index]) | \n\tCounts the number of steps. | \n\t
| Path:fill () | \n\tPath filling modifier. | \n\t
| Path:filter () | \n\tPath compression modifier. | \n\t
| Path:clone () | \n\tClones a path . | \n\t
| Path:isEqualTo (p2) | \n\tChecks if a path is equal to another. | \n\t
| Path:reverse () | \n\tReverses a path . | \n\t
| Path:append (p) | \n\tAppends a given path to self. | \n\t
Path(...) acts as a shortcut to Path:new(...).\n local p = Path()\n \n\n
\n for node, count in p:iter() do\n ...\n end\n \n\n
\n for node, count in p:nodes() do\n ...\n end\t\n \n\n
local len = p:getLength()\n \n\n
local nSteps = p:countSteps()\n \n\n
p:fill()\n \n\n
p:filter()\n \n\n
local p = path:clone()\n \n\n
print(myPath:isEqualTo(anotherPath))\n \n\n
myPath:reverse()\n \n\n
myPath:append(anotherPath)\n \n\n
gridThe Grid class.
\n Implementation of the grid class.\n The grid is a implicit graph which represents the 2D\n world map layout on which the pathfinder object will run.\n During a search, the pathfinder object needs to save some critical values. These values are cached within each node\n object, and the whole set of nodes are tight inside the grid object itself.
| Grid:new (map [, cacheNodeAtRuntime]) | \n\tInits a new grid | \n\t
| Grid:isWalkableAt (x, y [, walkable [, clearance]]) | \n\tChecks if node at [x,y] is walkable. | \n\t
| Grid:getWidth () | \n\tReturns the grid width. | \n\t
| Grid:getHeight () | \n\tReturns the grid height. | \n\t
| Grid:getMap () | \n\tReturns the collision map. | \n\t
| Grid:getNodes () | \n\tReturns the set of nodes. | \n\t
| Grid:getBounds () | \n\tReturns the grid bounds. | \n\t
| Grid:getNeighbours (node [, walkable [, allowDiagonal [, tunnel [, clearance]]]]) | \n\tReturns neighbours. | \n\t
| Grid:iter ( [lx [, ly [, ex [, ey]]]]) | \n\tGrid iterator. | \n\t
| Grid:around (node [, radius]) | \n\tGrid iterator. | \n\t
| Grid:each (f [, ...]) | \n\tEach transformation. | \n\t
| Grid:eachRange (lx, ly, ex, ey, f [, ...]) | \n\tEach (in range) transformation. | \n\t
| Grid:imap (f [, ...]) | \n\tMap transformation. | \n\t
| Grid:imapRange (lx, ly, ex, ey, f [, ...]) | \n\tMap in range transformation. | \n\t
| Grid:getNodeAt (x, y) | \n\tReturns the node at location [x,y]. | \n\t
Grid(...) acts as a shortcut to Grid:new(...).\n \\n or \\r) as row delimiters.node will cause it to be created and cache within the grid on purpose (i.e, when needed).\n This is a memory-safe option, in case your dealing with some tight memory constraints.\n Defaults to false when omitted.\n -- A simple 3x3 grid\n local myGrid = Grid:new({{0,0,0},{0,0,0},{0,0,0}})\n\n -- A memory-safe 3x3 grid\n myGrid = Grid('000\\n000\\n000', true)\n \n\n node at [x,y] is walkable.\n Will check if node at location [x,y] both exists on the collision map and is walkable\n\n node, false otherwise. If this parameter is not given\n while location [x,y] is valid, this actual function returns true.\n -- Always true\n print(myGrid:isWalkableAt(2,3))\n\n -- True if node at [2,3] collision map value is 0\n print(myGrid:isWalkableAt(2,3,0))\n\n -- True if node at [2,3] collision map value is 0 and has a clearance higher or equal to 2\n print(myGrid:isWalkableAt(2,3,0,2))\n\n \n\n
node exists and is walkable, false otherwise\n print(myGrid:getWidth())\n \n\n
print(myGrid:getHeight())\n \n\n
local map = myGrid:getMap()\n \n\n
local nodes = myGrid:getNodes()\n \n\n
local left_x, left_y, right_x, right_y = myGrid:getBounds()\n \n\n
node.\n\n node\n local aNode = myGrid:getNodeAt(5,6)\n local neighbours = myGrid:getNeighbours(aNode, 0, true)\n \n\n
\n for node, count in myGrid:iter() do\n print(node:getX(), node:getY(), count)\n end\n \n\n
node on the collision map, upon each iteration stepnode\n for node in myGrid:around(node, 2) do\n ...\n end\n \n\n
node at each iteration step\n node in the grid ,\n passing the node as the first argument to function f.\n\n \n local function printNode(node)\n print(node:getX(), node:getY())\n end\n myGrid:each(printNode)\n \n\n
node in the range of a rectangle of cells,\n passing the node as the first argument to function f.\n\n \n local function printNode(node)\n print(node:getX(), node:getY())\n end\n myGrid:eachRange(1,1,8,8,printNode)\n \n\n
node in a given range, passing the node as the first arg to function f and replaces\n it with the returned value. Therefore, the function should return a node.\n\n \n local function nothing(node)\n return node\n end\n myGrid:imap(nothing)\n \n\n
node in a rectangle range, passing the node as the first argument to the function and replaces\n it with the returned value. Therefore, the function should return a node.\n\n \n local function nothing(node)\n return node\n end\n myGrid:imap(1,1,6,6,nothing)\n \n\n
node at location [x,y].\n\n local aNode = myGrid:getNodeAt(2,2)\n \n\n
node\n pathfinderThe Pathfinder class
\n\n\n
\n\n| Finders | \n\tFinders (search algorithms implemented). | \n\t
| Modes | \n\tSearch modes. | \n\t
| Pathfinder:new (grid [, finderName [, walkable]]) | \n\tInits a new pathfinder | \n\t
| Pathfinder:annotateGrid () | \n\tEvaluates clearance\n for the whole grid . | \n\t
| Pathfinder:clearAnnotations () | \n\tRemoves clearancevalues. | \n\t
| Pathfinder:setGrid (grid) | \n\tSets the grid . | \n\t
| Pathfinder:getGrid () | \n\tReturns the grid . | \n\t
| Pathfinder:setWalkable (walkable) | \n\tSets the walkable value or function. | \n\t
| Pathfinder:getWalkable () | \n\tGets the walkable value or function. | \n\t
| Pathfinder:setFinder (finderName) | \n\tDefines the finder. | \n\t
| Pathfinder:getFinder () | \n\tReturns the name of the finder being used. | \n\t
| Pathfinder:getFinders () | \n\tReturns the list of all available finders names. | \n\t
| Pathfinder:setHeuristic (heuristic) | \n\tSets a heuristic. | \n\t
| Pathfinder:getHeuristic () | \n\tReturns the heuristic used. | \n\t
| Pathfinder:getHeuristics () | \n\tGets the list of all available heuristics. | \n\t
| Pathfinder:setMode (mode) | \n\tDefines the search mode. | \n\t
| Pathfinder:getMode () | \n\tReturns the search mode. | \n\t
| Pathfinder:getModes () | \n\tGets the list of all available search modes. | \n\t
| Pathfinder:setTunnelling (bool) | \n\tEnables tunnelling. | \n\t
| Pathfinder:getTunnelling () | \n\tReturns tunnelling feature state. | \n\t
| Pathfinder:getPath (startX, startY, endX, endY, clearance) | \n\tCalculates a path. | \n\t
| Pathfinder:reset () | \n\tResets the pathfinder . | \n\t
Pathfinder(...) acts as a shortcut to Pathfinder:new(...).\n Finder (search algorithm) to be used for search.\n Defaults to ASTAR when not given (see Pathfinder:getFinders).node, false otherwise.\n -- Example one\n local finder = Pathfinder:new(myGrid, 'ASTAR', 0)\n\n -- Example two\n local function walkable(value)\n return value > 0\n end\n local finder = Pathfinder(myGrid, 'JPS', walkable)\n \n\n
myFinder:annotateGrid()\n \n\n
myFinder:clearAnnotations()\n \n\n
myFinder:setGrid(myGrid)\n \n\n
local myGrid = myFinder:getGrid()\n \n\n
\n -- Value '0' is walkable\n myFinder:setWalkable(0)\n\n -- Any value greater than 0 is walkable\n myFinder:setWalkable(function(n)\n return n>0\n end\n \n\n
local walkable = myFinder:getWalkable()\n \n\n
finder. It refers to the search algorithm used by the pathfinder .\n Default finder is ASTAR. Use Pathfinder:getFinders to get the list of available finders.\n\n finder to be used for further searches.\n --To use Breadth-First-Search\n myFinder:setFinder('BFS')\n \n\n finder being used.\n\n\n local finderName = myFinder:getFinder()\n \n\n
finder to be used for further searches.\n \n local finders = myFinder:getFinders()\n for i, finderName in ipairs(finders) do\n print(i, finderName)\n end\n \n\n
heuristics. One can also define\n his own heuristic function.\n\n myFinder:setHeuristic('MANHATTAN')\n \n\n heuristic used. Returns the function itself.\n\n\n local h = myFinder:getHeuristic()\n \n\n
heuristic function being used by the pathfinder\n heuristics.\n\n\n \n local heur = myFinder:getHeuristic()\n for i, heuristicName in ipairs(heur) do\n ...\n end\n \n\n
mode.\n The default search mode is the DIAGONAL mode, which implies 8-possible directions when moving (north, south, east, west and diagonals).\n In ORTHOGONAL mode, only 4-directions are allowed (north, south, east and west).\n Use Pathfinder:getModes to get the list of all available search modes.\n\n mode.myFinder:setMode('ORTHOGNAL')\n \n\n local mode = myFinder:getMode()\n \n\n
local modes = myFinder:getModes()\n for modeName in ipairs(modes) do\n ...\n end\n \n\n
myFinder:setTunnelling(true)\n \n\n
local isTunnellingEnabled = myFinder:getTunnelling()\n \n\n
path. Returns the path from location [startX, startY] to location [endX, endY].\n Both locations must exist on the collision map. The starting location can be unwalkable.\n\n local path = myFinder:getPath(1,1,5,5)\n \n\n
local path, len = myFinder:getPath(1,1,5,5)\n \n\n
heap(...) _is used to instantiate new heaps_.\n\t-- @type heap\n\tlocal heap = setmetatable({},\n\t\t{__call = function(self,...)\n\t\t\treturn newHeap(self,...)\n\t\tend})\n\theap.__index = heap\n\n\t--- Checks if a `heap` is empty\n\t-- @class function\n\t-- @treturn bool __true__ of no item is queued in the heap, __false__ otherwise\n\t-- @usage\n\t-- if myHeap:empty() then \n\t-- print('Heap is empty!')\n\t-- end\n\tfunction heap:empty()\n\t\treturn (self._size==0)\n\tend\n\n\t--- Clears the `heap` (removes all items queued in the heap)\n\t-- @class function\n\t-- @treturn heap self (the calling `heap` itself, can be chained)\n\t-- @usage myHeap:clear()\n\tfunction heap:clear()\n\t\tself._heap = {}\n\t\tself._size = 0\n\t\tself._sort = self._sort or f_min\n\t\treturn self\n\tend\n\n\t--- Adds a new item in the `heap`\n\t-- @class function\n\t-- @tparam value item a new value to be queued in the heap\n\t-- @treturn heap self (the calling `heap` itself, can be chained)\n\t-- @usage\n\t-- myHeap:push(1)\n\t-- -- or, with chaining\n\t-- myHeap:push(1):push(2):push(4)\n\tfunction heap:push(item)\n\t\tif item then\n\t\t\tself._size = self._size + 1\n\t\t\tself._heap[self._size] = item\n\t\t\tpercolate_up(self, self._size)\n\t\tend\n\t\treturn self\n\tend\n\n\t--- Pops from the `heap`.\n\t-- Removes and returns the lowest cost item (with respect to the comparison function being used) from the `heap`.\n\t-- @class function\n\t-- @treturn value a value previously pushed into the heap\n\t-- @usage\n\t-- while not myHeap:empty() do \n\t-- local lowestValue = myHeap:pop()\n\t-- ...\n\t-- end\n\tfunction heap:pop()\n\t\tlocal root\n\t\tif self._size > 0 then\n\t\t\troot = self._heap[1]\n\t\t\tself._heap[1] = self._heap[self._size]\n\t\t\tself._heap[self._size] = nil\n\t\t\tself._size = self._size-1\n\t\t\tif self._size>1 then\n\t\t\t\tpercolate_down(self, 1)\n\t\t\tend\n\t\tend\n\t\treturn root\n\tend\n\n\t--- Restores the `heap` property.\n\t-- Reorders the `heap` with respect to the comparison function being used. \n\t-- When given argument __item__ (a value existing in the `heap`), will sort from that very item in the `heap`. \n\t-- Otherwise, the whole `heap` will be cheacked. \n\t-- @class function\n\t-- @tparam[opt] value item the modified value\n\t-- @treturn heap self (the calling `heap` itself, can be chained)\n\t-- @usage myHeap:heapify() \n\tfunction heap:heapify(item)\n\t\tif self._size == 0 then return end\n\t\tif item then\n\t\t\tlocal i = Utils.indexOf(self._heap,item)\n\t\t\tif i then \n\t\t\t\tpercolate_down(self, i)\n\t\t\t\tpercolate_up(self, i)\n\t\t\tend\n\t\t\treturn\n\t\tend\n\t\tfor i = floor(self._size/2),1,-1 do\n\t\t\tpercolate_down(self,i)\n\t\tend\n\t\treturn self\n\tend\n\n\treturn heap\nend"
},
{
"path": "jumper/core/heuristics.lua",
"content": "--- Heuristic functions for search algorithms.\n-- A distance heuristic \n-- provides an *estimate of the optimal distance cost* from a given location to a target. \n-- As such, it guides the pathfinder to the goal, helping it to decide which route is the best.\n--\n-- This script holds the definition of some built-in heuristics available through jumper.\n--\n-- Distance functions are internally used by the `pathfinder` to evaluate the optimal path\n-- from the start location to the goal. These functions share the same prototype:\n-- local function myHeuristic(nodeA, nodeB)\n-- -- function body\n-- end\n-- Jumper features some built-in distance heuristics, namely `MANHATTAN`, `EUCLIDIAN`, `DIAGONAL`, `CARDINTCARD`.\n-- You can also supply your own heuristic function, following the same template as above.\n\n\nlocal abs = math.abs\nlocal sqrt = math.sqrt\nlocal sqrt2 = sqrt(2)\nlocal max, min = math.max, math.min\n\nlocal Heuristics = {}\n --- Manhattan distance.\n -- distance = |dx|+|dy|\n -- @class function\n -- @tparam node nodeA a node\n -- @tparam node nodeB another node\n -- @treturn number the distance from __nodeA__ to __nodeB__\n\t-- @usage\n -- -- First method\n -- pathfinder:setHeuristic('MANHATTAN')\n -- -- Second method\n -- local Distance = require ('jumper.core.heuristics')\n -- pathfinder:setHeuristic(Distance.MANHATTAN)\n function Heuristics.MANHATTAN(nodeA, nodeB) \n\t\tlocal dx = abs(nodeA._x - nodeB._x)\n\t\tlocal dy = abs(nodeA._y - nodeB._y)\n\t\treturn (dx + dy) \n\tend\n \n --- Euclidian distance.\n -- distance = squareRoot(dx*dx+dy*dy)\n -- @class function\n -- @tparam node nodeA a node\n -- @tparam node nodeB another node\n -- @treturn number the distance from __nodeA__ to __nodeB__\n\t-- @usage\n -- -- First method\n -- pathfinder:setHeuristic('EUCLIDIAN')\n -- -- Second method\n -- local Distance = require ('jumper.core.heuristics')\n -- pathfinder:setHeuristic(Distance.EUCLIDIAN) \n function Heuristics.EUCLIDIAN(nodeA, nodeB)\n\t\tlocal dx = nodeA._x - nodeB._x\n\t\tlocal dy = nodeA._y - nodeB._y\n\t\treturn sqrt(dx*dx+dy*dy) \n\tend\n \n --- Diagonal distance.\n -- distance = max(|dx|, abs|dy|)\n -- @class function\n -- @tparam node nodeA a node\n -- @tparam node nodeB another node\n -- @treturn number the distance from __nodeA__ to __nodeB__\n\t-- @usage\n -- -- First method\n -- pathfinder:setHeuristic('DIAGONAL')\n -- -- Second method\n -- local Distance = require ('jumper.core.heuristics')\n -- pathfinder:setHeuristic(Distance.DIAGONAL)\n function Heuristics.DIAGONAL(nodeA, nodeB)\n\t\tlocal dx = abs(nodeA._x - nodeB._x)\n\t\tlocal dy = abs(nodeA._y - nodeB._y)\t\n\t\treturn max(dx,dy) \n\tend\n \n --- Cardinal/Intercardinal distance.\n -- distance = min(dx, dy)*squareRoot(2) + max(dx, dy) - min(dx, dy)\n -- @class function\n -- @tparam node nodeA a node\n -- @tparam node nodeB another node\n -- @treturn number the distance from __nodeA__ to __nodeB__\n\t-- @usage\n -- -- First method\n -- pathfinder:setHeuristic('CARDINTCARD')\n -- -- Second method\n -- local Distance = require ('jumper.core.heuristics')\n -- pathfinder:setHeuristic(Distance.CARDINTCARD)\n function Heuristics.CARDINTCARD(nodeA, nodeB)\n\t\tlocal dx = abs(nodeA._x - nodeB._x)\n\t\tlocal dy = abs(nodeA._y - nodeB._y)\t\n return min(dx,dy) * sqrt2 + max(dx,dy) - min(dx,dy)\n end\n\nreturn Heuristics"
},
{
"path": "jumper/core/lookuptable.lua",
"content": "local addNode(self, node, nextNode, ed)\n\tif not self._pathDB[node] then self._pathDB[node] = {} end\n\tself._pathDB[node][ed] = (nextNode == ed and node or nextNode)\nend\n\n-- Path lookupTable\nlocal lookupTable = {}\nlookupTable.__index = lookupTable\n\nfunction lookupTable:new()\n\tlocal lut = {_pathDB = {}}\n\treturn setmetatable(lut, lookupTable)\nend\n\nfunction lookupTable:addPath(path)\n\tlocal st, ed = path._nodes[1], path._nodes[#path._nodes]\n\tfor node, count in path:nodes() do\n\t\tlocal nextNode = path._nodes[count+1]\n\t\tif nextNode then addNode(self, node, nextNode, ed) end\n\tend\nend\n\nfunction lookupTable:hasPath(nodeA, nodeB)\n\tlocal found\n\tfound = self._pathDB[nodeA] and self._path[nodeA][nodeB]\n\tif found then return true, true end\n\tfound = self._pathDB[nodeB] and self._path[nodeB][nodeA]\n\tif found then return true, false end\n\treturn false\nend\n\nreturn lookupTable"
},
{
"path": "jumper/core/node.lua",
"content": "--- The Node class.\n-- The `node` represents a cell (or a tile) on a collision map. Basically, for each single cell (tile)\n-- in the collision map passed-in upon initialization, a `node` object will be generated\n-- and then cached within the `grid`.\n--\n-- In the following implementation, nodes can be compared using the `<` operator. The comparison is\n-- made with regards of their `f` cost. From a given node being examined, the `pathfinder` will expand the search \n-- to the next neighbouring node having the lowest `f` cost. See `core.bheap` for more details.\n-- \n\nif (...) then\n\n\tlocal assert = assert\n\t\n\t--- The `Node` class.Node(...) _acts as a shortcut to_ Node:new(...).\n\t-- @type Node\n local Node = {}\n Node.__index = Node\n\n --- Inits a new `node`\n -- @class function\n -- @tparam int x the x-coordinate of the node on the collision map\n -- @tparam int y the y-coordinate of the node on the collision map\n -- @treturn node a new `node`\n\t-- @usage local node = Node(3,4)\n function Node:new(x,y)\n return setmetatable({_x = x, _y = y, _clearance = {}}, Node)\n end\n\n -- Enables the use of operator '<' to compare nodes.\n -- Will be used to sort a collection of nodes in a binary heap on the basis of their F-cost\n function Node.__lt(A,B) return (A._f < B._f) end\n\n --- Returns x-coordinate of a `node`\n -- @class function\n -- @treturn number the x-coordinate of the `node`\n\t-- @usage local x = node:getX()\t\n\tfunction Node:getX() return self._x end\n\t\n --- Returns y-coordinate of a `node`\n -- @class function\n -- @treturn number the y-coordinate of the `node`\t\n\t-- @usage local y = node:getY()\t\t\n\tfunction Node:getY() return self._y end\n\t\n --- Returns x and y coordinates of a `node`\n -- @class function\n -- @treturn number the x-coordinate of the `node`\n -- @treturn number the y-coordinate of the `node`\n\t-- @usage local x, y = node:getPos()\t\t\n\tfunction Node:getPos() return self._x, self._y end\n\t\n --- Returns the amount of true [clearance](http://aigamedev.com/open/tutorial/clearance-based-pathfinding/#TheTrueClearanceMetric) \n\t-- for a given `node`\n -- @class function\n -- @tparam string|int|func walkable the value for walkable locations in the collision map array.\n -- @treturn int the clearance of the `node`\n\t-- @usage\n\t-- -- Assuming walkable was 0\t\n\t-- local clearance = node:getClearance(0)\t\t\n\tfunction Node:getClearance(walkable)\n\t\treturn self._clearance[walkable]\n\tend\n\t\n --- Removes the clearance value for a given walkable.\n -- @class function\n -- @tparam string|int|func walkable the value for walkable locations in the collision map array.\n\t-- @treturn node self (the calling `node` itself, can be chained)\n\t-- @usage\n\t-- -- Assuming walkable is defined\t\n\t-- node:removeClearance(walkable)\t\n\tfunction Node:removeClearance(walkable)\n\t\tself._clearance[walkable] = nil\n\t\treturn self\n\tend\n\t\n\t--- Clears temporary cached attributes of a `node`.\n\t-- Deletes the attributes cached within a given node after a pathfinding call.\n\t-- This function is internally used by the search algorithms, so you should not use it explicitely.\n\t-- @class function\n\t-- @treturn node self (the calling `node` itself, can be chained)\n\t-- @usage\n\t-- local thisNode = Node(1,2)\n\t-- thisNode:reset()\n\tfunction Node:reset()\n\t\tself._g, self._h, self._f = nil, nil, nil\n\t\tself._opened, self._closed, self._parent = nil, nil, nil\n\t\treturn self\n\tend\n\t\n return setmetatable(Node,\n\t\t{__call = function(self,...) \n\t\t\treturn Node:new(...) \n\t\tend}\n\t)\nend"
},
{
"path": "jumper/core/path.lua",
"content": "--- The Path class.\n-- The `path` class is a structure which represents a path (ordered set of nodes) from a start location to a goal.\n-- An instance from this class would be a result of a request addressed to `Pathfinder:getPath`.\n--\n-- This module is internally used by the library on purpose.\n-- It should normally not be used explicitely, yet it remains fully accessible.\n--\n\n\nif (...) then\n\t\n -- Dependencies\n\tlocal _PATH = (...):match('(.+)%.path$')\n local Heuristic = require (_PATH .. '.heuristics')\n\t\n\t -- Local references\n local abs, max = math.abs, math.max\n\tlocal t_insert, t_remove = table.insert, table.remove\n\t\n\t--- The `Path` class.Path(...) acts as a shortcut to Path:new(...).\n\t-- @type Path\n local Path = {}\n Path.__index = Path\n\n --- Inits a new `path`.\n -- @class function\n -- @treturn path a `path`\n\t-- @usage local p = Path()\n function Path:new()\n return setmetatable({_nodes = {}}, Path)\n end\n\n --- Iterates on each single `node` along a `path`. At each step of iteration,\n -- returns the `node` plus a count value. Aliased as @{Path:nodes}\n -- @class function\n -- @treturn node a `node`\n -- @treturn int the count for the number of nodes\n\t-- @see Path:nodes\n\t-- @usage\n\t-- for node, count in p:iter() do\n\t-- ...\n\t-- end\n function Path:iter()\n local i,pathLen = 1,#self._nodes\n return function()\n if self._nodes[i] then\n i = i+1\n return self._nodes[i-1],i-1\n end\n end\n end\n \n --- Iterates on each single `node` along a `path`. At each step of iteration,\n -- returns a `node` plus a count value. Alias for @{Path:iter}\n -- @class function\n\t-- @name Path:nodes\n -- @treturn node a `node`\n -- @treturn int the count for the number of nodes\n\t-- @see Path:iter\t\n\t-- @usage\n\t-- for node, count in p:nodes() do\n\t-- ...\n\t-- end\t\n\tPath.nodes = Path.iter\n\t\n --- Evaluates the `path` length\n -- @class function\n -- @treturn number the `path` length\n\t-- @usage local len = p:getLength()\n function Path:getLength()\n local len = 0\n for i = 2,#self._nodes do\n len = len + Heuristic.EUCLIDIAN(self._nodes[i], self._nodes[i-1])\n end\n return len\n end\n\t\n\t--- Counts the number of steps.\n\t-- Returns the number of waypoints (nodes) in the current path.\n\t-- @class function\n\t-- @tparam node node a node to be added to the path\n\t-- @tparam[opt] int index the index at which the node will be inserted. If omitted, the node will be appended after the last node in the path.\n\t-- @treturn path self (the calling `path` itself, can be chained)\n\t-- @usage local nSteps = p:countSteps()\n\tfunction Path:addNode(node, index)\n\t\tindex = index or #self._nodes+1\n\t\tt_insert(self._nodes, index, node)\n\t\treturn self\n\tend\n\t\n\t\n --- `Path` filling modifier. Interpolates between non contiguous nodes along a `path`\n -- to build a fully continuous `path`. This maybe useful when using search algorithms such as Jump Point Search.\n -- Does the opposite of @{Path:filter}\n -- @class function\n\t-- @treturn path self (the calling `path` itself, can be chained)\t\n -- @see Path:filter\n\t-- @usage p:fill()\n function Path:fill()\n local i = 2\n local xi,yi,dx,dy\n local N = #self._nodes\n local incrX, incrY\n while true do\n xi,yi = self._nodes[i]._x,self._nodes[i]._y\n dx,dy = xi-self._nodes[i-1]._x,yi-self._nodes[i-1]._y\n if (abs(dx) > 1 or abs(dy) > 1) then\n incrX = dx/max(abs(dx),1)\n incrY = dy/max(abs(dy),1)\n t_insert(self._nodes, i, self._grid:getNodeAt(self._nodes[i-1]._x + incrX, self._nodes[i-1]._y +incrY))\n N = N+1\n else i=i+1\n end\n if i>N then break end\n end\n\t\treturn self\n end\n\n --- `Path` compression modifier. Given a `path`, eliminates useless nodes to return a lighter `path` \n\t-- consisting of straight moves. Does the opposite of @{Path:fill}\n -- @class function\n\t-- @treturn path self (the calling `path` itself, can be chained)\t\n -- @see Path:fill\n\t-- @usage p:filter()\n function Path:filter()\n local i = 2\n local xi,yi,dx,dy, olddx, olddy\n xi,yi = self._nodes[i]._x, self._nodes[i]._y\n dx, dy = xi - self._nodes[i-1]._x, yi-self._nodes[i-1]._y\n while true do\n olddx, olddy = dx, dy\n if self._nodes[i+1] then\n i = i+1\n xi, yi = self._nodes[i]._x, self._nodes[i]._y\n dx, dy = xi - self._nodes[i-1]._x, yi - self._nodes[i-1]._y\n if olddx == dx and olddy == dy then\n t_remove(self._nodes, i-1)\n i = i - 1\n end\n else break end\n end\n\t\treturn self\n end\n\t\n --- Clones a `path`.\n -- @class function\n -- @treturn path a `path`\n\t-- @usage local p = path:clone()\t\n\tfunction Path:clone()\n\t\tlocal p = Path:new()\n\t\tfor node in self:nodes() do p:addNode(node) end\n\t\treturn p\n\tend\n\t\n --- Checks if a `path` is equal to another. It also supports *filtered paths* (see @{Path:filter}).\n -- @class function\n\t-- @tparam path p2 a path\n -- @treturn boolean a boolean\n\t-- @usage print(myPath:isEqualTo(anotherPath))\n\tfunction Path:isEqualTo(p2)\n\t\tlocal p1 = self:clone():filter()\n\t\tlocal p2 = p2:clone():filter()\n\t\tfor node, count in p1:nodes() do\n\t\t\tif not p2._nodes[count] then return false end\n\t\t\tlocal n = p2._nodes[count]\n\t\t\tif n._x~=node._x or n._y~=node._y then return false end\n\t\tend\t\n\t\treturn true\n\tend\n\t\n --- Reverses a `path`.\n -- @class function\n\t-- @treturn path self (the calling `path` itself, can be chained)\n\t-- @usage myPath:reverse()\t\n\tfunction Path:reverse()\n\t\tlocal _nodes = {}\n\t\tfor i = #self._nodes,1,-1 do\n\t\t\t_nodes[#_nodes+1] = self._nodes[i]\t\t\n\t\tend\n\t\tself._nodes = _nodes\n\t\treturn self\n\tend\t\n\n --- Appends a given `path` to self.\n -- @class function\n\t-- @tparam path p a path\n\t-- @treturn path self (the calling `path` itself, can be chained)\n\t-- @usage myPath:append(anotherPath)\t\t\n\tfunction Path:append(p)\n\t\tfor node in p:nodes() do self:addNode(node)\tend\n\t\treturn self\n\tend\n\t\n return setmetatable(Path,\n {__call = function(self,...)\n return Path:new(...)\n end\n })\nend"
},
{
"path": "jumper/core/utils.lua",
"content": "-- Various utilities for Jumper top-level modules\n\nif (...) then\n\n\t-- Dependencies\n\tlocal _PATH = (...):gsub('%.utils$','')\n\tlocal Path = require (_PATH .. '.path')\n\tlocal Node = require (_PATH .. '.node')\n\n\t-- Local references\n\tlocal pairs = pairs\n\tlocal type = type\n\tlocal t_insert = table.insert\n\tlocal assert = assert\n\tlocal coroutine = coroutine\n\n\t-- Raw array items count\n\tlocal function arraySize(t)\n\t\tlocal count = 0\n\t\tfor k,v in pairs(t) do\n\t\t\tcount = count+1\n\t\tend\n\t\treturn count\n\tend\n\n\t-- Parses a string map and builds an array map\n local function stringMapToArray(str)\n\t\tlocal map = {}\n\t\tlocal w, h\n for line in str:gmatch('[^\\n\\r]+') do\n if line then\n w = not w and #line or w\n assert(#line == w, 'Error parsing map, rows must have the same size!')\n h = (h or 0) + 1\n map[h] = {}\n for char in line:gmatch('.') do\n\t\t\t\t\tmap[h][#map[h]+1] = char\n\t\t\t\tend\n end\n end\n return map\n end\n\n\t-- Collects and returns the keys of a given array\n local function getKeys(t)\n local keys = {}\n for k,v in pairs(t) do keys[#keys+1] = k end\n return keys\n end\n\n\t-- Calculates the bounds of a 2d array\n local function getArrayBounds(map)\n local min_x, max_x\n local min_y, max_y\n for y in pairs(map) do\n min_y = not min_y and y or (yGrid(...) _acts as a shortcut to_ Grid:new(...).\n\t-- @type Grid\n local Grid = {}\n Grid.__index = Grid\n\n -- Specialized grids\n local PreProcessGrid = setmetatable({},Grid)\n local PostProcessGrid = setmetatable({},Grid)\n PreProcessGrid.__index = PreProcessGrid\n PostProcessGrid.__index = PostProcessGrid\n PreProcessGrid.__call = function (self,x,y)\n return self:getNodeAt(x,y)\n end\n PostProcessGrid.__call = function (self,x,y,create)\n if create then return self:getNodeAt(x,y) end\n return self._nodes[y] and self._nodes[y][x]\n end\n\n --- Inits a new `grid`\n -- @class function\n -- @tparam table|string map A collision map - (2D array) with consecutive indices (starting at 0 or 1)\n\t-- or a `string` with line-break chars (\\n or \\r) as row delimiters.\n -- @tparam[opt] bool cacheNodeAtRuntime When __true__, returns an empty `grid` instance, so that\n\t-- later on, indexing a non-cached `node` will cause it to be created and cache within the `grid` on purpose (i.e, when needed).\n\t-- This is a __memory-safe__ option, in case your dealing with some tight memory constraints.\n\t-- Defaults to __false__ when omitted.\n -- @treturn grid a new `grid` instance\n\t-- @usage\n\t-- -- A simple 3x3 grid\n\t-- local myGrid = Grid:new({{0,0,0},{0,0,0},{0,0,0}})\n\t--\n\t-- -- A memory-safe 3x3 grid\n\t-- myGrid = Grid('000\\n000\\n000', true)\n function Grid:new(map, cacheNodeAtRuntime)\n\t\tif type(map) == 'string' then\n\t\t\tassert(Assert.isStrMap(map), 'Wrong argument #1. Not a valid string map')\n\t\t\tmap = Utils.strToMap(map)\n\t\tend\n assert(Assert.isMap(map),('Bad argument #1. Not a valid map'))\n assert(Assert.isBool(cacheNodeAtRuntime) or Assert.isNil(cacheNodeAtRuntime),\n ('Bad argument #2. Expected \\'boolean\\', got %s.'):format(type(cacheNodeAtRuntime)))\n if cacheNodeAtRuntime then\n return PostProcessGrid:new(map,walkable)\n end\n return PreProcessGrid:new(map,walkable)\n end\n\n --- Checks if `node` at [x,y] is __walkable__.\n\t-- Will check if `node` at location [x,y] both *exists* on the collision map and *is walkable*\n -- @class function\n -- @tparam int x the x-location of the node\n -- @tparam int y the y-location of the node\n -- @tparam[opt] string|int|func walkable the value for walkable locations in the collision map array (see @{Grid:new}).\n\t-- Defaults to __false__ when omitted.\n -- If this parameter is a function, it should be prototyped as __f(value)__ and return a `boolean`:\n -- __true__ when value matches a __walkable__ `node`, __false__ otherwise. If this parameter is not given\n -- while location [x,y] __is valid__, this actual function returns __true__.\n -- @tparam[optchain] int clearance the amount of clearance needed. Defaults to 1 (normal clearance) when not given.\n -- @treturn bool __true__ if `node` exists and is __walkable__, __false__ otherwise\n\t-- @usage\n\t-- -- Always true\n\t-- print(myGrid:isWalkableAt(2,3))\n\t--\n\t-- -- True if node at [2,3] collision map value is 0\n\t-- print(myGrid:isWalkableAt(2,3,0))\n\t--\n\t-- -- True if node at [2,3] collision map value is 0 and has a clearance higher or equal to 2\n\t-- print(myGrid:isWalkableAt(2,3,0,2))\n\t--\n function Grid:isWalkableAt(x, y, walkable, clearance)\n local nodeValue = self._map[y] and self._map[y][x]\n if nodeValue then\n if not walkable then return true end\n else\n\t\t\treturn false\n end\n\t\tlocal hasEnoughClearance = not clearance and true or false\n\t\tif not hasEnoughClearance then\n\t\t\tif not self._isAnnotated[walkable] then return false end\n\t\t\tlocal node = self:getNodeAt(x,y)\n\t\t\tlocal nodeClearance = node:getClearance(walkable)\n\t\t\thasEnoughClearance = (nodeClearance >= clearance)\n\t\tend\n if self._eval then\n\t\t\treturn walkable(nodeValue) and hasEnoughClearance\n\t\tend\n return ((nodeValue == walkable) and hasEnoughClearance)\n end\n\n --- Returns the `grid` width.\n -- @class function\n -- @treturn int the `grid` width\n\t-- @usage print(myGrid:getWidth())\n function Grid:getWidth()\n return self._width\n end\n\n --- Returns the `grid` height.\n -- @class function\n -- @treturn int the `grid` height\n\t-- @usage print(myGrid:getHeight())\n function Grid:getHeight()\n return self._height\n end\n\n --- Returns the collision map.\n -- @class function\n -- @treturn map the collision map (see @{Grid:new})\n\t-- @usage local map = myGrid:getMap()\n function Grid:getMap()\n return self._map\n end\n\n --- Returns the set of nodes.\n -- @class function\n -- @treturn {{node,...},...} an array of nodes\n\t-- @usage local nodes = myGrid:getNodes()\n function Grid:getNodes()\n return self._nodes\n end\n\n --- Returns the `grid` bounds. Returned values corresponds to the upper-left\n\t-- and lower-right coordinates (in tile units) of the actual `grid` instance.\n -- @class function\n -- @treturn int the upper-left corner x-coordinate\n -- @treturn int the upper-left corner y-coordinate\n -- @treturn int the lower-right corner x-coordinate\n -- @treturn int the lower-right corner y-coordinate\n\t-- @usage local left_x, left_y, right_x, right_y = myGrid:getBounds()\n\tfunction Grid:getBounds()\n\t\treturn self._min_x, self._min_y,self._max_x, self._max_y\n\tend\n\n --- Returns neighbours. The returned value is an array of __walkable__ nodes neighbouring a given `node`.\n -- @class function\n -- @tparam node node a given `node`\n -- @tparam[opt] string|int|func walkable the value for walkable locations in the collision map array (see @{Grid:new}).\n\t-- Defaults to __false__ when omitted.\n -- @tparam[optchain] bool allowDiagonal when __true__, allows adjacent nodes are included (8-neighbours).\n\t-- Defaults to __false__ when omitted.\n -- @tparam[optchain] bool tunnel When __true__, allows the `pathfinder` to tunnel through walls when heading diagonally.\n -- @tparam[optchain] int clearance When given, will prune for the neighbours set all nodes having a clearance value lower than the passed-in value\n\t-- Defaults to __false__ when omitted.\n -- @treturn {node,...} an array of nodes neighbouring a given node\n\t-- @usage\n\t-- local aNode = myGrid:getNodeAt(5,6)\n\t-- local neighbours = myGrid:getNeighbours(aNode, 0, true)\n function Grid:getNeighbours(node, walkable, allowDiagonal, tunnel, clearance)\n\t\tlocal neighbours = {}\n for i = 1,#straightOffsets do\n local n = self:getNodeAt(\n node._x + straightOffsets[i].x,\n node._y + straightOffsets[i].y\n )\n if n and self:isWalkableAt(n._x, n._y, walkable, clearance) then\n neighbours[#neighbours+1] = n\n end\n end\n\n if not allowDiagonal then return neighbours end\n\n\t\ttunnel = not not tunnel\n for i = 1,#diagonalOffsets do\n local n = self:getNodeAt(\n node._x + diagonalOffsets[i].x,\n node._y + diagonalOffsets[i].y\n )\n if n and self:isWalkableAt(n._x, n._y, walkable, clearance) then\n\t\t\t\tif tunnel then\n\t\t\t\t\tneighbours[#neighbours+1] = n\n\t\t\t\telse\n\t\t\t\t\tlocal skipThisNode = false\n\t\t\t\t\tlocal n1 = self:getNodeAt(node._x+diagonalOffsets[i].x, node._y)\n\t\t\t\t\tlocal n2 = self:getNodeAt(node._x, node._y+diagonalOffsets[i].y)\n\t\t\t\t\tif ((n1 and n2) and not self:isWalkableAt(n1._x, n1._y, walkable, clearance) and not self:isWalkableAt(n2._x, n2._y, walkable, clearance)) then\n\t\t\t\t\t\tskipThisNode = true\n\t\t\t\t\tend\n\t\t\t\t\tif not skipThisNode then neighbours[#neighbours+1] = n end\n\t\t\t\tend\n end\n end\n\n return neighbours\n end\n\n --- Grid iterator. Iterates on every single node\n -- in the `grid`. Passing __lx, ly, ex, ey__ arguments will iterate\n -- only on nodes inside the bounding-rectangle delimited by those given coordinates.\n -- @class function\n -- @tparam[opt] int lx the leftmost x-coordinate of the rectangle. Default to the `grid` leftmost x-coordinate (see @{Grid:getBounds}).\n -- @tparam[optchain] int ly the topmost y-coordinate of the rectangle. Default to the `grid` topmost y-coordinate (see @{Grid:getBounds}).\n -- @tparam[optchain] int ex the rightmost x-coordinate of the rectangle. Default to the `grid` rightmost x-coordinate (see @{Grid:getBounds}).\n -- @tparam[optchain] int ey the bottom-most y-coordinate of the rectangle. Default to the `grid` bottom-most y-coordinate (see @{Grid:getBounds}).\n -- @treturn node a `node` on the collision map, upon each iteration step\n -- @treturn int the iteration count\n\t-- @usage\n\t-- for node, count in myGrid:iter() do\n\t-- print(node:getX(), node:getY(), count)\n\t-- end\n function Grid:iter(lx,ly,ex,ey)\n local min_x = lx or self._min_x\n local min_y = ly or self._min_y\n local max_x = ex or self._max_x\n local max_y = ey or self._max_y\n\n local x, y\n y = min_y\n return function()\n x = not x and min_x or x+1\n if x > max_x then\n x = min_x\n y = y+1\n end\n if y > max_y then\n y = nil\n end\n return self._nodes[y] and self._nodes[y][x] or self:getNodeAt(x,y)\n end\n end\n\n\t--- Grid iterator. Iterates on each node along the outline (border) of a squared area\n\t-- centered on the given node.\n\t-- @tparam node node a given `node`\n\t-- @tparam[opt] int radius the area radius (half-length). Defaults to __1__ when not given.\n\t-- @treturn node a `node` at each iteration step\n\t-- @usage\n\t-- for node in myGrid:around(node, 2) do\n\t-- ...\n\t-- end\n\tfunction Grid:around(node, radius)\n\t\tlocal x, y = node._x, node._y\n\t\tradius = radius or 1\n\t\tlocal _around = Utils.around()\n\t\tlocal _nodes = {}\n\t\trepeat\n\t\t\tlocal state, x, y = coroutine.resume(_around,x,y,radius)\n\t\t\tlocal nodeAt = state and self:getNodeAt(x, y)\n\t\t\tif nodeAt then _nodes[#_nodes+1] = nodeAt end\n\t\tuntil (not state)\n\t\tlocal _i = 0\n\t\treturn function()\n\t\t\t_i = _i+1\n\t\t\treturn _nodes[_i]\n\t\tend\n\tend\n\n --- Each transformation. Calls the given function on each `node` in the `grid`,\n\t-- passing the `node` as the first argument to function __f__.\n -- @class function\n -- @tparam func f a function prototyped as __f(node,...)__\n -- @tparam[opt] vararg ... args to be passed to function __f__\n\t-- @treturn grid self (the calling `grid` itself, can be chained)\n\t-- @usage\n\t-- local function printNode(node)\n\t-- print(node:getX(), node:getY())\n\t-- end\n\t-- myGrid:each(printNode)\n function Grid:each(f,...)\n for node in self:iter() do f(node,...) end\n\t\treturn self\n end\n\n --- Each (in range) transformation. Calls a function on each `node` in the range of a rectangle of cells,\n\t-- passing the `node` as the first argument to function __f__.\n -- @class function\n -- @tparam int lx the leftmost x-coordinate coordinate of the rectangle\n -- @tparam int ly the topmost y-coordinate of the rectangle\n -- @tparam int ex the rightmost x-coordinate of the rectangle\n -- @tparam int ey the bottom-most y-coordinate of the rectangle\n -- @tparam func f a function prototyped as __f(node,...)__\n -- @tparam[opt] vararg ... args to be passed to function __f__\n\t-- @treturn grid self (the calling `grid` itself, can be chained)\n\t-- @usage\n\t-- local function printNode(node)\n\t-- print(node:getX(), node:getY())\n\t-- end\n\t-- myGrid:eachRange(1,1,8,8,printNode)\n function Grid:eachRange(lx,ly,ex,ey,f,...)\n for node in self:iter(lx,ly,ex,ey) do f(node,...) end\n\t\treturn self\n end\n\n --- Map transformation.\n\t-- Calls function __f(node,...)__ on each `node` in a given range, passing the `node` as the first arg to function __f__ and replaces\n\t-- it with the returned value. Therefore, the function should return a `node`.\n -- @class function\n -- @tparam func f a function prototyped as __f(node,...)__\n -- @tparam[opt] vararg ... args to be passed to function __f__\n\t-- @treturn grid self (the calling `grid` itself, can be chained)\n\t-- @usage\n\t-- local function nothing(node)\n\t-- return node\n\t-- end\n\t-- myGrid:imap(nothing)\n function Grid:imap(f,...)\n for node in self:iter() do\n node = f(node,...)\n end\n\t\treturn self\n end\n\n --- Map in range transformation.\n\t-- Calls function __f(node,...)__ on each `node` in a rectangle range, passing the `node` as the first argument to the function and replaces\n\t-- it with the returned value. Therefore, the function should return a `node`.\n\t-- @class function\n -- @tparam int lx the leftmost x-coordinate coordinate of the rectangle\n -- @tparam int ly the topmost y-coordinate of the rectangle\n -- @tparam int ex the rightmost x-coordinate of the rectangle\n -- @tparam int ey the bottom-most y-coordinate of the rectangle\n -- @tparam func f a function prototyped as __f(node,...)__\n -- @tparam[opt] vararg ... args to be passed to function __f__\n\t-- @treturn grid self (the calling `grid` itself, can be chained)\n\t-- @usage\n\t-- local function nothing(node)\n\t-- return node\n\t-- end\n\t-- myGrid:imap(1,1,6,6,nothing)\n function Grid:imapRange(lx,ly,ex,ey,f,...)\n for node in self:iter(lx,ly,ex,ey) do\n node = f(node,...)\n end\n\t\treturn self\n end\n\n -- Specialized grids\n -- Inits a preprocessed grid\n function PreProcessGrid:new(map)\n local newGrid = {}\n newGrid._map = map\n newGrid._nodes, newGrid._min_x, newGrid._max_x, newGrid._min_y, newGrid._max_y = Utils.arrayToNodes(newGrid._map)\n newGrid._width = (newGrid._max_x-newGrid._min_x)+1\n newGrid._height = (newGrid._max_y-newGrid._min_y)+1\n\t\tnewGrid._isAnnotated = {}\n return setmetatable(newGrid,PreProcessGrid)\n end\n\n -- Inits a postprocessed grid\n function PostProcessGrid:new(map)\n local newGrid = {}\n newGrid._map = map\n newGrid._nodes = {}\n newGrid._min_x, newGrid._max_x, newGrid._min_y, newGrid._max_y = Utils.getArrayBounds(newGrid._map)\n newGrid._width = (newGrid._max_x-newGrid._min_x)+1\n newGrid._height = (newGrid._max_y-newGrid._min_y)+1\n\t\tnewGrid._isAnnotated = {}\t\t\n return setmetatable(newGrid,PostProcessGrid)\n end\n\n --- Returns the `node` at location [x,y].\n -- @class function\n -- @name Grid:getNodeAt\n -- @tparam int x the x-coordinate coordinate\n -- @tparam int y the y-coordinate coordinate\n -- @treturn node a `node`\n\t-- @usage local aNode = myGrid:getNodeAt(2,2)\n\n -- Gets the node at location Pathfinder(...) _acts as a shortcut to_ Pathfinder:new(...).\n\t-- @type Pathfinder\n local Pathfinder = {}\n Pathfinder.__index = Pathfinder\n\n --- Inits a new `pathfinder`\n -- @class function\n -- @tparam grid grid a `grid`\n -- @tparam[opt] string finderName the name of the `Finder` (search algorithm) to be used for search.\n\t-- Defaults to `ASTAR` when not given (see @{Pathfinder:getFinders}).\n -- @tparam[optchain] string|int|func walkable the value for __walkable__ nodes.\n -- If this parameter is a function, it should be prototyped as __f(value)__, returning a boolean:\n -- __true__ when value matches a __walkable__ `node`, __false__ otherwise.\n -- @treturn pathfinder a new `pathfinder` instance\n\t-- @usage\n\t-- -- Example one\n\t-- local finder = Pathfinder:new(myGrid, 'ASTAR', 0)\n\t--\n\t-- -- Example two\n\t-- local function walkable(value)\n\t-- return value > 0\n\t-- end\n\t-- local finder = Pathfinder(myGrid, 'JPS', walkable)\n function Pathfinder:new(grid, finderName, walkable)\n local newPathfinder = {}\n setmetatable(newPathfinder, Pathfinder)\n\t newPathfinder:setGrid(grid)\n newPathfinder:setFinder(finderName)\n newPathfinder:setWalkable(walkable)\n newPathfinder:setMode('DIAGONAL')\n newPathfinder:setHeuristic('MANHATTAN')\n newPathfinder:setTunnelling(false)\n return newPathfinder\n end\n\n\t--- Evaluates [clearance](http://aigamedev.com/open/tutorial/clearance-based-pathfinding/#TheTrueClearanceMetric)\n\t-- for the whole `grid`. It should be called only once, unless the collision map or the\n\t-- __walkable__ attribute changes. The clearance values are calculated and cached within the grid nodes.\n -- @class function\n\t-- @treturn pathfinder self (the calling `pathfinder` itself, can be chained)\n\t-- @usage myFinder:annotateGrid()\n\tfunction Pathfinder:annotateGrid()\n\t\tassert(self._walkable, 'Finder must implement a walkable value')\n\t\tfor x=self._grid._max_x,self._grid._min_x,-1 do\n\t\t\tfor y=self._grid._max_y,self._grid._min_y,-1 do\n\t\t\t\tlocal node = self._grid:getNodeAt(x,y)\n\t\t\t\tif self._grid:isWalkableAt(x,y,self._walkable) then\n\t\t\t\t\tlocal nr = self._grid:getNodeAt(node._x+1, node._y)\n\t\t\t\t\tlocal nrd = self._grid:getNodeAt(node._x+1, node._y+1)\n\t\t\t\t\tlocal nd = self._grid:getNodeAt(node._x, node._y+1)\n\t\t\t\t\tif nr and nrd and nd then\n\t\t\t\t\t\tlocal m = nrd._clearance[self._walkable] or 0\n\t\t\t\t\t\tm = (nd._clearance[self._walkable] or 0)