move apis into rom/modules/main for shell compatibility

sys/modules/opus/jumper/core/bheap.lua

@@ -0,0 +1,175 @@
+--- A light implementation of Binary heaps data structure.
+-- While running a search, some search algorithms (Astar, Dijkstra, Jump Point Search) have to maintains
+-- a list of nodes called __open list__. Retrieve from this list the lowest cost node can be quite slow,
+-- as it normally requires to skim through the full set of nodes stored in this list. This becomes a real
+-- problem especially when dozens of nodes are being processed (on large maps).
+--
+-- The current module implements a <a href="http://www.policyalmanac.org/games/binaryHeaps.htm">binary heap</a>
+-- data structure, from which the search algorithm will instantiate an open list, and cache the nodes being
+-- examined during a search. As such, retrieving the lower-cost node is faster and globally makes the search end
+-- up quickly.
+--
+-- This module is internally used by the library on purpose.
+-- It should normally not be used explicitely, yet it remains fully accessible.
+--
+
+--[[
+	Notes:
+	This lighter implementation of binary heaps, based on :
+		https://github.com/Yonaba/Binary-Heaps
+--]]
+
+if (...) then
+
+	-- Dependency
+	local Utils = require((...):gsub('%.bheap$','.utils'))
+
+	-- Local reference
+	local floor = math.floor
+
+	-- Default comparison function
+	local function f_min(a,b) return a < b end
+
+	-- Percolates up
+	local function percolate_up(heap, index)
+		if index == 1 then return end
+		local pIndex
+		if index <= 1 then return end
+		if index%2 == 0 then
+			pIndex =  index/2
+		else pIndex = (index-1)/2
+		end
+		if not heap._sort(heap._heap[pIndex], heap._heap[index]) then
+			heap._heap[pIndex], heap._heap[index] =
+				heap._heap[index], heap._heap[pIndex]
+			percolate_up(heap, pIndex)
+		end
+	end
+
+	-- Percolates down
+	local function percolate_down(heap,index)
+		local lfIndex,rtIndex,minIndex
+		lfIndex = 2*index
+		rtIndex = lfIndex + 1
+		if rtIndex > heap._size then
+			if lfIndex > heap._size then return
+			else minIndex = lfIndex  end
+		else
+			if heap._sort(heap._heap[lfIndex],heap._heap[rtIndex]) then
+				minIndex = lfIndex
+			else
+				minIndex = rtIndex
+			end
+		end
+		if not heap._sort(heap._heap[index],heap._heap[minIndex]) then
+			heap._heap[index],heap._heap[minIndex] = heap._heap[minIndex],heap._heap[index]
+			percolate_down(heap,minIndex)
+		end
+	end
+
+	-- Produces a new heap
+	local function newHeap(template,comp)
+		return setmetatable({_heap = {},
+			_sort = comp or f_min, _size = 0},
+		template)
+	end
+
+
+	--- The `heap` class.<br/>
+	-- This class is callable.
+	-- _Therefore,_ <code>heap(...)</code> _is used to instantiate new heaps_.
+	-- @type heap
+	local heap = setmetatable({},
+		{__call = function(self,...)
+			return newHeap(self,...)
+		end})
+	heap.__index = heap
+
+	--- Checks if a `heap` is empty
+	-- @class function
+	-- @treturn bool __true__ of no item is queued in the heap, __false__ otherwise
+	-- @usage
+	-- if myHeap:empty() then
+	--   print('Heap is empty!')
+	-- end
+	function heap:empty()
+		return (self._size==0)
+	end
+
+	--- Clears the `heap` (removes all items queued in the heap)
+	-- @class function
+	-- @treturn heap self (the calling `heap` itself, can be chained)
+	-- @usage myHeap:clear()
+	function heap:clear()
+		self._heap = {}
+		self._size = 0
+		self._sort = self._sort or f_min
+		return self
+	end
+
+	--- Adds a new item in the `heap`
+	-- @class function
+	-- @tparam value item a new value to be queued in the heap
+	-- @treturn heap self (the calling `heap` itself, can be chained)
+	-- @usage
+	-- myHeap:push(1)
+	-- -- or, with chaining
+	-- myHeap:push(1):push(2):push(4)
+	function heap:push(item)
+		if item then
+			self._size = self._size + 1
+			self._heap[self._size] = item
+			percolate_up(self, self._size)
+		end
+		return self
+	end
+
+	--- Pops from the `heap`.
+	-- Removes and returns the lowest cost item (with respect to the comparison function being used) from the `heap`.
+	-- @class function
+	-- @treturn value a value previously pushed into the heap
+	-- @usage
+	-- while not myHeap:empty() do
+	--   local lowestValue = myHeap:pop()
+	--   ...
+	-- end
+	function heap:pop()
+		local root
+		if self._size > 0 then
+			root = self._heap[1]
+			self._heap[1] = self._heap[self._size]
+			self._heap[self._size] = nil
+			self._size = self._size-1
+			if self._size>1 then
+				percolate_down(self, 1)
+			end
+		end
+		return root
+	end
+
+	--- Restores the `heap` property.
+	-- Reorders the `heap` with respect to the comparison function being used.
+	-- When given argument __item__ (a value existing in the `heap`), will sort from that very item in the `heap`.
+	-- Otherwise, the whole `heap` will be cheacked.
+	-- @class function
+	-- @tparam[opt] value item the modified value
+	-- @treturn heap self (the calling `heap` itself, can be chained)
+	-- @usage myHeap:heapify()
+	function heap:heapify(item)
+		if self._size == 0 then return end
+		if item then
+			local i = Utils.indexOf(self._heap,item)
+			if i then
+				percolate_down(self, i)
+				percolate_up(self, i)
+			end
+			return
+		end
+		for i = floor(self._size/2),1,-1 do
+			percolate_down(self,i)
+		end
+		return self
+	end
+
+	return heap
+end

