8.4 KiB

Raw Blame History

ADR 0017: Provider-neutral simulation and Unreal evaluation

Status

Accepted for architecture on 2026-07-25. The provider contract is implemented on the Polygon branch. Gazebo remains the accepted regression baseline. No Unreal integration, Unreal runtime profile or choice between native Unreal, CARLA and Project AirSim is accepted by this decision.

Context

The first Polygon vertical proved that Mission Core can own a virtual Ackermann run, display canonical ENU/FLU state in React, persist evidence and deliver bounded virtual-only rover commands through PX4. That proof used one concrete stack: Gazebo Harmonic, PX4 SITL, ROS 2 and Micro XRCE-DDS.

Treating that stack as the product architecture would make later work expensive:

a realistic vehicle, road surface, terrain and sensor model may be easier to build and inspect in Unreal;
reconstructed Gaussian scenes are primarily visual evidence and do not by themselves supply collision, friction, road or navigation geometry;
native Unreal, CARLA and Project AirSim have different vehicle, sensor, controller, platform and lifecycle assumptions;
a browser cannot and should not execute the full physics/autopilot stack;
replacing Gazebo must not replace Mission Core run identity, authority, evidence, UI or evaluator contracts.

The choice is therefore not “Gazebo or Unreal for the whole product.” It is which worker-side provider profile is appropriate for each qualification case.

Decision

Mission Core remains simulation-provider neutral. A worker publishes an exact missioncore.simulation-provider-profile/v1 before it may be used by the browser or gateway.
A provider profile declares logical providers, roles, capabilities, authoritative simulation clock, supported canonical control profiles and the fixed map_enu/base_link_flu boundary.
Provider roles are world, physics, state, controller, transport, sensor and traffic. One process may implement several roles; several processes may compose one profile.
Component pins and provider roles remain separate: component pins prove exact software provenance, while provider descriptors explain runtime responsibility and interoperability.
Worker status v2 exposes the configured provider profile separately from currently active process IDs. VehicleState names its source provider. Command acceptance v2 names the delivering controller provider and canonical control profile.
The browser consumes canonical state and evidence. Unreal, Gazebo, PX4, ROS 2 and their native windows remain outside React and run on registered workers.
Gazebo/PX4 remains the frozen, comparatively cheap deterministic regression profile until another profile passes the same lifecycle, clock, command, safety and evidence gates.
Unreal is evaluated as a high-fidelity provider family. Native Unreal, CARLA and Project AirSim are separate candidates and are not interchangeable labels:
- native Unreal maximizes project control but requires Mission Core-owned vehicle, sensor, clock and bridge work;
- CARLA is evaluated when road/traffic simulation and its supported vehicle model fit the rover case;
- Project AirSim is evaluated only against its current supported vehicle, PX4, ROS 2, platform and maintenance constraints.
A Gaussian scene may provide appearance and sensor-rendering context. Every qualification world still needs separately versioned physical collision meshes, road/drivable surfaces, materials/friction, semantic regions, spawn/goal definitions and evaluator truth.
Unreal does not block S1 completion or the S2 Gazebo/Nav2 baseline. It becomes most valuable in S3 virtual-sensor/perception work and S5 high-fidelity/digital-twin work. An earlier bounded adapter spike is allowed because it reduces architectural risk.
PX4 remains a replaceable controller provider. An Unreal profile may use PX4 through an admitted external-simulator boundary or may use a different virtual controller, but each choice creates a distinct profile and cannot inherit the other profile's evidence.
No real actuator authority is introduced. All current profiles remain virtual-only.

Fidelity ladder

Level	Purpose	Initial provider
L0 contract tests	Fast lifecycle, schema and safety regression	In-process fakes
L1 dynamics regression	Cheap repeated control/navigation qualification	Gazebo + PX4 SITL
L2 sensor/scene fidelity	Camera/LiDAR/perception and difficult visual worlds	Unreal candidate
L3 hardware/control integration	Controller-in-loop and HIL	Separate gated profile
L4 physical evidence	Shadow and later controlled field qualification	Vehicle Edge Agent

A higher level does not replace lower-level regression. Evidence is comparable only when scenario, provider profile, metric profile and reproducibility tier allow it.

Unreal evaluation gates

U0 — selection spike

For native Unreal, CARLA and Project AirSim, record:

supported rover/Ackermann dynamics and controllable wheel/suspension model;
fixed-step clock, pause/step/reset and headless execution;
external command/state bridge and PX4 compatibility;
camera, depth, LiDAR, IMU, GNSS and ground-truth availability;
collision/contact and semantic truth;
Linux/Windows worker placement, GPU/VRAM/RAM and startup time;
automation, packaging, licensing, upstream activity and version pinning;
import path for existing Unreal assets and Gaussian reconstructions.

Exit: one candidate or native implementation is selected for a disposable U1 adapter. “Looks better” is not an exit criterion.

U1 — canonical adapter proof

publish one provider profile and authoritative fixed-step clock;
launch/reset/stop through the Simulation Orchestrator;
map a stock Ackermann pose to VehicleState;
accept rover-speed-steering/v1 under the existing TTL/watchdog boundary;
prove straight, turn, reverse, command expiry and clean zero-residue stop;
retain exact world, provider, host and resource evidence on D.

Exit: the existing React panel and run archive work without Unreal-specific branches in Mission Core.

U2 — physical and sensor world

add reviewed collision/drivable geometry alongside visual assets/Gaussians;
pin vehicle mass, inertia, wheelbase, steering limits, suspension, friction and sensor extrinsics;
publish evaluator-only truth separately from planner/perception inputs;
validate camera/LiDAR timing, noise and frame conversion.

Exit: sensor/perception experiments are repeatable and do not consume hidden ground truth.

U3 — comparative qualification

run equivalent scenarios through the Gazebo and Unreal profiles;
report control, collision, latency, resource and reproducibility differences;
declare which conclusions are portable across providers and which are not.

Exit: Unreal supplies measurable product value beyond rendering quality.

Immediate work policy

Continue work that remains valuable across providers:

provider-neutral orchestration and capability admission;
run, event, command, artifact and report contracts;
TTL, heartbeat, watchdog, failsafe and authority gates;
canonical frames, clocks, telemetry and evaluator metrics;
scenario/profile registry and browser presentation of canonical state;
Gazebo regression cases needed to validate those boundaries.

Defer until U0 selects a direction:

a polished custom Gazebo vehicle;
large Gazebo world/model libraries;
simulator-specific UI controls;
a production Unreal bridge;
Gaussian collision or road generation assumptions;
provider-specific perception contracts.

Consequences

Existing Polygon work is retained as the control plane and regression tier.
Unreal experimentation can proceed independently without forking the product model or exposing a native engine to the browser.
The first Unreal work is a measured adapter spike, not a platform migration.
More explicit provider metadata and compatibility testing is required.
Two physics providers increase qualification cost, but allow fast regression and high-fidelity experiments to coexist.

8.4 KiB Raw Blame History