ig.

pathfinding

Pathfinding for entities using A*.
- some aspects based on PathFinding.js and impact-astar-for-entities
- for garbage collector friendly code, path points are nodes from the pathfinding grid (so don't modify the path points).
- path is constructed in reverse order to allow user to ".length--" to remove a node when reached, instead of shifting/splicing which is usually worse on performance. Tip: base pathfinding works best when entity size is <= 3x the tilesize. For larger entities, add a ig.PathfindingMap with green tiles around the middle of your entity's path of travel for best results! IMPORTANT: if using a ig.PathfindingMap, the tilesize must match the ig.CollisionMap's tilesize!

Author:
  • Collin Hover - collinhover.com
  • Jakub Siemiatkowski - jsiemiatkowski@gmail.com
Source:

Methods

<static> getBoundsPathfollowing(entity, x, y, width, height, target, zeroGrav, bounds) → {Object}

Calculates following position and bounds for an entity to align with while following a path.

Parameters:
Name Type Argument Default Description
entity ig.EntityExtended entity to find position for.
x Number x position of entity
y Number y position of entity
width Number width of entity
height Number height of entity
target ig.pathfinding.Node | Vector2 | Object target node or position
zeroGrav Boolean <optional>
 false whether to treat as if has no gravity
bounds Object <optional>
 bounding object
Source:
Returns:
{ Object } bounds within bounds of entity to start and align while following a path.

<static> getDiagonalNeighbors(node) → {Array}

Get only the diagonal walkable neighbors of the given node, excluding direct.

Parameters:
Name Type Description
node ig.pathfinding.Node node to get neighbors for
Source:
Returns:
{ Array } neighbors of node
Example 
// neighbors are precalculated on rebuild
// so this is usually a bad idea:
var myNeighbors = ig.pathfinding.getNeighbors( myNode );
// this is a better idea
var myNeighbors = myNode.neighbors;

<static> getDirectNeighbors(node) → {Array}

Get only the direct walkable neighbors of the given node, excluding diagonals.

Parameters:
Name Type Description
node ig.pathfinding.Node node to get neighbors for
Source:
Returns:
{ Array } neighbors of node
Example 
// neighbors are precalculated on rebuild
// so this is usually a bad idea:
var myNeighbors = ig.pathfinding.getNeighbors( myNode );
// this is a better idea
var myNeighbors = myNode.neighbors;

<static> getEntityNeighborPositionX(x, width, dirX)

Calculates x position of node next to entity.

Parameters:
Name Type Description
x Number x position of entity
width Number width of entity
dirX Number x direction
Source:

<static> getEntityNeighborPositionY(y, height, dirY, zeroGrav)

Calculates y position of node next to entity.

Parameters:
Name Type Argument Default Description
y Number y position of entity
height Number height of entity
dirY Number y direction
zeroGrav Boolean <optional>
 false whether to treat as if has no gravity
Source:

<static> getEntityOnSmoothSlope(entity, dirX, dirY) → {boolean}

Calculates whether entity (with gravity) may be moving along a smooth slope. This is useful for knowing if the entity can just move or if it needs to jump.

Parameters:
Name Type Argument Default Description
entity ig.EntityExtended entity
dirX Number x direction of movement, where < 0 is left
dirY Number <optional>
 both y direction of movement, where < 0 is up
Source:
Returns:
{ boolean } true if moving along a smooth slope

<static> getGridNode(gridX, gridY) → {ig.pathfinding.Node}

Get a node in the pathfinding grid using grid coordinates.

Parameters:
Name Type Description
gridX Number x index of node.
gridY Number y index of node.
Source:
Returns:
{ ig.pathfinding.Node } node at index.

<static> getGridWalkableNode(x, y, gridOffsetX, gridOffsetY, avoidEntities, entityPathing) → {ig.pathfinding.Node}

Get a walkable node in the pathfinding grid using grid coordinates.

Parameters:
Name Type Argument Default Description
x Number x index to start from.
y Number y index to start from.
gridOffsetX Number <optional>
 0 number of nodes to offset on x.
gridOffsetY Number <optional>
 0 number of nodes to offset on y.
avoidEntities Boolean <optional>
 false whether to take into account entities that may collide, requires entityPathing.
entityPathing ig.EntityExtended <optional>
 entity that will be walking to node, only required when avoiding entities.
Source:
Returns:
{ ig.pathfinding.Node } walkable node at index.

<static> getNeighbors(node) → {Array}

Get all walkable neighbors of the given node.

Parameters:
Name Type Description
node ig.pathfinding.Node node to get neighbors for
Source:
Returns:
{ Array } neighbors of node
Example 
// neighbors are precalculated on rebuild
// so this is usually a bad idea:
var myNeighbors = ig.pathfinding.getNeighbors( myNode );
// this is a better idea
var myNeighbors = myNode.neighbors;

<static> getNode(x, y, gridOffsetX, gridOffsetY) → {ig.pathfinding.Node}

Get a node in the pathfinding grid using world coordinates.

Parameters:
Name Type Argument Default Description
x Number x location in world.
y Number y location in world.
gridOffsetX Number <optional>
 0 number of nodes to offset on x.
gridOffsetY Number <optional>
 0 number of nodes to offset on y.
Source:
Returns:
{ ig.pathfinding.Node } node at point.

<static> getPathAwayFrom(fromX, fromY, awayFromX, awayFromY, avoidEntities, searchDistance, entityPathing, heuristicType) → {Array}

Get a path that goes furthest away from a point.

Parameters:
Name Type Argument Default Description
fromX Number x position to start from
fromY Number y position to start from
awayFromX Number x position to path away from
awayFromY Number y position to path away from
avoidEntities Boolean <optional>
 false whether to try to avoid entities
searchDistance Number <optional>
 ig.pathfinding.AWAY_FROM_DISTANCE distance to flee
entityPathing ig.EntityExtended <optional>
 entity to find path for
heuristicType String <optional>
 Type of heuristic function to use
Source:
Returns:
{ Array } path as a list of points with x and y properties.

<static> getPathAwayFromEntity(entityPathing, entityTarget, avoidEntities, searchDistance, heuristicType) → {Array}

Get the path that goes furthest away from a target entity for another entity.

Parameters:
Name Type Argument Default Description
entityPathing ig.EntityExtended entity to find path for
entityTarget ig.EntityExtended entity to find path away from
avoidEntities Boolean <optional>
 false whether to try to avoid entities
searchDistance Number <optional>
 ig.pathfinding.AWAY_FROM_DISTANCE distance to flee
heuristicType String <optional>
 Type of heuristic function to use
Source:
Returns:
{ Array } path as a list of points with x and y properties.

<static> getPathAwayFromPoint(entityPathing, awayFromX, awayFromY, avoidEntities, searchDistance, heuristicType) → {Array}

Get a path that goes furthest away from a point for an entity.

Parameters:
Name Type Argument Default Description
entityPathing ig.EntityExtended entity to find path for
awayFromX Number x position to path away from
awayFromY Number y position to path away from
avoidEntities Boolean <optional>
 false whether to try to avoid entities
searchDistance Number <optional>
 ig.pathfinding.AWAY_FROM_DISTANCE distance to flee
heuristicType String <optional>
 Type of heuristic function to use
Source:
Returns:
{ Array } path as a list of points with x and y properties.

<static> getPathTo(fromX, fromY, targetX, targetY, avoidEntities, searchDistance, entityPathing, entityTarget, heuristicType) → {Array}

Get the path to target point.

Parameters:
Name Type Argument Default Description
fromX Number x position to start from
fromY Number y position to start from
targetX Number x position to path to
targetY Number y position to path to
avoidEntities Boolean <optional>
 false whether to try to avoid entities
searchDistance Number <optional>
 infinity maximum positive distance to search
entityPathing ig.EntityExtended <optional>
 entity to find path for
entityTarget ig.EntityExtended <optional>
 entity to find path to
heuristicType String <optional>
 Type of heuristic function to use
Source:
Returns:
{ Array } path as a list of points with x and y properties.

<static> getPathToEntity(entityPathing, entityTarget, avoidEntities, searchDistance, heuristicType) → {Array}

Get the path to target entity from another entity.

Parameters:
Name Type Argument Default Description
entityPathing ig.EntityExtended entity to find path for
entityTarget ig.EntityExtended entity to find path to
avoidEntities Boolean <optional>
 false whether to try to avoid entities
searchDistance Number <optional>
 infinity maximum positive distance to search
heuristicType String <optional>
 Type of heuristic function to use
Source:
Returns:
{ Array } path as a list of points with x and y properties.

<static> getPathToPoint(entityPathing, targetX, targetY, avoidEntities, searchDistance, entityTarget, heuristicType) → {Array}

Get the path to a point from an entity.

Parameters:
Name Type Argument Default Description
entityPathing ig.EntityExtended entity to find path for
targetX Number x position to path to
targetY Number y position to path to
avoidEntities Boolean <optional>
 false whether to try to avoid entities
searchDistance Number <optional>
 infinity maximum positive distance to search
entityTarget ig.EntityExtended <optional>
 entity to find path to
heuristicType String <optional>
 Type of heuristic function to use
Source:
Returns:
{ Array } path as a list of points with x and y properties.

<static> getPositionPathfindingEntities(entity, target, positions) → {Object}

Calculates the positions and bounds for entities to align for pathfinding.

Parameters:
Name Type Argument Description
entity ig.EntityExtended entity to find position for.
target ig.EntityExtended target entity.
positions Object <optional>
 positions object with from and target vectors
Source:
Returns:
{ Object } positions within bounds of entity to start and align for pathfinding.

<static> getPositionPathfindingPoint(entity, targetX, targetY, position) → {Object}

Calculates the positions and bounds for entity to align for pathfinding.

Parameters:
Name Type Argument Description
entity ig.EntityExtended entity to find position for.
targetX Number target x
targetY Number target y
position Object <optional>
 position object
Source:
Returns:
{ Object } position within bounds of entity to start and align for pathfinding.

<static> getSlopeDirectionY(entity, dirX) → {Number}

Calculates the y direction of a slope an entity (with gravity) is moving on, based on the x direction of movement. This is useful for knowing if the entity should move down or up in addition to sideways.

Parameters:
Name Type Description
entity ig.EntityExtended entity
dirX Number x direction of movement, where < 0 is left
Source:
Returns:
{ Number } direction y, where -1 is up

<static> getWalkableNode(x, y, gridOffsetX, gridOffsetY, avoidEntities, entityPathing) → {ig.pathfinding.Node}

Get a walkable node in the pathfinding grid using world coordinates.

Parameters:
Name Type Argument Default Description
x Number x location in world to start from.
y Number y location in world to start from.
gridOffsetX Number <optional>
 0 number of nodes to offset on x.
gridOffsetY Number <optional>
 0 number of nodes to offset on y.
avoidEntities Boolean <optional>
 false whether to take into account entities that may collide, requires entityPathing.
entityPathing ig.EntityExtended <optional>
 entity that will be walking to node, only required when avoiding entities.
Source:
Returns:
{ ig.pathfinding.Node } walkable node at point.

<static> getWalkableNodeChain(x, y, dirX, dirY, numNodes, avoidEntities, entityPathing, nodes) → {Array}

Get a chain of walkable nodes in the pathfinding grid using world coordinates in a direction.

Parameters:
Name Type Argument Default Description
x Number x location in world to start from.
y Number y location in world to start from.
dirX Number x direction, between -1 and 1, to find chain.
dirY Number y direction, between -1 and 1, to find chain.
numNodes Number <optional>
 2 maximum number of nodes to find.
avoidEntities Boolean <optional>
 false whether to take into account entities that may collide, requires entityPathing.
entityPathing ig.EntityExtended <optional>
 entity that will be walking to node, only required when avoiding entities.
nodes Array <optional>
 array to add nodes to
Source:
Returns:
{ Array } walkable nodes in direction.

<static> isDirectionWalkable(node, dirX, dirY, nodeFrom)

Get if a node is walkable from a direction, accounting for one way and, when the node from is passed, diagonal movement.

Parameters:
Name Type Argument Description
node ig.pathfinding.Node node to check
dirX Number direction of travel on x
dirY Number direction of travel on y
nodeFrom ig.pathfinding.Node <optional>
 node traveling from
Source:

<static> isGridPointInGrid(gridX, gridY) → {Boolean}

Check if node is within the bounds of pathfinding grid using grid coordinates.

Parameters:
Name Type Description
gridX Number x index of node.
gridY Number y index of node.
Source:
Returns:
{ Boolean } whether node is within grid.

<static> isGridWalkable(x, y, gridOffsetX, gridOffsetY, avoidEntities, entityPathing) → {Boolean}

Check if a grid location is walkable using grid coordinates.

Parameters:
Name Type Argument Default Description
x Number x index to start from.
y Number y index to start from.
gridOffsetX Number <optional>
 0 number of nodes to offset on x.
gridOffsetY Number <optional>
 0 number of nodes to offset on y.
avoidEntities Boolean <optional>
 false whether to take into account entities that may collide, requires entityPathing.
entityPathing ig.EntityExtended <optional>
 entity that will be walking to node, only required when avoiding entities.
Source:
Returns:
{ Boolean } whether node is walkable.

<static> isPointInGrid(x, y, gridOffsetX, gridOffsetY) → {Boolean}

Check if node is within the bounds of pathfinding grid using world coordinates.

Parameters:
Name Type Argument Default Description
x Number x location in world.
y Number y location in world.
gridOffsetX Number <optional>
 0 number of nodes to offset on x.
gridOffsetY Number <optional>
 0 number of nodes to offset on y.
Source:
Returns:
{ Boolean } whether node is within grid.

<static> isWalkable(x, y, gridOffsetX, gridOffsetY, avoidEntities, entityPathing) → {Boolean}

Check if a world location is walkable using world coordinates.

Parameters:
Name Type Argument Default Description
x Number x location in world to start from.
y Number y location in world to start from.
gridOffsetX Number <optional>
 0 number of nodes to offset on x.
gridOffsetY Number <optional>
 0 number of nodes to offset on y.
avoidEntities Boolean <optional>
 false whether to take into account entities that may collide, requires entityPathing.
entityPathing ig.EntityExtended <optional>
 entity that will be walking to node, only required when avoiding entities.
Source:
Returns:
{ Boolean } whether node is walkable.

<static> nodeHasCollidingEntities(node, nodeFrom, entityPathing, entityTarget) → {Boolean}

Checks a node to see if there are any entities that would collide with pathing entity.

Parameters:
Name Type Argument Description
node ig.pathfinding.Node node to get weight for
nodeFrom ig.pathfinding.Node node moving from
entityPathing ig.EntityExtended entity to find path for
entityTarget ig.EntityExtended <optional>
 entity to find path to
Source:
Returns:
{ Boolean } whether node has a colliding entity

<static> rebuild(collisionMap, pathfindingMap)

Rebuild pathfinding.
- this is called automatically by ig.GameExtended#buildLevel when ig.CONFIG.PATHFINDING.BUILD_WITH_LEVEL is enabled. IMPORTANT: if using a ig.PathfindingMap, the tilesize must match the ig.CollisionMap's tilesize!

Parameters:
Name Type Argument Description
collisionMap ig.CollisionMap map to determine walkability of nodes
pathfindingMap ig.PathfindingMap <optional>
 map to add settings to each node
Source:

<static> unload()

Unload pathfinding and clear map, grid, etc. IMPORTANT: this is called automatically by ig.GameExtended#unloadLevel.

Source: