71 lines
3.4 KiB
Markdown
71 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
```text
|
|
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.
|