NavigationGrid

2D navigation grid supporting weighted traversal costs, walkability flags, elevation rules, dynamic obstacles, chunk boundary links, and A* pathfinding.

Classes

NavigationGrid

Methods

(static) fromAscii(ascii, legendopt, optionsopt) → {NavigationGrid}

Construct a NavigationGrid from an ASCII layout. Legend maps characters to properties like { walkable, cost, elevation }.

Parameters:
NameTypeAttributesDefaultDescription
asciistring

Multiline text representation of the grid

legendObject<optional>
{}

Mapping from character to cell properties

optionsObject<optional>
{}

Grid options

Returns:
Type: 
NavigationGrid

(static) fromTilemap(tilemap, optionsopt) → {NavigationGrid}

Construct a NavigationGrid from a Thalassa Tilemap.

Parameters:
NameTypeAttributesDefaultDescription
tilemapObject

Tilemap instance

optionsObject<optional>
{}

Grid options

Returns:
Type: 
NavigationGrid

Add a chunk link or portal connecting two coordinates. Supports both addChunkLink(fromX, fromY, toX, toY, options) and addChunkLink({ from, to, cost, bidirectional, id }).

Parameters:
NameTypeAttributesDefaultDescription
linkOrFromXnumber | Object
fromYnumber<optional>
toXnumber<optional>
toYnumber<optional>
optionsObject<optional>
{}
Returns:

The created chunk link.

Type: 
Object

addObstacle(idOrConfig, xopt, yopt, widthopt, heightopt) → {Object}

Add a dynamic obstacle blocking one or more cells. Supports both addObstacle(id, x, y, width, height) and addObstacle({ id, x, y, width, height, cells }).

Parameters:
NameTypeAttributesDefaultDescription
idOrConfigstring | Object
xnumber<optional>
0
ynumber<optional>
0
widthnumber<optional>
1
heightnumber<optional>
1
Returns:

The registered obstacle record.

Type: 
Object

addPortal(linkOrFromX, fromYopt, toXopt, toYopt, optionsopt) → {Object}

Alias for addChunkLink.

Parameters:
NameTypeAttributesDefaultDescription
linkOrFromXnumber | Object
fromYnumber<optional>
toXnumber<optional>
toYnumber<optional>
optionsObject<optional>
{}
Returns:
Type: 
Object

Clear all chunk links.

clearObstacles()

Remove all dynamic obstacles.

clone() → {NavigationGrid}

Create a clone of this NavigationGrid.

Returns:
Type: 
NavigationGrid

findPath(startArg, goalArg, optionsOrGoalXopt, goalYopt, optionsopt) → {NavigationPath}

Compute the lowest-cost path from start to goal using A*. Supports both findPath(start, goal, options) and findPath(startX, startY, goalX, goalY, options).

Parameters:
NameTypeAttributesDescription
startArgObject | Array | number

Starting point { x, y }, [x, y], or startX number

goalArgObject | Array | number

Goal point { x, y }, [x, y], or startY number

optionsOrGoalXObject | number<optional>

Options object, or goalX number

goalYnumber<optional>

goalY number if coordinates were passed numerically

optionsObject<optional>

Options object if coordinates were passed numerically

Properties
NameTypeAttributesDefaultDescription
allowDiagonalboolean<optional>

Allow diagonal steps (default this.allowDiagonal)

preventCornerCuttingboolean<optional>
true

Strict corner-cutting prevention past solid walls

maxClimbHeightnumber<optional>

Max traversable height diff (default this.maxClimbHeight)

diagonalCostMultipliernumber<optional>

Multiplier for diagonal steps

includeStartboolean<optional>
false

Whether to include the starting tile in the path

useChunkLinksboolean<optional>
true

Whether to traverse chunk links/portals

maxCostnumber<optional>

Search cost cutoff limit

isWalkablefunction<optional>

Custom walkability predicate (x, y) => boolean

Returns:

Path result containing status, success, cost, and steps.

Type: 
NavigationPath

getCell(x, y) → {Object|null}

Get cell properties at (x, y).

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

Cell state or null if out of bounds.

Type: 
Object | null

Get outgoing chunk links from coordinate (x, y).

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:
Type: 
Array.<Object>

getCost(x, y) → {number}

Get traversal cost for a cell.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

Cost value (>= 1.0) or Infinity if out of bounds / unwalkable.

Type: 
number

getElevation(x, y) → {number|null}

Get elevation level for a cell.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:

Elevation level or null if out of bounds.

Type: 
number | null

getInvalidatedRoutes() → {Array.<string>}

Query which registered routes are currently invalid.

Returns:

List of invalidated route IDs.

Type: 
Array.<string>

getMaxClimbHeight() → {number}

Get maximum climb height difference.

