Skip to content

VDSim v0.2 — roadmap / plan

Status: v0.2.4 GUI + v0.3 catalog shipped (2026-06-06). WS3–WS4 + catalog cutover complete. WS1 drivetrain inertia + LuGre tire implemented (opt-in / defaults preserve legacy behaviour). Engine torque–RPM map still open.

Baseline (what v0.1.0 shipped)

Validated dynamics core (Lk/Ld1/Ld2/Ld3 + Pacejka MF96 + Ld4 hardpoint), web viewer (pure subscriber), VDS1 UDP co-sim runtime, Python API + batch, FMI 2.0, ISO maneuvers, sensors, cross-platform (Linux/Windows), 191/191 ctest. Low-speed handling is a pragmatic blend (kinematic + brake-hold + lambda fade); the tire is empirical MF96; the drivetrain has no engine inertia (see Known gaps).

v0.2 theme — the composable vehicle

v0.1 = one validated monolithic vehicle. v0.2 = build a vehicle from component models, each with its own physics + editor + import path, and author/run multi-vehicle scenarios from a redesigned UI. Two halves of one idea: each subsystem gets (a) a proper model and (b) a workshop to edit/import it; the scene UI assembles vehicles (chassis + parts) and wires up I/O.

Workstreams

WS Name What Depends on
WS1 Subsystem physics models drivetrain, tire (LuGre), brake, steering, controller/actuator deadtime, suspension levels core (exists)
WS2 Component workshops per-subsystem editor UIs + import (torque-RPM/efficiency map, TIR, damper curves) WS1
WS3 Scene authoring UI redesign 3-tab config, multi-vehicle tree, data-comms, mini-map, sim controls, save/load WS4 (parts), WS1 (configs)
WS4 Vehicle assembly vehicle = chassis + parts; part registry; YAML serialization WS1 interfaces

WS1 — subsystem physics models

Module v0.1 state v0.2 target Design doc Notes
Drivetrain flat throttle*max_torque*final_drive, ideal open diff, no engine inertia done: engine_rotational_inertia + carrier coupling; torque–RPM curve open V0.2_DRIVETRAIN.md Default I_engine=0.25. Set 0 for legacy. Re-baseline ISO/accel when updating.
Tire MF96 empirical + low-speed blend done (opt-in): LuGre bristle + MF96 g(); default off keeps blend V0.2_TIRE_LUGRE.md lugre.enabled: true skips blend/hold. User guide: docs/CATALOG_AND_PHYSICS.md.
Brake flat pedal*max_brake_torque booster -> line pressure -> pad mu -> caliper torque (per wheel); fade optional (new) Pairs with the brake workshop.
Steering direct steer_angle_wheel column -> MDPS assist -> steering ratio -> rack travel -> road-wheel angle (Ackermann from rack) (new) rack_torque already in STATE; close the loop.
Controller/actuator first-order actuator lag per-channel deadtime + lag for steer/accel/brake (extend) Deadtime is a common SIL/HIL need.
Suspension Ld4 hardpoint + linear rates level-based spring/damper (linear/progressive), per-corner (extend Ld4) Pairs with suspension workshop.

WS2 — component workshops (editors + import)

Each WS1 module gets an editor in the GUI (extends the existing builder/ branch):

  • Engine/motor workshop: torque-RPM + efficiency map editor; import maps.
  • Tire workshop: Pacejka .tir import (decide MF5.2/6.⅙.2) + a sample library.
  • Suspension workshop: spring/damper curves, level presets.
  • Brake / steering / controller workshops: parameter editors for the WS1 models.

WS3 — scene authoring UI redesign

  • Tab 1 — vehicle + sensor config: left vehicle list; per-vehicle tree (vehicle -> sensors); multi-vehicle; "ground/infra" sensor class (sensors not attached to a vehicle).
  • Tab 2 — environment config: map, waypoints.
  • Tab 3 — simulator config: UDP comms ports, rates.
  • Data-comms panel: UDP sender/receiver boxes with toggles, templates, source selection (builds on the existing /api/io + telemetry targets).
  • Mini-map (bottom-left); sim controls (top-left: play/stop/reset + realtime multiplier slider); save/load full sim config.

Open: keep vanilla HTML+three.js or adopt a framework? The redesign is large enough to justify deciding this up front.

WS4 — vehicle assembly

Vehicle = chassis + parts (engine, diff, tires, suspension, brakes, steering, controller, sensors). Part registry + YAML serialization; the WS3 tree renders this tree; the WS1 models are the part implementations. This is the data model that ties WS1/WS2/WS3 together.

Dependencies

WS1 (models) ──► WS2 (workshops)
   │                 │
   └──► WS4 (parts) ─┴──► WS3 (scene UI)

Milestones (current order — updated 2026-06-05)

  • WS1 subsystem skeletons — DONE (#159-162 + deadtime): interfaces, default modules, L2 routing (+ deadtime), per-wheel ARB. 191 green (WS1 L3 → v0.3). (Engine torque-RPM curve + inertia / LuGre tire = v0.3.)
  • WS2 component workshops — DONE (app.html edit modal; engine stub → v0.3).
  • WS4 vehicle assembly — DONE (fleet parts + registry + L3 kinematics attach).
  • WS3 scene authoring UI — DONE (3-tab setup, data-comms, save/load).
  • Multi-vehicle runtime (#157/#158) — DONE. V0.2_MULTIVEHICLE.md.
  • Stunt physics (jump → vertical loop) — deferred to v0.4.0 single release; see V0.4_PLAN.md (not split across v0.5/v0.6).

Rationale: physics (WS1) shipped first as the differentiator; workshops (WS2) make the modules editable now; the multi-vehicle runtime lands last so the scene UI / parts model it touches are settled first.

Decisions log

  • 2026-06-05 — Multi-vehicle runtime = one process, N vehicles (shared world, one clock). Rejected N independent plant processes: in-engine collision needs all bodies in one frame at the same instant with contact forces fed back inside the integration step, which async free-running UDP processes can't do. V2V collision physics is deferred to a future TODO (see V0.2_MULTIVEHICLE.md); the runtime is built collision-ready now. I/O moves to VDS1 v4 with a vehicle_id field (one socket, demux by id).

Open questions / decisions needed

  1. Gearbox: model a multi-ratio transmission in v0.2, or just final drive + engine inertia + torque curve?
  2. .tir import: which MF version(s) to support first.
  3. UI framework decision for WS3 (vanilla vs framework).
  4. Re-baselining: WS1 changes will shift the ISO/accel benchmark numbers — plan a single re-validation pass per milestone, not per change.

Known gaps carried from v0.1 (the "why" behind WS1)

  • Drivetrain inertia missing → exaggerated open-diff inner-wheel spin (V0.2_DRIVETRAIN.md).
  • Tire is empirical MF96 + low-speed blend, not a unified physical model (V0.2_TIRE_LUGRE.md).
  • Brake/steering are idealized (flat torque / direct wheel angle).
  • True static standstill hold is approximated by a viscous brake-hold damper (LOW_SPEED_HANDLING.md), not real stiction (the LuGre tire would supersede it).
  • V0.2_DRIVETRAIN.md — engine inertia + coupled diff (detailed).
  • V0.2_TIRE_LUGRE.md — unified brush/LuGre tire (detailed).
  • LOW_SPEED_HANDLING.md — v0.1 low-speed approach (what v0.2 tire supersedes).
  • RUNTIME_ARCH.md — the 3-branch runtime the UI/co-sim build on.