sys/modules/opus/jumper/core/node.lua

@@ -0,0 +1,41 @@
+--- The Node class.
+-- The `node` represents a cell (or a tile) on a collision map. Basically, for each single cell (tile)
+-- in the collision map passed-in upon initialization, a `node` object will be generated
+-- and then cached within the `grid`.
+--
+-- In the following implementation, nodes can be compared using the `<` operator. The comparison is
+-- made with regards of their `f` cost. From a given node being examined, the `pathfinder` will expand the search
+-- to the next neighbouring node having the lowest `f` cost. See `core.bheap` for more details.
+--
+if (...) then
+
+	local Node = {}
+	Node.__index = Node
+
+	function Node:new(x,y,z)
+		return setmetatable({x = x, y = y, z = z }, Node)
+	end
+
+	-- Enables the use of operator '<' to compare nodes.
+	-- Will be used to sort a collection of nodes in a binary heap on the basis of their F-cost
+	function Node.__lt(A,B) return (A._f < B._f) end
+
+	function Node:getX() return self.x end
+	function Node:getY() return self.y end
+	function Node:getZ() return self.z end
+
+	--- Clears temporary cached attributes of a `node`.
+	-- Deletes the attributes cached within a given node after a pathfinding call.
+	-- This function is internally used by the search algorithms, so you should not use it explicitely.
+	function Node:reset()
+		self._g, self._h, self._f = nil, nil, nil
+		self._opened, self._closed, self._parent = nil, nil, nil
+		return self
+	end
+
+	return setmetatable(Node,
+		{__call = function(_,...)
+			return Node:new(...)
+		end}
+	)
+end

sys/modules/opus/jumper/core/path.lua