Returns:
Type: 
number

getObstacle(id) → {Object|null}

Get obstacle by ID.

Parameters:
NameTypeDescription
idstring
Returns:
Type: 
Object | null

getObstacles() → {Array.<Object>}

Get all active obstacles.

Returns:
Type: 
Array.<Object>

getRegisteredRoute(id) → {Array|null}

Get a registered route by ID.

Parameters:
NameTypeDescription
idstring
Returns:
Type: 
Array | null

hasObstacle(id) → {boolean}

Check if obstacle exists by ID.

Parameters:
NameTypeDescription
idstring
Returns:
Type: 
boolean

inBounds(x, y) → {boolean}

Check whether (x, y) is inside the grid bounds.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:
Type: 
boolean

invalidateRoutes() → {Array.<string>}

Explicitly invalidate routes and increment version.

Returns:

IDs of registered routes that are invalid.

Type: 
Array.<string>

isCellBlockedByObstacle(x, y) → {boolean}

Check if a specific cell is blocked by dynamic obstacles.

Parameters:
NameTypeDescription
xnumber
ynumber
Returns:
Type: 
boolean

isRouteValid(path, optionsopt) → {boolean}

Check if an existing path remains valid.

Parameters:
NameTypeAttributesDefaultDescription
pathArray

Array of { x, y }

optionsObject<optional>
{}
Returns:
Type: 
boolean

isWalkable(x, y, checkObstaclesopt) → {boolean}

Check if a cell is walkable and not blocked by dynamic obstacles.

Parameters:
NameTypeAttributesDefaultDescription
xnumber
ynumber
checkObstaclesboolean<optional>
true

Whether dynamic obstacles block walkability

Returns:
Type: 
boolean

offRouteInvalidated(callback)

Remove an invalidation listener.

Parameters:
NameTypeDescription
callbackfunction

onRouteInvalidated(callback) → {function}

Subscribe to route invalidation events.

Parameters:
NameTypeDescription
callbackfunction

Event listener

Returns:

Unsubscribe function

Type: 
function

registerRoute(id, path)

Register a route to monitor for invalidation when obstacles change.

Parameters:
NameTypeDescription
idstring

Identifier for the route

pathArray

Array of { x, y } steps

Remove a chunk link by ID.

Parameters:
NameTypeDescription
idstring
Returns:

True if removed.

Type: 
boolean

removeObstacle(id) → {boolean}

Remove a dynamic obstacle by ID.

Parameters:
NameTypeDescription
idstring
Returns:

True if removed.

Type: 
boolean

setCell(x, y, propsopt) → {boolean}

Set multiple cell properties at once.

Parameters:
NameTypeAttributesDefaultDescription
xnumber
ynumber
propsObject<optional>
{}
Properties
NameTypeAttributesDescription
walkableboolean<optional>
costnumber<optional>
elevationnumber<optional>
Returns:

True if in bounds.

Type: 
boolean

setCellMaterial(x, y, materialId, stateopt, registryopt) → {boolean}

Set cell properties based on material definitions from SIM-01.

Parameters:
NameTypeAttributesDefaultDescription
xnumber
ynumber
materialIdstring

Material ID (e.g., 'water', 'grass', 'wood')

statestring<optional>
'dry'

Material state (e.g., 'dry', 'wet', 'frozen')

registryObject<optional>
null

Optional MaterialRegistry instance

Returns:

True if set.

Type: 
boolean

setCost(x, y, cost) → {boolean}

Set traversal cost for a cell.

Parameters:
NameTypeDescription
xnumber
ynumber
costnumber

Movement cost (must be >= 1.0)

Returns:

True if updated.

Type: 
boolean

setElevation(x, y, elevation) → {boolean}

Set elevation level for a cell.

Parameters:
NameTypeDescription
xnumber
ynumber
elevationnumber
Returns:

True if updated.

Type: 
boolean

setMaxClimbHeight(height)

Set maximum climb height difference between adjacent cells.

Parameters:
NameTypeDescription
heightnumber

setWalkable(x, y, walkable) → {boolean}

Set walkability flag for a cell.

Parameters:
NameTypeDescription
xnumber
ynumber
walkableboolean
Returns:

True if updated.

Type: 
boolean

unregisterRoute(id) → {boolean}

Unregister a monitored route.

Parameters:
NameTypeDescription
idstring
Returns:

True if removed.

Type: 
boolean

validateRoute(path, optionsopt) → {Object}

Validate whether an existing path remains walkable and unbroken.

Parameters:
NameTypeAttributesDefaultDescription
pathArray

Sequence of { x, y } step objects

optionsObject<optional>
{}

Validation options

Returns:

Validation report { valid, blockedIndex, blockedCell, reason }

Type: 
Object