new NavigationGrid()
2D navigation grid supporting weighted traversal costs, walkability flags, elevation rules, dynamic obstacles, chunk boundary links, and A* pathfinding.
Classes
Methods
(static) fromAscii(ascii, legendopt, optionsopt) → {NavigationGrid}
Construct a NavigationGrid from an ASCII layout. Legend maps characters to properties like { walkable, cost, elevation }.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
ascii | string | Multiline text representation of the grid | ||
legend | Object | <optional> | {} | Mapping from character to cell properties |
options | Object | <optional> | {} | Grid options |
- Type:
- NavigationGrid
(static) fromTilemap(tilemap, optionsopt) → {NavigationGrid}
Construct a NavigationGrid from a Thalassa Tilemap.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
tilemap | Object | Tilemap instance | ||
options | Object | <optional> | {} | Grid options |
- Type:
- NavigationGrid
addChunkLink(linkOrFromX, fromYopt, toXopt, toYopt, optionsopt) → {Object}
Add a chunk link or portal connecting two coordinates. Supports both addChunkLink(fromX, fromY, toX, toY, options) and addChunkLink({ from, to, cost, bidirectional, id }).
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
linkOrFromX | number | | |||
fromY | number | <optional> | ||
toX | number | <optional> | ||
toY | number | <optional> | ||
options | Object | <optional> | {} |
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 }).
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
idOrConfig | string | | |||
x | number | <optional> | 0 | |
y | number | <optional> | 0 | |
width | number | <optional> | 1 | |
height | number | <optional> | 1 |
The registered obstacle record.
- Type:
- Object
addPortal(linkOrFromX, fromYopt, toXopt, toYopt, optionsopt) → {Object}
Alias for addChunkLink.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
linkOrFromX | number | | |||
fromY | number | <optional> | ||
toX | number | <optional> | ||
toY | number | <optional> | ||
options | Object | <optional> | {} |
- Type:
- Object
clearChunkLinks()
Clear all chunk links.
clearObstacles()
Remove all dynamic obstacles.
clone() → {NavigationGrid}
Create a clone of this NavigationGrid.
- 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).
| Name | Type | Attributes | Description | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
startArg | Object | | Starting point { x, y }, [x, y], or startX number | ||||||||||||||||||||||||||||||||||||||||||||||
goalArg | Object | | Goal point { x, y }, [x, y], or startY number | ||||||||||||||||||||||||||||||||||||||||||||||
optionsOrGoalX | Object | | <optional> | Options object, or goalX number | |||||||||||||||||||||||||||||||||||||||||||||
goalY | number | <optional> | goalY number if coordinates were passed numerically | |||||||||||||||||||||||||||||||||||||||||||||
options | Object | <optional> | Options object if coordinates were passed numerically Properties
|
Path result containing status, success, cost, and steps.
- Type:
- NavigationPath
getCell(x, y) → {Object|null}
Get cell properties at (x, y).
| Name | Type | Description |
|---|---|---|
x | number | |
y | number |
Cell state or null if out of bounds.
- Type:
- Object |
null
getChunkLinks(x, y) → {Array.<Object>}
Get outgoing chunk links from coordinate (x, y).
| Name | Type | Description |
|---|---|---|
x | number | |
y | number |
- Type:
- Array.<Object>
getCost(x, y) → {number}
Get traversal cost for a cell.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number |
Cost value (>= 1.0) or Infinity if out of bounds / unwalkable.
- Type:
- number
getElevation(x, y) → {number|null}
Get elevation level for a cell.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number |
Elevation level or null if out of bounds.
- Type:
- number |
null
getInvalidatedRoutes() → {Array.<string>}
Query which registered routes are currently invalid.
List of invalidated route IDs.
- Type:
- Array.<string>
getMaxClimbHeight() → {number}
Get maximum climb height difference.
- Type:
- number
getObstacle(id) → {Object|null}
Get obstacle by ID.
| Name | Type | Description |
|---|---|---|
id | string |
- Type:
- Object |
null
getObstacles() → {Array.<Object>}
Get all active obstacles.
- Type:
- Array.<Object>
getRegisteredRoute(id) → {Array|null}
Get a registered route by ID.
| Name | Type | Description |
|---|---|---|
id | string |
- Type:
- Array |
null
hasObstacle(id) → {boolean}
Check if obstacle exists by ID.
| Name | Type | Description |
|---|---|---|
id | string |
- Type:
- boolean
inBounds(x, y) → {boolean}
Check whether (x, y) is inside the grid bounds.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number |
- Type:
- boolean
invalidateRoutes() → {Array.<string>}
Explicitly invalidate routes and increment version.
IDs of registered routes that are invalid.
- Type:
- Array.<string>
isCellBlockedByObstacle(x, y) → {boolean}
Check if a specific cell is blocked by dynamic obstacles.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number |
- Type:
- boolean
isRouteValid(path, optionsopt) → {boolean}
Check if an existing path remains valid.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
path | Array | Array of { x, y } | ||
options | Object | <optional> | {} |
- Type:
- boolean
isWalkable(x, y, checkObstaclesopt) → {boolean}
Check if a cell is walkable and not blocked by dynamic obstacles.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
x | number | |||
y | number | |||
checkObstacles | boolean | <optional> | true | Whether dynamic obstacles block walkability |
- Type:
- boolean
offRouteInvalidated(callback)
Remove an invalidation listener.
| Name | Type | Description |
|---|---|---|
callback | function |
onRouteInvalidated(callback) → {function}
Subscribe to route invalidation events.
| Name | Type | Description |
|---|---|---|
callback | function | Event listener |
Unsubscribe function
- Type:
- function
registerRoute(id, path)
Register a route to monitor for invalidation when obstacles change.
| Name | Type | Description |
|---|---|---|
id | string | Identifier for the route |
path | Array | Array of { x, y } steps |
removeChunkLink(id) → {boolean}
Remove a chunk link by ID.
| Name | Type | Description |
|---|---|---|
id | string |
True if removed.
- Type:
- boolean
removeObstacle(id) → {boolean}
Remove a dynamic obstacle by ID.
| Name | Type | Description |
|---|---|---|
id | string |
True if removed.
- Type:
- boolean
setCell(x, y, propsopt) → {boolean}
Set multiple cell properties at once.
| Name | Type | Attributes | Default | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
x | number | |||||||||||||||||||
y | number | |||||||||||||||||||
props | Object | <optional> | {} | Properties
|
True if in bounds.
- Type:
- boolean
setCellMaterial(x, y, materialId, stateopt, registryopt) → {boolean}
Set cell properties based on material definitions from SIM-01.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
x | number | |||
y | number | |||
materialId | string | Material ID (e.g., 'water', 'grass', 'wood') | ||
state | string | <optional> | 'dry' | Material state (e.g., 'dry', 'wet', 'frozen') |
registry | Object | <optional> | null | Optional MaterialRegistry instance |
True if set.
- Type:
- boolean
setCost(x, y, cost) → {boolean}
Set traversal cost for a cell.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
cost | number | Movement cost (must be >= 1.0) |
True if updated.
- Type:
- boolean
setElevation(x, y, elevation) → {boolean}
Set elevation level for a cell.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
elevation | number |
True if updated.
- Type:
- boolean
setMaxClimbHeight(height)
Set maximum climb height difference between adjacent cells.
| Name | Type | Description |
|---|---|---|
height | number |
setWalkable(x, y, walkable) → {boolean}
Set walkability flag for a cell.
| Name | Type | Description |
|---|---|---|
x | number | |
y | number | |
walkable | boolean |
True if updated.
- Type:
- boolean
unregisterRoute(id) → {boolean}
Unregister a monitored route.
| Name | Type | Description |
|---|---|---|
id | string |
True if removed.
- Type:
- boolean
validateRoute(path, optionsopt) → {Object}
Validate whether an existing path remains walkable and unbroken.
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
path | Array | Sequence of { x, y } step objects | ||
options | Object | <optional> | {} | Validation options |
Validation report { valid, blockedIndex, blockedCell, reason }
- Type:
- Object