@@ -0,0 +1,67 @@
+--- The Path class.
+-- The `path` class is a structure which represents a path (ordered set of nodes) from a start location to a goal.
+-- 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.
+-- It should normally not be used explicitely, yet it remains fully accessible.
+--
+
+if (...) then
+
+	local t_remove = table.remove
+
+	local Path = {}
+	Path.__index = Path
+
+	function Path:new()
+		return setmetatable({_nodes = {}}, Path)
+	end
+
+	--- Iterates on each single `node` along a `path`. At each step of iteration,
+	-- returns the `node` plus a count value. Aliased as @{Path:nodes}
+	-- @usage
+	-- for node, count in p:iter() do
+	--   ...
+	-- end
+	function Path:nodes()
+		local i = 1
+		return function()
+			if self._nodes[i] then
+				i = i+1
+				return self._nodes[i-1],i-1
+			end
+		end
+	end
+
+	--- `Path` compression modifier. Given a `path`, eliminates useless nodes to return a lighter `path`
+	-- consisting of straight moves. Does the opposite of @{Path:fill}
+	-- @class function
+	-- @treturn path self (the calling `path` itself, can be chained)
+	-- @see Path:fill
+	-- @usage p:filter()
+	function Path:filter()
+		local i = 2
+		local xi,yi,zi,dx,dy,dz, olddx, olddy, olddz
+		xi,yi,zi = self._nodes[i].x, self._nodes[i].y, self._nodes[i].z
+		dx, dy,dz = xi - self._nodes[i-1].x, yi-self._nodes[i-1].y, zi-self._nodes[i-1].z
+		while true do
+			olddx, olddy, olddz = dx, dy, dz
+			if self._nodes[i+1] then
+				i = i+1
+				xi, yi, zi = self._nodes[i].x, self._nodes[i].y, self._nodes[i].z
+				dx, dy, dz = xi - self._nodes[i-1].x, yi - self._nodes[i-1].y, zi - self._nodes[i-1].z
+				if olddx == dx and olddy == dy and olddz == dz then
+					t_remove(self._nodes, i-1)
+					i = i - 1
+				end
+			else break end
+		end
+		return self
+	end
+
+	return setmetatable(Path,
+		{__call = function(_,...)
+			return Path:new(...)
+		end
+	})
+end

sys/modules/opus/jumper/core/utils.lua

@@ -0,0 +1,57 @@
+-- Various utilities for Jumper top-level modules
+
+if (...) then
+
+	-- Dependencies
+	local _PATH = (...):gsub('%.utils$','')
+	local Path = require (_PATH .. '.path')
+
+	-- Local references
+	local pairs = pairs
+	local t_insert = table.insert
+
+	-- Raw array items count
+	local function arraySize(t)
+		local count = 0
+		for _ in pairs(t) do
+			count = count+1
+		end
+		return count
+	end
+
+	-- Extract a path from a given start/end position
+	local function traceBackPath(finder, node, startNode)
+		local path = Path:new()
+		path._grid = finder._grid
+		while true do
+			if node._parent then
+				t_insert(path._nodes,1,node)
+				node = node._parent
+			else
+				t_insert(path._nodes,1,startNode)
+				return path
+			end
+		end
+	end
+
+	-- Lookup for value in a table
+	local indexOf = function(t,v)
+		for i = 1,#t do
+			if t[i] == v then return i end
+		end
+		return nil
+	end
+
+	-- Is i out of range
+	local function outOfRange(i,low,up)
+		return (i< low or i > up)
+	end
+
+	return {
+		arraySize = arraySize,
+		indexOf = indexOf,
+		outOfRange = outOfRange,
+		traceBackPath = traceBackPath
+	}
+
+end

sys/modules/opus/jumper/grid.lua

