Module pathfinder

The Pathfinder class

Finders

Finders Finders (search algorithms implemented).

Modes

Modes Search modes.

Class Pathfinder

Pathfinder:new (grid [, finderName [, walkable]]) Inits a new pathfinder
Pathfinder:annotateGrid () Evaluates clearance for the whole grid .
Pathfinder:clearAnnotations () Removes clearancevalues.
Pathfinder:setGrid (grid) Sets the grid .
Pathfinder:getGrid () Returns the grid .
Pathfinder:setWalkable (walkable) Sets the walkable value or function.
Pathfinder:getWalkable () Gets the walkable value or function.
Pathfinder:setFinder (finderName) Defines the finder.
Pathfinder:getFinder () Returns the name of the finder being used.
Pathfinder:getFinders () Returns the list of all available finders names.
Pathfinder:setHeuristic (heuristic) Sets a heuristic.
Pathfinder:getHeuristic () Returns the heuristic used.
Pathfinder:getHeuristics () Gets the list of all available heuristics.
Pathfinder:setMode (mode) Defines the search mode.
Pathfinder:getMode () Returns the search mode.
Pathfinder:getModes () Gets the list of all available search modes.
Pathfinder:setTunnelling (bool) Enables tunnelling.
Pathfinder:getTunnelling () Returns tunnelling feature state.
Pathfinder:getPath (startX, startY, endX, endY, clearance) Calculates a path.
Pathfinder:reset () Resets the pathfinder .


Finders

