Syncromesh/Navigation — SyncroMesh Documentation

Provides local path planning for moving entities. The runtime samples nearby physics obstacles, attempts direct movement first, then falls back to a tangent/visibility-graph solve. Use generateWaypoints when you only need points to enqueue, or diagnoseWaypoints when you need solver telemetry for debugging and tooling.

Import #

Functions #

generateWaypoints

Returns ordered waypoint points from from toward to.

The result can be direct, solved, or partial depending on obstacle layout and configured limits.
Returns an empty array when no path segment can be produced.

generateWaypoints(from: Point, to: Point, options?: NavigationQueryOptions): Promise<Point[]>

diagnoseWaypoints

Runs the same solver and returns status, reason, costs, stage breakdown, and optional debug geometry.

status and reason are stable enum-like keys intended for tests and telemetry.
debug arrays are always present; they are empty unless the solver emits corresponding geometry.

diagnoseWaypoints(from: Point, to: Point, options?: NavigationQueryOptions): Promise<NavigationDiagnostics>

Query options #

NavigationQueryOptions

Optional controls for obstacle inflation, graph size caps, and diagnostics verbosity.

agentRadius number optional — Agent collision radius. Default 0.55.
formationRadius number optional — Extra formation spacing radius added to clearance. Default 0.
safetyMargin number optional — Additional inflation margin. Default 0.05.
maxDetourDistance number optional — Maximum allowed routed distance extension over direct distance. Default 64.
maxObstacleCount number optional — Obstacle cap for one solve. Minimum 1. Default 64.
maxCandidates number optional — Candidate point cap. Alias for maxCandidateCount. Minimum 2. Default 128.
maxCandidateCount number optional — Equivalent to maxCandidates.
maxEdges number optional — Visibility edge cap. Alias for maxEdgeCount. Minimum 1. Default 512.
maxEdgeCount number optional — Equivalent to maxEdges.
smoothingPasses number optional — Line-of-sight smoothing passes after A*. Default 2.
includeDebugGeometry boolean optional — Includes inflated obstacle proxies, candidate points, and edge sets in diagnostics. Default false.
includeRejectedEdges boolean optional — When debug geometry is enabled, also records rejected visibility edges. Default false.
ignoreEntities number[] optional — Entity ids to exclude from obstacle discovery for this query.
ignoreEntityIds number[] optional — Alias for ignoreEntities.
ignoreWeldedAttachedEntities boolean optional — When true, welded bodies attached to any ignored entity are excluded too. Default true.

Diagnostics shape #

NavigationDiagnostics

Full result object returned by diagnoseWaypoints.

status string — One of the status keys listed below.
reason string — Stable reason key for solved/partial/failed outcomes.
waypoints Point[] — Ordered path points to enqueue.
query NavigationQuerySummary — Resolved query values used by the solver.
cost NavigationCost — Performance and graph-size counters for the solve.
stages NavigationStage[] — Stage-by-stage solve summary (directSweep, cluster, visibilityGraph, astar, smoothing).
debug NavigationDebug — Debug geometry payload (arrays may be empty).

NavigationQuerySummary

Effective query values after option parsing.

from Point — Start point.
to Point — Target point.
agentRadius number — Agent radius used for this solve.
formationRadius number — Formation radius used for this solve.
clearance number — Computed obstacle inflation (agentRadius + formationRadius + safetyMargin).

NavigationCost

Solve telemetry counters.

elapsedMicros number — Solver wall-clock duration in microseconds.
obstaclesConsidered number — Obstacle proxies considered in this query region.
candidatesGenerated number — Candidate graph nodes generated (excluding start/target).
visibilityEdgesTested number — Visibility segment checks performed.
graphNodes number — Total graph nodes in the solve.
graphEdges number — Visible graph edges accepted.

NavigationStage

One solver stage entry.

name string — Stage name.
status string — Stage-local status key.
blockerCount number optional — Blocking obstacle count for sweep stages.
clusterCount number optional — Obstacle cluster size.
nodeCount number optional — Graph node count.
edgeCount number optional — Graph edge count.
visitedNodes number optional — A* visited node count.
removedWaypoints number optional — Smoothing pass removals.

NavigationDebug

Optional geometry emitted for diagnostics.

directSegment Point[] — Input direct segment endpoints (from, to).
inflatedObstacles NavigationDebugObstacle[] — Inflated obstacle proxies used by the solve.
candidatePoints Point[] — Graph candidate points after filtering.
chosenEdges Array<[Point, Point]> — Visible edges accepted into the graph.
rejectedEdges Array<[Point, Point]> — Visibility edges rejected (only when includeRejectedEdges is true).

Status keys #

Key	Meaning
`direct`	Direct movement segment is clear; no detour graph required.
`solved`	Visibility-graph solve reached the target.
`partial`	Only partial progress was produced (for example adjusted target or clipped detour).
`failed`	No movement segment could be produced by the solver.
`limit_exceeded`	Solve aborted because configured caps were exceeded.

Reason keys #

Key	Meaning
`none`	No failure condition (successful direct/solved path).
`start_blocked`	Start point remained blocked after escape attempts.
`target_blocked`	Target point was blocked and required adjustment, or remained blocked.
`direct_blocked`	Direct segment blocked and no better reason chosen.
`no_visible_edges`	Visibility graph had no viable edges between start and target neighborhoods.
`astar_no_path`	Graph built, but A* could not connect to target (or returned partial fallback progress).
`max_obstacles_exceeded`	Obstacle cap exceeded.
`max_candidates_exceeded`	Candidate point cap exceeded.
`max_edges_exceeded`	Edge test/edge count cap exceeded.
`max_detour_exceeded`	Route exceeded allowed detour budget and was clipped to partial.

Example #

import * as Navigation from 'Syncromesh/Navigation';
import * as Entity from 'Syncromesh/Entity';

const from = await Entity.getPosition(unitId);
const to = { x: 20, y: -8 };

const diagnostics = await Navigation.diagnoseWaypoints(from, to, {
    agentRadius: 0.55,
    maxDetourDistance: 24,
    maxCandidates: 160,
    maxEdges: 1400,
    includeDebugGeometry: true
});

for (const waypoint of diagnostics.waypoints)
{
    await Entity.enqueueWaypoint(unitId, waypoint);
}

// Telemetry keys are stable for tooling.
// diagnostics.status: direct | solved | partial | failed | limit_exceeded
// diagnostics.reason: none | start_blocked | target_blocked | ...

← Syncromesh/Network