@@ -0,0 +1,101 @@
+--- 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.
+
+if (...) then
+
+	-- Dependencies
+	local _PATH = (...):gsub('%.grid$','')
+
+	-- Local references
+	local Utils = require (_PATH .. '.core.utils')
+	local Node = require (_PATH .. '.core.node')
+
+	-- Local references
+	local setmetatable = setmetatable
+
+	-- Offsets for straights moves
+	local straightOffsets = {
+		{x = 1, y = 0, z = 0} --[[W]], {x = -1, y =  0, z =  0}, --[[E]]
+		{x = 0, y = 1, z = 0} --[[S]], {x =  0, y = -1, z =  0}, --[[N]]
+		{x = 0, y = 0, z = 1} --[[U]], {x =  0, y = -0, z = -1}, --[[D]]
+	}
+
+	local Grid = {}
+	Grid.__index = Grid
+
+	function Grid:new(dim)
+		local newGrid = { }
+		newGrid._min_x, newGrid._max_x = dim.x, dim.ex
+		newGrid._min_y, newGrid._max_y = dim.y, dim.ey
+		newGrid._min_z, newGrid._max_z = dim.z, dim.ez
+		newGrid._nodes = { }
+		newGrid._width = (newGrid._max_x-newGrid._min_x)+1
+		newGrid._height = (newGrid._max_y-newGrid._min_y)+1
+		newGrid._length = (newGrid._max_z-newGrid._min_z)+1
+		return setmetatable(newGrid,Grid)
+	end
+
+	function Grid:isWalkableAt(x, y, z)
+		local node = self:getNodeAt(x,y,z)
+		return node and node.walkable ~= 1
+	end
+
+	function Grid:getWidth()
+		return self._width
+	end
+
+	function Grid:getHeight()
+		 return self._height
+	end
+
+	function Grid:getNodes()
+		return self._nodes
+	end
+
+	function Grid:getBounds()
+		return self._min_x, self._min_y, self._min_z, self._max_x, self._max_y, self._max_z
+	end
+
+	--- Returns neighbours. The returned value is an array of __walkable__ nodes neighbouring a given `node`.
+	-- @treturn {node,...} an array of nodes neighbouring a given node
+	function Grid:getNeighbours(node)
+		local neighbours = {}
+		for i = 1,#straightOffsets do
+			local n = self:getNodeAt(
+				node.x + straightOffsets[i].x,
+				node.y + straightOffsets[i].y,
+				node.z + straightOffsets[i].z
+			)
+			if n and self:isWalkableAt(n.x, n.y, n.z) then
+				neighbours[#neighbours+1] = n
+			end
+		end
+
+		return neighbours
+	end
+
+ function Grid:getNodeAt(x,y,z)
+		if not x or not y or not z then return end
+		if Utils.outOfRange(x,self._min_x,self._max_x) then return end
+		if Utils.outOfRange(y,self._min_y,self._max_y) then return end
+		if Utils.outOfRange(z,self._min_z,self._max_z) then return end
+
+		-- inefficient
+		if not self._nodes[y] then self._nodes[y] = {} end
+		if not self._nodes[y][x] then self._nodes[y][x] = {} end
+		if not self._nodes[y][x][z] then self._nodes[y][x][z] = Node:new(x,y,z) end
+		return self._nodes[y][x][z]
+	end
+
+	return setmetatable(Grid,{
+		__call = function(self,...)
+			return self:new(...)
+		end
+	})
+
+end

sys/modules/opus/jumper/pathfinder.lua

@@ -0,0 +1,104 @@
+--[[
+	The following License applies to all files within the jumper directory.
+
+	Note that this is only a partial copy of the full jumper code base. Also,
+	the code was modified to support 3D maps.
+--]]
+
+--[[
+This work is under MIT-LICENSE
+Copyright (c) 2012-2013 Roland Yonaba.
+
+-- https://opensource.org/licenses/MIT
+
+--]]
+
+local _VERSION = ""
+local _RELEASEDATE = ""
+
+if (...) then
+
+	-- Dependencies
+	local _PATH = (...):gsub('%.pathfinder$','')
+	local Utils     = require (_PATH .. '.core.utils')
+
+	-- Internalization
+	local pairs = pairs
+	local assert = assert
+	local setmetatable = setmetatable
+
+	--- Finders (search algorithms implemented). Refers to the search algorithms actually implemented in Jumper.
+	-- <li>[A*](http://en.wikipedia.org/wiki/A*_search_algorithm)</li>
+	local Finders = {
+		['ASTAR']     = require (_PATH .. '.search.astar'),
+	}
+
+	-- Will keep track of all nodes expanded during the search
+	-- to easily reset their properties for the next pathfinding call
+	local toClear = {}
+
+	-- Performs a traceback from the goal node to the start node
+	-- Only happens when the path was found
+
+	local Pathfinder = {}
+	Pathfinder.__index = Pathfinder
+
+	function Pathfinder:new(heuristic)
+		local newPathfinder = {}
+		setmetatable(newPathfinder, Pathfinder)
+		self._finder = Finders.ASTAR
+		self._heuristic = heuristic
+		return newPathfinder
+	end
+
+	function Pathfinder:setGrid(grid)
+		self._grid = grid
+		return self
+	end
+
+	--- Calculates a `path`. Returns the `path` from start to end location
+	-- Both locations must exist on the collision map. The starting location can be unwalkable.
+	-- @treturn path a path (array of nodes) when found, otherwise nil
+	-- @usage local path = myFinder:getPath(1,1,5,5)
+	function Pathfinder:getPath(startX, startY, startZ, ih, endX, endY, endZ, oh)
+		self:reset()
+		local startNode = self._grid:getNodeAt(startX, startY, startZ)
+		local endNode = self._grid:getNodeAt(endX, endY, endZ)
+		if not startNode or not endNode then
+			return nil
+		end
+
+		startNode.heading = ih
+		endNode.heading = oh
+
+		assert(startNode, ('Invalid location [%d, %d, %d]'):format(startX, startY, startZ))
+		assert(endNode and self._grid:isWalkableAt(endX, endY, endZ),
+			('Invalid or unreachable location [%d, %d, %d]'):format(endX, endY, endZ))
+		local _endNode = self._finder(self, startNode, endNode, toClear)
+		if _endNode then
+			return Utils.traceBackPath(self, _endNode, startNode)
+		end
+		return nil
+	end
+
+	--- Resets the `pathfinder`. This function is called internally between
+	-- successive pathfinding calls, so you should not
+	-- use it explicitely, unless under specific circumstances.
+	-- @class function
+	-- @treturn pathfinder self (the calling `pathfinder` itself, can be chained)
+	-- @usage local path, len = myFinder:getPath(1,1,5,5)
+	function Pathfinder:reset()
+		for node in pairs(toClear) do node:reset() end
+		toClear = {}
+		return self
+	end
+
+	-- Returns Pathfinder class
+	Pathfinder._VERSION = _VERSION
+	Pathfinder._RELEASEDATE = _RELEASEDATE
+	return setmetatable(Pathfinder,{
+		__call = function(self,...)
+			return self:new(...)
+		end
+	})
+end

sys/modules/opus/jumper/search/astar.lua

@@ -0,0 +1,77 @@
+-- Astar algorithm
+-- This actual implementation of A-star is based on
+-- [Nash A. & al. pseudocode](http://aigamedev.com/open/tutorials/theta-star-any-angle-paths/)
+
+if (...) then
+
+	-- Internalization
+	local huge = math.huge
+
+	-- Dependancies
+	local _PATH = (...):match('(.+)%.search.astar$')
+	local Heap = require (_PATH.. '.core.bheap')
+
+	-- Updates G-cost
+	local function computeCost(node, neighbour, heuristic)
+		local mCost, heading = heuristic(neighbour, node) -- Heuristics.EUCLIDIAN(neighbour, node)
+
+		if node._g + mCost < neighbour._g then
+			neighbour._parent = node
+			neighbour._g = node._g + mCost
+			neighbour.heading = heading
+		end
+	end
+
+	-- Updates vertex node-neighbour
+	local function updateVertex(openList, node, neighbour, endNode, heuristic)
+		local oldG = neighbour._g
+		computeCost(node, neighbour, heuristic)
+		if neighbour._g < oldG then
+			if neighbour._opened then neighbour._opened = false end
+			neighbour._h = heuristic(endNode, neighbour)
+			neighbour._f = neighbour._g + neighbour._h
+			openList:push(neighbour)
+			neighbour._opened = true
+		end
+	end
+
+	-- Calculates a path.
+	-- Returns the path from location `<startX, startY>` to location `<endX, endY>`.
+	return function (finder, startNode, endNode, toClear)
+		local openList = Heap()
+		startNode._g = 0
+		startNode._h = finder._heuristic(endNode, startNode)
+		startNode._f = startNode._g + startNode._h
+		openList:push(startNode)
+		toClear[startNode] = true
+		startNode._opened = true
+
+		while not openList:empty() do
+			local node = openList:pop()
+			node._closed = true
+			if node == endNode then return node end
+			local neighbours = finder._grid:getNeighbours(node)
+			for i = 1,#neighbours do
+				local neighbour = neighbours[i]
+				if not neighbour._closed then
+					toClear[neighbour] = true
+					if not neighbour._opened then
+						neighbour._g = huge
+						neighbour._parent = nil
+					end
+					updateVertex(openList, node, neighbour, endNode, finder._heuristic)
+				end
+			end
+
+			--[[
+			printf('x:%d y:%d z:%d  g:%d', node.x, node.y, node.z, node._g)
+			for i = 1,#neighbours do
+				local n = neighbours[i]
+				printf('x:%d y:%d z:%d f:%f g:%f h:%d', n.x, n.y, n.z, n._f, n._g, n.heading or -1)
+			end
+			--]]
+
+		end
+		return nil
+	end
+end