Finders
Finders (search algorithms implemented). Refers to the search algorithms actually implemented in Jumper.

  • A*
  • Dijkstra
  • Theta Astar
  • BFS
  • DFS
  • JPS
  • see also:

    Modes

    Modes
    Search modes. Refers to the search modes. In ORTHOGONAL mode, 4-directions are only possible when moving, including North, East, West, South. In DIAGONAL mode, 8-directions are possible when moving, including North, East, West, South and adjacent directions.

  • ORTHOGNAL
  • DIAGONAL
  • see also:

    Class Pathfinder

    The Pathfinder class.
    This class is callable. Therefore,_ Pathfinder(...) acts as a shortcut to Pathfinder:new(...).
    Pathfinder:new (grid [, finderName [, walkable]])
    Inits a new pathfinder

    Parameters:

    • grid grid a grid
    • finderName string the name of the Finder (search algorithm) to be used for search. Defaults to ASTAR when not given (see Pathfinder:getFinders).
    • walkable string, int or func the value for walkable nodes. 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.

    Usage:

       -- Example one
       local finder = Pathfinder:new(myGrid, 'ASTAR', 0)
      
       -- Example two
       local function walkable(value)
         return value > 0
       end
       local finder = Pathfinder(myGrid, 'JPS', walkable)

    Returns:

      pathfinder a new pathfinder instance
    Pathfinder:annotateGrid ()
    Evaluates clearance for the whole grid . It should be called only once, unless the collision map or the walkable attribute changes. The clearance values are calculated and cached within the grid nodes.

    Usage:

      myFinder:annotateGrid()

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)
    Pathfinder:clearAnnotations ()
    Removes clearancevalues. Clears cached clearance values for the current walkable.

    Usage:

      myFinder:clearAnnotations()

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)
    Pathfinder:setGrid (grid)
    Sets the grid . Defines the given grid as the one on which the pathfinder will perform the search.

    Parameters:

    Usage:

      myFinder:setGrid(myGrid)

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)
    Pathfinder:getGrid ()
    Returns the grid . This is a reference to the actual grid used by the pathfinder .

    Usage:

      local myGrid = myFinder:getGrid()

    Returns:

      grid the grid
    Pathfinder:setWalkable (walkable)
    Sets the walkable value or function.

    Parameters:

    Usage:

       -- Value '0' is walkable
       myFinder:setWalkable(0)
      
       -- Any value greater than 0 is walkable
       myFinder:setWalkable(function(n)
         return n>0
       end

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)
    Pathfinder:getWalkable ()
    Gets the walkable value or function.

    Usage:

      local walkable = myFinder:getWalkable()

    Returns:

      string, int or func the walkable value or function
    Pathfinder:setFinder (finderName)
    Defines the finder. It refers to the search algorithm used by the pathfinder . Default finder is ASTAR. Use Pathfinder:getFinders to get the list of available finders.

    Parameters:

    • finderName string the name of the finder to be used for further searches.

    Usage:

       --To use Breadth-First-Search
       myFinder:setFinder('BFS')

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)

    see also:

    Pathfinder:getFinder ()
    Returns the name of the finder being used.

    Usage:

      local finderName = myFinder:getFinder()

    Returns:

      string the name of the finder to be used for further searches.
    Pathfinder:getFinders ()
    Returns the list of all available finders names.

    Usage:

       local finders = myFinder:getFinders()
       for i, finderName in ipairs(finders) do
         print(i, finderName)
       end

    Returns:

      {string,...} array of built-in finders names.
    Pathfinder:setHeuristic (heuristic)
    Sets a heuristic. This is a function internally used by the pathfinder to find the optimal path during a search. Use Pathfinder:getHeuristics to get the list of all available heuristics. One can also define his own heuristic function.

    Parameters:

    • heuristic func or string heuristic function, prototyped as f(dx,dy) or as a string .

    Usage:

      myFinder:setHeuristic('MANHATTAN')

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)

    see also:

    Pathfinder:getHeuristic ()
    Returns the heuristic used. Returns the function itself.

    Usage:

      local h = myFinder:getHeuristic()

    Returns:

      func the heuristic function being used by the pathfinder

    see also:

    Pathfinder:getHeuristics ()
    Gets the list of all available heuristics.

    Usage:

       local heur = myFinder:getHeuristic()
       for i, heuristicName in ipairs(heur) do
         ...
       end

    Returns:

      {string,...} array of heuristic names.

    see also:

    Pathfinder:setMode (mode)
    Defines the search mode. The default search mode is the DIAGONAL mode, which implies 8-possible directions when moving (north, south, east, west and diagonals). In ORTHOGONAL mode, only 4-directions are allowed (north, south, east and west). Use Pathfinder:getModes to get the list of all available search modes.

    Parameters:

    • mode string the new search mode.

    Usage:

      myFinder:setMode('ORTHOGNAL')

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)

    see also:

    Pathfinder:getMode ()
    Returns the search mode.

    Usage:

      local mode = myFinder:getMode()

    Returns:

      string the current search mode

    see also:

    Pathfinder:getModes ()
    Gets the list of all available search modes.

    Usage:

       local modes = myFinder:getModes()
       for modeName in ipairs(modes) do
         ...
       end

    Returns:

      {string,...} array of search modes.

    see also:

    Pathfinder:setTunnelling (bool)
    Enables tunnelling. Defines the ability for the pathfinder to tunnel through walls when heading diagonally. This feature is not compatible with Jump Point Search algorithm (i.e. enabling it will not affect Jump Point Search)

    Parameters:

    • bool bool a boolean

    Usage:

      myFinder:setTunnelling(true)

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)
    Pathfinder:getTunnelling ()
    Returns tunnelling feature state.

    Usage:

      local isTunnellingEnabled = myFinder:getTunnelling()

    Returns:

      bool tunnelling feature actual state
    Pathfinder:getPath (startX, startY, endX, endY, clearance)
    Calculates a path. Returns the path from location [startX, startY] to location [endX, endY]. Both locations must exist on the collision map. The starting location can be unwalkable.

    Parameters:

    • startX int the x-coordinate for the starting location
    • startY int the y-coordinate for the starting location
    • endX int the x-coordinate for the goal location
    • endY int the y-coordinate for the goal location
    • clearance int the amount of clearance (i.e the pathing agent size) to consider

    Usage:

      local path = myFinder:getPath(1,1,5,5)

    Returns:

      path a path (array of nodes) when found, otherwise nil
    Pathfinder:reset ()
    Resets the pathfinder . This function is called internally between successive pathfinding calls, so you should not use it explicitely, unless under specific circumstances.

    Usage:

      local path, len = myFinder:getPath(1,1,5,5)

    Returns:

      pathfinder self (the calling pathfinder itself, can be chained)
    generated by LDoc 1.2