Design

Authority And Boundaries

The native compiler remains the only road authority. The existing traffic-signal runtime remains the only signal authority. The new feature adds a route/simulation layer beside those artifacts; it does not alter signal geometry, phase grouping, or Blender static assets.

native-road/compiled.json + native-road/layers/*
  -> native route compiler
  -> _preview/<area>-traffic-simulation.json
  -> Cesium preview runtime

package/runtime/traffic-signals.json
  -> signal phase clock + stop events

The descriptor is intentionally package-adjacent, not embedded in the GLB. A consumer can copy the package and descriptor to another platform and reproduce the simulation without running Node.

Descriptor Contract

Schema: native-preview-traffic-simulation/v1.

Required top-level fields:

areaId, coordinateSystem (WGS84 route coordinates, ENU model placement), generatedAt
source with relative artifact references and SHA-256 records
settings with speed, acceleration, deceleration, reaction time, vehicle length, and minimum gap
routes[] with ordered WGS84 coordinates, cumulative distances, connector/maneuver IDs, and stops[]
signals[] copied by stable signal_uid from the runtime contract, including phase group and stop-line association; no regenerated pose fields
migration describing schema version, coordinate conversion, update-loop expectations, and compatibility notes

The descriptor is deterministic for the same OSM, overrides, native compiler version, and settings.

Route Construction

Use native directional roads and published connector geometry. Build a small number of deterministic closed demonstration routes that cross real connectors and retain lane/road IDs. Route generation must reject routes with missing geometry or disabled connectors and write structured diagnostics. Native stop lines are matched by road_id/lane_id where available, with a bounded geometric fallback recorded in the stop record. No fixed-width or legacy polygon fallback is allowed.

Browser Simulation

Keep the existing signal phase functions and signalData payload. Replace the current per-vehicle independent distance advance with a shared simulation state:

each vehicle has route distance, speed, desired speed, status, and active stop reason;
signal stop constraints are evaluated before the native stop line for red/yellow phases;
leader constraints are evaluated on the same route and wrap around the loop;
acceleration/deceleration clamps advance toward the minimum of desired speed, signal limit, and leader-safe speed;
vehicle position and orientation remain Cesium callback properties, with no per-frame allocation of heavyweight Cesium objects;
incident-card behavior remains local to each vehicle and must not mutate the descriptor or package.

Diagnostics expose route count, signal count, stopped vehicles, and queue length in the existing preview diagnostics panel.

Migration And Rollback

Document the descriptor, runtime signal schema, coordinate conversion, and a reference update loop in docs/native-preview-traffic-simulation.md. Include a JSON example and a consumer checklist. Legacy preview route files remain readable only through the existing legacy provider path; native generation must not depend on them. Removing the new descriptor restores the existing no-cruise native preview.

3.4 KiB Raw Blame History