@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/skills/helix-vehicles/references/physics-from-specs.md

@@ -0,0 +1,463 @@
+# Physics from real-world specs
+
+Physics is **stated, not invented**. Every number is `Sourced`: either
+`{ value, unit, sources: [citationId] }` or `{ value, unit, derivedFrom: "<arithmetic>" }`. Only
+two knobs are ours to tune toward the targets: `grip.peak` and `suspension.*`. Everything else
+belongs to the real car. If 0–100 is off and the engine is cited, the cause is grip, gearing or
+launch behaviour. It is not the engine.
+
+## 1. Research (before any mesh work)
+
+Collect citations first. Give each one an `id`, a `kind` and a title that quotes the numbers it
+supports.
+
+| Kind | Use for |
+| --- | --- |
+| `manufacturer` | Press kit or technical data: power and torque with their rpm, mass (state DIN or EU and whether it includes a driver), gear ratios, final drive, Cd, tyre sizes, dimensions, top speed, and the manufacturer's 0–100. |
+| `instrumented-test` | Magazine road tests: 0–60, quarter mile, 60–0, skidpad g. **Collect several and take the middle (the median); record the spread in `note`.** Never drop the test you like least as an "outlier" unless you can say why it is wrong. |
+| `reference-database` | Wikipedia, spec databases: dimensions and track widths. Cross-check them against the manufacturer. |
+| `measured-fixture` | Values measured off your own GLB: wheelbase, track, wheel radius, ride height. |
+| `engineering-literature` | Ride frequency, damping ratio, roll gradient and tyre conventions. |
+
+**Torque curve.** You need at least 10 points from idle to the limiter, in strictly ascending rpm,
+and the curve must reach the limiter. Sources, best first:
+
+1. a published dyno chart from the manufacturer or a magazine;
+2. the shape of a known curve for the same engine family, scaled to the cited peak torque;
+3. a derived curve built from cited peak power and peak torque, with the derivation written in
+   `derivedFrom`.
+
+Peak power must agree with torque × rpm: `P[kW] = T[N·m] × rpm / 9549`.
+
+**A fictional or concept car** gets a named real analogue for each subsystem, with
+`derivedFrom: "analogue: <real car> <field>, scaled by <reason>"`. Never write a bare number.
+
+**Never take physics from a game mod as truth.** One mod's engine was a renamed template making
+360 N·m and 238 kW, stronger than any real 993. Use mod data only for *relative* add-on deltas.
+
+## 2. Deriving the fields
+
+All units are SI.
+
+| Field | How |
+| --- | --- |
+| `chassis.mass` | The configuration's own published kerb mass. Not an estimate. |
+| `weightDistributionFront` | Published. For example, the 993 is 0.39. |
+| `centreOfMassHeight` | Published if available, else derived as `≈ 0.35–0.40 × height` for road cars (lower for supercars, as the class presets assume). Write the derivation. |
+| `wheelbase`, `trackFront`, `trackRear`, `length`, `width`, `height` | Published, then cross-checked against your mesh. The runtime measures wheel positions from the mesh, so a disagreement means your mesh is wrong. |
+| `wheelRadius` | The **measured rolling radius of the drawn tyre**. Compute the nominal radius from the tyre size: `(rim_in × 25.4 / 2 + width_mm × aspect/100) / 1000`; a 205/55R16 is 0.316. Then use what the mesh actually draws. Visible geometry wins. A car with different front and rear tyres: see "Staggered tyres" below. |
+| `staticRideHeight` | Anchor to wheel centre, in m. **Set it so that `wheelRadius + staticRideHeight = groundToBodyOrigin`.** |
+| `groundToBodyOrigin` | The body origin's height above the ground at rest. It is locked after the first publish. |
+| `engine.torqueCurve`, `idleRpm`, `limiterRpm` | Cited, as described above. |
+| `engine.drivetrainEfficiency` | 0.85–0.91 for a manual RWD car. Label it as an assumption if it is not published. This, and aero drag, is where real-world losses live (see "Torque: target the declared crank figures"). |
+| `engine.coastTorque` | Engine braking. About 10–15 % of peak torque is typical; label it derived. |
+| `gearbox.ratios`, `reverseRatio` (negative), `finalDrive` | Published. |
+| `shiftTime` | 0.2–0.3 s manual, 0.1–0.15 s DCT. |
+| `autoUpRpm`, `autoDownRpm` | Just below the limiter, and roughly 40 % of the limiter. |
+| `driveBiasFront` | The nominal **front share of drive torque at zero slip**: 0 RWD, 1 FWD. An AWD car is **strictly between 0 and 1** and equal to `centre.torqueSplit` (see "All-wheel drive"); exactly 0 or 1 flags an axle's wheels unpowered, whatever the centre diff says. |
+| `aero.dragCoefficient` | Published Cd. If it is unpublished, derive it from the measured top speed: `Cd = 2·P_wheel / (ρ v³ A)`, with ρ = 1.225, `P_wheel = kW × 1000 × efficiency` and v in m/s. |
+| `aero.frontalArea` | Published, else `0.80 × width × height`. |
+| `aero.downforceCoefficient` | 0 for a road car without aero. A `mul` add-on on 0 does nothing. |
+| `linearDamping` | **0 when aero is modelled.** A value of 0.02 removed 65 km/h of top speed. |
+| `brakes.maxTorque` | Whole car, in N·m. It must at least reach the tyre limit, `T ≥ m·g·μ·r`; real cars carry headroom over that (the 993 used about 1.7×). With enough torque, stopping distance is tyre-limited. |
+| `brakes.biasFront` | Tracks the static weight plus the transfer, typically 0.6–0.7. |
+| `grip.peak` | At least the average braking g implied by the published 60–0 distance. `a = v² / 2d` gives 0.97 g for 36 m from 26.8 m/s, so pick ≥ 0.98; the 993 used 1.05. Pick `sliding` a little below peak. |
+| `grip.lateralMultiplier` | About 0.9. The derived lateral g is about 0.85 × longitudinal. Check it against the published skidpad. |
+| `suspension.rideHzFront` / `rideHzRear` | 1.2–1.6 Hz for road cars, 1.8–2.5 Hz for track cars. Rear about 10 % above front (flat ride). |
+| `suspension.dampingRatio` | 0.2–0.3 for a soft road car, 0.4–0.5 for a sports car, 0.65–0.7 for a race car. |
+| `bumpScale`, `reboundScale` | For example 0.9 and 1.1: rebound firmer than bump. |
+| `bumpTravel` | Measured travel to the bump stop, about 0.07 m on a sports car. |
+| `antiRollBarFront` / `Rear` | **Size by roll gradient, not by feel.** A road car runs 4–5° per g, and the bars add about 1/5 of the roll stiffness. The 993 used 14,000 / 9,000 N/m; an earlier 38,000 / 28,000 N/m gave a racing car's 2.3° per g. |
+| `steering.roadWheelLockDeg` | Published, else about 34°. Use a `rackTime` of about 0.14 s. |
+| `inertiaMultiplier` | `[1, 1.1, 1.3]`. This is ours, not the car's: say so in `note`. |
+
+### `simulation.land` (the v2 solver; required for manual gears and a real drivetrain)
+
+| Part | How |
+| --- | --- |
+| `driveline.engine` | `torqueCurve: { points }` is the same as the physics curve. Then: `inertia` 0.1–0.2 kg·m², `friction` and `dynamicFriction` small, `engineBrakeTorque` equal to `coastTorque`, `burnEfficiency` as a load LUT, `drivetrainEfficiency`, `revLimiterType` soft or hard. Set `boostTorqueCoef: 0` for NA, or when the curve already includes boost. |
+| `driveline.clutch` | `capacity` ≈ 1.6 × peak torque. Typical values: `inertia` ~0.1, `freePlay` 0.2, launch rpm. |
+| `driveline.gearbox` | `kind` is `manual` or `sequential` for manual mode. Also `ratios`, `reverseRatio`, `shiftDelay` and `auto { enabled, upRpm, downRpm }`. |
+| Differentials | `rear` for RWD, `front` for FWD, both plus `centre` for AWD. **`gearRatio` on the driven diff is the final drive.** Types: `open`, `locked`, `viscous`, `lsd` (with `lsdPreload`, `lsdLockCoef`, `lsdRevLockCoef`). For AWD, read "All-wheel drive" below. |
+| `abs` | `{ targetSlip: 0.12, releaseRate: 12, applyRate: 5, minSpeed: 2.5 }` if the car has ABS. If it is absent, wheels lock. |
+| `tractionControl` | Optional; absent means none. `{ targetSlip: 0.2, cutRate: 25, restoreRate: 3, minTorque: 0.45, upshiftTorqueRamp: true }` if the car had traction control, or as a declared playability aid. See "Traction control" below. |
+| `tyreByAxle[]` | Front and rear tyre models, one per axle: `radius` (that axle's measured rolling radius), `angularInertia`, `alphaPeakRad`, `muLut { fz[], mu[], slideRatio }`, `loadSensitivity`, `sigmaX/Y`, `cxMult`, `dxOverDy`, `sFall`, `camberGain` and `rollingResistance`. Start from the reference package's tyre and scale `muLut.mu` to your grip, or use the BeamNG importer's sampled LUT. |
+| `turbine` | Turbo cars only: `pressureMap`, `wastegateStartBar` and `wastegateLimitBar`, `displacementM3`, and so on. A turbo add-on does nothing on a v2 car without one. |
+
+The fully worked example is the `simulation` block in the `reference-package` reference. That
+car is naturally aspirated.
+
+### All-wheel drive
+
+The v2 solver reads the split from `simulation.land.driveline`: `front` and `rear` axle diffs (their `gearRatio` is the final
+drive; an axle with no diff is not driven) and a `centre` diff. Every diff is `{ type, torqueSplit, gearRatio, friction,
+dynamicFriction, lockTorque, viscousCoef, viscousTorque, lsdPreload, lsdLockCoef, lsdRevLockCoef }`.
+
+- **`centre.torqueSplit` is the FRONT share of drive torque before any locking.** `physics.driveBiasFront` is the same number
+  and must equal it, strictly between 0 and 1. (The solver takes the split from the centre diff; `driveBiasFront` decides which
+  wheels are powered, and an add-on that moves it scales `torqueSplit`.)
+- **Locking.** The centre sends `front = split·Q + lock`, `rear = (1−split)·Q − lock`, with `lock = capacity · tanh(Δω / 0.5 rad/s)` and
+  Δω = front − rear axle speed. The lock **moves torque to the slower axle**: a spinning rear axle pulls torque forward, a spinning
+  front axle pushes it back, and a corner (front faster) leans rearward. `Q` is the torque entering the centre diff in N·m.
+- **Capacity by type:** `open` 0; `locked` `lockTorque` (a very stiff coupling, not a rigid weld); `viscous`
+  `min(viscousCoef·|Δω|, viscousTorque)`; `lsd` `lsdPreload + lsdLockCoef·|Q|` on power and `lsdPreload + lsdRevLockCoef·|Q|` on coast.
+  Power and coast are two numbers on purpose.
+- **Maximum share to the other axle** at full lock ≈ `torqueSplit + lsdLockCoef + lsdPreload/Q` (rear-biased car, rear slipping).
+  Set the coefficients so that equals the maker's stated maximum, and keep it below 1.
+
+| Kind (e.g.) | `centre.type` | `torqueSplit` = `driveBiasFront` | Lock fields |
+| --- | --- | --- | --- |
+| Clutch-pack, slip-metered, rear-biased (ATTESA-, xDrive-type) | `lsd` | The maker's **zero-slip** front share: `0.05` for "0:100", about `0.4` for "40:60". Never the average of a launch. | `lsdPreload` 30–80 N·m; `lsdLockCoef` = (maximum front share − `torqueSplit`), e.g. `0.40` for a 50 % maximum from `0.05`, less the preload term; `lsdRevLockCoef` 0.05–0.15 (the pack opens on coast and under ABS). |
+| Clutch-pack, front-biased (Haldex-type) | `lsd` | `0.9`–`0.95` (almost all front at rest; the lock sends torque back). | Same fields; the rear's maximum share ≈ `(1 − torqueSplit) + lsdLockCoef`. |
+| Permanent torque-biasing (Torsen-type) | `lsd` | The design split (`0.4` for 40:60). | `lsdPreload` 0–20; `lsdLockCoef` so that `(slow share + coef)/(fast share − coef)` = the torque-bias ratio (2.5–4); `lsdRevLockCoef` ≈ `lsdLockCoef`. |
+| Permanent viscous | `viscous` | The design split (`0.35`–`0.5`). | `viscousCoef` 8–30 N·m per rad/s; `viscousTorque` 600–800 N·m. No lock at steady cruise. |
+| Part-time 4WD (engaged) | `locked` | `0.5`, or the fixed-gearing split. | `lockTorque` 10,000. Author the engaged mode only. |
+| Open centre | `open` | The split. | none (no transfer: one slipping axle stays slipping). |
+| RWD / FWD | no `centre`; one axle diff | `0` / `1` | — |
+
+A worked check on one 1.6 t turbo scratch car (full-throttle launch, front share of drive at 0.25 / 0.75 / 1.75 / 3.75 s, from the
+instrument; `driveBiasFront` held at 0.30, which the solver reads only as powered / unpowered): clutch-pack `lsd` split 0.02, preload 40, coef 0.40, coast 0.10 → 52 / 35 / 29 / 31 %; Torsen-like `lsd` 0.40, coef 0.25 →
+42 / 35 / 42 / 45 %; viscous 0.35, coef 8, cap 800 → 38 / 35 / 37 / 38 %; locked 0.5 → 54 / 35 / 46 / 49 %; the same car with
+`driveBiasFront` 0 and an AWD centre → **0 %** to the front axle, and 37 km/h slower after 6 s. `validate_vehicle` warns
+`AWD_DRIVE_BIAS_UNPOWERS_AN_AXLE` and `AWD_DRIVE_BIAS_DISAGREES_WITH_CENTRE_SPLIT`.
+
+**Slip-metered centre (engine ≥ 0.3.207; prefer it for any on-demand clutch-pack system).** `simulation.land.driveline.centre.slipMetered:
+{ transferGain, maxFrontShare?, minFrontShare? }` makes the front share follow axle slip instead of a fixed `lsd` lock (e.g. an
+ATTESA-, Haldex- or xDrive-type coupling). Absent = the constant split, exactly as before.
+
+- `centre.torqueSplit` is the share with both axles turning together. Use a small non-zero value for a rear-primary system
+  (`0.02`–`0.05`) or `0.9`–`0.95` for a front-primary one, and set `driveBiasFront` to the same number: exactly 0 or 1 unpowers an axle.
+- `transferGain` (0, 5] is the share moved per rad/s of centre-carrier speed difference near zero slip. `0.01`–`0.03` stays
+  rear-biased under steady power; `0.05` reaches the maximum in launch wheelspin.
+- `maxFrontShare` ∈ [torqueSplit, 1] applies when the REAR slips, and `minFrontShare` ∈ [0, torqueSplit] when the FRONT slips. Set at least one.
+  Torque only moves to the slower (gripping) axle, so a corner (front faster) does not move a rear-primary car's share.
+- Pair it with `type: "open"` and zero LSD coefficients: the metering is the coupling, so an LSD preload on top double-counts it.
+  It is allowed on the centre only, and `validate_vehicle` range-checks it.
+
+```json
+"centre": { "type": "open", "torqueSplit": 0.02, "lsdPreload": 0, "lsdLockCoef": 0, "lsdRevLockCoef": 0,
+            "slipMetered": { "transferGain": 0.05, "maxFrontShare": 0.5 } }
+```
+
+On a 1.56 t AWD package this gave 49 % front in launch wheelspin, 3 % once the rears hooked up, and 26–30 % under full power in higher gears.
+
+### The shift scheme (auto vs manual — and the live shift key)
+
+How a car changes gear is part of its physics and must be authored, never left to a default:
+
+- **`driveline.gearbox.auto { enabled, upRpm, downRpm }` is the automatic upshift.** In the default
+  drive mode the engine shifts itself at `upRpm` and down at `downRpm`. For a road car the player
+  drives by holding throttle, leave `enabled: true` and set `upRpm` just under the limiter and
+  `downRpm` ~40 % of it.
+- **`driveline.gearbox.kind` is `manual` or `sequential` for a manual car.** A manual/sequential kind
+  makes the live drive expose a manual shift layer on top of the automatic one, keyed on the standard
+  action ids: **`ability7` toggles automatic ⇄ manual, `sprint` is the clutch, `ability1`–`ability6`
+  select forward gears 1–6, `crouch` is neutral, `reload` is reverse.** In automatic mode these keys are
+  inert and the `auto` block does the shifting.
+- **The two must agree, or the car cannot be driven.** A manual-kind box with `auto.enabled: false`
+  pins 1st gear and never upshifts in the default drive (round 5's F40 could not be driven live for
+  exactly this class of mismatch) — the player would have to toggle to manual and shift with
+  `ability1`–`ability6`, which no one is told to do. So either author `auto { enabled: true, upRpm,
+  downRpm }` (a road car the default drive should shift itself), or document the manual keys as the
+  intended scheme and say so.
+- **`simulate_vehicle` proves the automatic path only.** It drives in automatic mode, so a car whose
+  `auto` block is wrong (or absent) shows it there: the figures cannot be reached and the comparison
+  fails, with a shift warning. But it cannot prove the live manual layer — when the box is a manual kind
+  it reports "simulated with auto-shift; live manual-shift unverified". **Verify the live car upshifts**
+  (drive it in a hosted flat world, median of 3, and confirm it pulls through the gears) before you ship;
+  round 5 passed the simulator's 0–100 4.28 s while the live car pinned 1st at ~20 km/h.
+
+### Turbo or supercharged cars
+
+Published torque figures for a turbo car are **boosted**. Use that curve as-is and tell the
+solver so; otherwise the validator refuses the double-counted boost. In `physics`:
+
+```json
+"induction": { "kind": "turbo",
+  "maxBoostBar": { "value": 1.15, "unit": "bar", "sources": ["…"] },
+  "wastegateBar": { "value": 1.0, "unit": "bar", "sources": ["…"] },
+  "referenceRpm": { "value": 3800, "unit": "rpm", "derivedFrom": "start of the torque plateau" },
+  "gamma": { "value": 2.0, "unit": "ratio", "derivedFrom": "spool shape prior" },
+  "spoolUpTime": { "value": 0.7, "unit": "s", "derivedFrom": "…" },
+  "spoolDownTime": { "value": 1.0, "unit": "s", "derivedFrom": "…" },
+  "blowOffThresholdBar": { "value": 0.35, "unit": "bar", "derivedFrom": "…" },
+  "torqueCurveIncludesBoost": true }
+```
+
+In `simulation.land.driveline`, set `engine.boostTorqueCoef: 0`, because the curve already holds
+the boost and the turbine only drives the spool and blow-off sound and signals. Then add a
+`turbine` block.
+
+**Author the turbo lag into the curve.** On the v2 solver the engine torque each step is
+`torqueCurve(rpm) × throttle × limiter cut × boost factor`. With `boostTorqueCoef: 0` and no
+`curveBoostBar`, the boost factor is 1: the turbine makes sound but adds no torque, and the curve
+applies as written at every rpm, instantly. (A set `curveBoostBar` only ever raises torque above
+the curve.) A published boosted
+curve then launches the car with full boost from low rpm, and it runs too quick (round 1's F40
+did 0–100 in 3.5 s against a real 4.5 s). So **derate the static curve below the spool point**:
+below the rpm where the real engine comes on boost, use the off-boost torque (the naturally
+aspirated figure for that displacement, or the published curve's own shape below its knee), and
+ramp steeply to the boosted figure across the spool band. Write the arithmetic in `derivedFrom`,
+cite the dyno chart that shows the knee, and confirm the 0–100 and `turboLagS` (with the onset
+rpm it reports) with `simulate_vehicle`. The lag rig holds a low rpm in third gear, goes to full
+throttle, and times how long the pull takes to reach 90 % of its peak acceleration. The engine's turbocharged reference car uses:
+
+```json
+"turbine": { "kind": "turbo",
+  "pressureMap": { "points": [[0,-6.5],[30000,0],[60000,2],[90000,12],[150000,14],[200000,20],[250000,20.5]] },
+  "wastegateStartBar": 0.827, "wastegateLimitBar": 1.413, "inertiaScale": 5, "frictionCoef": 35,
+  "maxExhaustPower": 35000, "pressureRatePsi": 35, "sizeCoef": 0.7,
+  "exhaustFactor": { "points": [[0,0],[650,0.05],[1400,0.35],[2000,0.7],[3000,0.85],[5000,0.95],[7000,1.0],[9000,0.9]] },
+  "volumetricEfficiency": { "points": [[0,0],[650,0.25],[1400,0.65],[2000,0.85],[3000,0.98],[5000,0.8],[7000,0.68],[9000,0.6]] },
+  "displacementM3": 0.002457, "blowOffThresholdBar": 0.35, "driveRatio": 1 }
+```
+
+Also set `driveline.displacementM3`. The `pressureMap` is in turbine rpm against PSI gauge, and
+the wastegate values are in bar; scale them to your car's published boost. The driveline has a
+single optional `turbine`, so a twin-turbo engine is modelled as one turbine for the pair.
+
+### Drivable on a keyboard (the full-throttle launch)
+
+A keyboard player cannot modulate the throttle. What the platform sends is fixed:
+
+- **W is a step.** The drive ability passes it straight to the controller; nothing ramps a digital
+  throttle.
+- **W with A or D is 0.707 throttle and 0.707 steer.** The keyboard `move` vector is normalised, so
+  every heading correction under full throttle cuts the throttle to 71 % while the key is down, and
+  full lock is never available with W held.
+- **A land-v2 car has traction control only if its package authors it**
+  (`simulation.land.tractionControl`, engine humanoid-character 0.3.204+; see "Traction control"
+  below). With ABS (`simulation.land.abs`), it is one of the two driver aids you can author. There
+  is no stability control or launch control. The old anti-wheelie limiter works on the v1
+  powertrain only.
+- **Every full-throttle upshift chirps the driven tyres.** The auto box cuts fuel for
+  `shiftDelay`, then restores full throttle in one step while the clutch re-clamps over 120 ms.
+  The crank has only fallen by engine braking, so it re-engages 1,300–2,400 rpm above the new
+  gear's road speed. Wheel torque peaks at 1.5–2× steady state for about 0.1 s, on every car measured.
+- **The launch clutch** (`clutch.launchStartRpm` / `launchTargetRpm`) slips until the gearbox
+  input passes `launchStartRpm`, and is fully closed above it. A turbo curve whose boost step sits
+  inside that window makes the launch bistable: a clean W overshoots onto boost and spins the
+  rears, while a launch where the throttle dips (W+A) parks at the window with little wheelspin.
+
+`simulate_vehicle` therefore also runs a **keyboard launch** in the same runtime solver.
+
+- **The run.** W goes from 0 to 1 in one tick from an auto-hold stop. The player taps A or D with
+  100 ms reactions to hold a 3.5 m lane, from a start 2° off it. The report gives the keyboard 0–100
+  next to the instrument's, wheelspin time and peak driven slip per gear, the peak yaw rate, heading
+  error and sideslip for 1.5 s after each upshift re-engages, and the worst lane offset.
+- **The probe.** The same launch is run hands-off, with a 0.2 rad/s yaw nudge at 20, 40, 60 and
+  100 km/h and as each of the first two upshifts re-engages. 0.2 rad/s is less than one short tap.
+- **FAIL ("not drivable on a keyboard")** when a nudge grows into a spin (sideslip ≥ 20°, or the
+  yaw rate grows to ≥ 3× the nudge), or when the player spins or leaves the lane.
+- **WARN** when the player needs more than 5.7° of heading or sideslip, when a nudge has not
+  settled after 1 s, or when the keyboard 0–100 is more than 15 % slower than the instrument's.
+- `simulate_vehicle` exits 1 on FAIL. `validate_vehicle` and `publish_vehicle` report it as the
+  warning `SIMULATED_KEYBOARD_LAUNCH_UNDRIVABLE` (or `…_MARGINAL`). It stays a warning because a
+  faithful car without traction control may have no accurate way to pass.
+- The report has a `traction control:` line (none, ON with its tuning, or switched off), and the
+  keyboard launch says how long the controller was cutting torque.
+
+Calibration: round 8's turbo supercar failed the probe at 20, 40 and 60 km/h and at the 1→2
+re-engagement. Live, it hit the arena wall in 3 of 3 keyboard launches. The live 993 passed, and
+reached 100 km/h in 3 of 3 with the same harness: 5.8–6.6 s live, against 5.92 s from the gate.
+
+**Tuning for it without leaving the real figures.** The figures in `targets` are fixed. These
+levers were measured one at a time on round 8's car (577 N·m turbo, rear drive, 39/61, 1st gear ×
+final = 10.1):
+
+| Lever | Effect on the keyboard launch | Cost to accuracy |
+| --- | --- | --- |
+| LSD `lsdLockCoef` 0.1–0.5, `lsdPreload` 0–150 | **None.** In a straight full-throttle launch both rears spin together and the diff stays locked: identical to 0.01 s, still spins | none. Author the real diff and don't expect it to fix a snap |
+| `rear.type: "open"` | 60 km/h settles; 20/40 km/h and the 1→2 re-engagement still marginal or spinning | wrong for an LSD car |
+| Rear `muLut.mu` × 1.15 | 1st-gear wheelspin 3.5 s → 0.2 s; 20/40 km/h still spin | 0–100 4.38 → 3.88 s: off the real figure. Only if the tyre data supports it, and recheck skidpad and 60–0 |
+| Rear `muLut.slideRatio` 0.85 → 0.95–1.0 (less grip lost past the peak) | the 1→2 snap goes; 1st gear still spins | 0–100 → 4.0 s: off the real figure |
+| `launchStartRpm`/`TargetRpm` 3,000/3,500 → 2,000/2,500 (launch below the boost step) | 20 km/h settles; 40/60 km/h still spin | 0–60 4.23 → 4.70 s: out of tolerance |
+| Dynamic boost (`boostTorqueCoef: 1`, NA base curve = boosted curve ÷ (1 + 1.1 bar)) | none; the turbine spools within 1st gear | none (0–100 4.33 s) |
+
+The rule that follows: if the engine's torque through 1st gear exceeds what the rear tyres hold,
+no accurate package lever makes the car stable flat out. Don't hide the wheelspin with extra grip
+or an invented torque curve; both move the car off its figures. Real boost-by-gear behaviour is
+fine to model when it is documented (a turbine with real lag, or an ECU that limits boost in 1st
+and 2nd): cite it. Otherwise, author traction control as the next section describes.
+
+### Traction control (`simulation.land.tractionControl`)
+
+Opt-in and per car: absent means the car has none, and every published car without the block
+drives exactly as before. It needs engine humanoid-character **0.3.204** or later. `simulate_vehicle`
+and `validate_vehicle` run the same runtime the platform serves, so what they report is what a
+player gets. If the block is authored but the runtime is older, the report says it is NOT MODELLED.
+
+```json
+"tractionControl": { "targetSlip": 0.2, "cutRate": 25, "restoreRate": 3, "minTorque": 0.45, "upshiftTorqueRamp": true }
+```
+
+What it does: while the fastest driven wheel's slip ratio is above `targetSlip`, it cuts engine
+torque, faster the further past the target the wheel is. Below the target, it puts the torque back.
+It cuts torque at the crank (like an ignition cut), so boost and engine braking are unaffected. It
+reads the same tyre slip state the tyre model uses, so the controller and the tyre always agree.
+
+| Field | Meaning | Start | Valid |
+| --- | --- | --- | --- |
+| `targetSlip` | Driven-wheel slip ratio to hold. The tyre peaks near 0.14; 0.15–0.2 keeps the launch | 0.2 | 0.02–1 |
+| `cutRate` | Torque fraction cut per second at the target. It grows with the overshoot | 25 | > 0, ≤ 100 |
+| `restoreRate` | Torque fraction restored per second once the wheel is back under the target | 3 | > 0, ≤ 100 |
+| `minTorque` | The least torque fraction it leaves. Below ~0.4 the crank falls under the launch clutch's bite point and the car bogs | 0.45 | 0 – < 1 |
+| `launchSpeed` | Road speed in m/s below which wheelspin is judged as tyre overspeed (`targetSlip × launchSpeed` m/s) instead of a ratio, because a ratio is meaningless at walking pace | omit (5) | 0–30 |
+| `upshiftTorqueRamp` | After each upshift, torque follows the clutch back in until the pack is closed. This smooths the 1.5–2× re-clamp spike every car has | true | boolean; omitted = off |
+| `enabled` | `false` keeps the tuned block in the package with the system off | omit (on) | boolean |
+
+**When to author it.**
+
+- **The maker fitted traction control** (ASR, ASC+T, TCS, a stability system with a traction
+  mode): author it and cite the source next to the car's other equipment. It is part of the real
+  car, so its figures were measured with it working.
+- **The maker fitted none** (the F40, the 993 Carrera, most turbo supercars before the 2000s): you
+  may still author it, as a **playability aid**, when the keyboard launch FAILs and no accurate
+  lever above fixes it. Declare it. Say "traction control: playability aid, not fitted to the real
+  car" in the item description and in the ledger. Every figure must stay inside its tolerance.
+- **The car already passes the keyboard launch**: leave it out. It costs a car whose launch already
+  works some time: the live 993 goes from 0–100 5.62 s to 5.90 s with the starting block.
+
+**How to tune it.** Run `simulate_vehicle` after each change, and read the keyboard-launch verdict,
+the probes, "traction control cutting … s", and 0–100 against its target.
+
+1. Start from the block above.
+2. A probe still spins: lower `targetSlip` (0.15) or raise `cutRate` (40). If only the probe at
+   an upshift re-engagement spins, check that `upshiftTorqueRamp` is `true`.
+3. The car is now slower than its tolerance, or the keyboard 0–100 gap is a WARN: raise
+   `minTorque` (0.5), then `restoreRate` (4–8), then `targetSlip` (0.25).
+4. The car is now **quicker** than its tolerance. This can happen: the instrument's own launch
+   stops wasting time in wheelspin. The F40 with `cutRate: 40` ran 0–100 in 4.23 s against
+   4.60 s ±6 %, and failed. Soften the controller (lower `cutRate`, raise `targetSlip`). Never
+   move the targets.
+
+Measured on engine 0.3.204 (`helix vehicle simulate`):
+
+| Car | Traction control | 0–100 (target) | Keyboard launch |
+| --- | --- | --- | --- |
+| F40, 577 N·m turbo RWD (none fitted) | none | 4.38 s (4.60 ±6 %) | FAIL: spins at 20, 40 and 60 km/h and at the 1→2 |
+| F40 | starting block | 4.38 s | PASS: every probe settles; 2nd-gear post-shift slip 0.39 → 0.22 |
+| 993 Carrera | none | 5.62 s (5.60 ±6 %) | PASS |
+| 993 Carrera | starting block | 5.90 s | PASS. It costs 0.28 s, so leave it off |
+| 993 with 1.6× torque (more than its rears hold) | none | 4.23 s | FAIL |
+| 993 with 1.6× torque | starting block | 4.22 s | PASS |
+
+## Staggered tyres
+
+Many sports cars run wider, taller tyres at the rear (a 245/40R17 front and 335/35R17 rear has
+rolling radii of 0.314 m and 0.333 m). Model it as the real car is:
+
+- **Draw each axle's tyre at its own size**, with each wheel node's origin at its own hub
+  (`rim_lf`/`rim_rf` at the front radius, `rim_lr`/`rim_rr` at the rear).
+- Set each **`simulation.land.tyreByAxle[].radius`** to that axle's measured rolling radius, and
+  `physics.chassis.tyreSize` to the real sizes (for example `"245/40R17 / 335/35R17"`).
+- Set `physics.chassis.wheelRadius` to the **driven axle's** radius (the rear on a rear-drive car):
+  it sets the rolling radius and so the gearing. Keep
+  `groundToBodyOrigin = wheelRadius + staticRideHeight`. The physics contacts still use this one
+  radius at all four corners, so the other axle's contact sits off its drawn tyre by the radius
+  difference (about 19 mm on a 245/40R17 front and 335/35R17 rear). Look at the parked stance in
+  `preview_vehicle`.
+- Visual QA judges spin and the drawn tyre radius per wheel, against that axle's `tyreByAxle`
+  radius, so a staggered car passes as it is. Never equalise the tyres to satisfy a check: round
+  1's F40 drew both axles at one size and lost accuracy for nothing.
+
+## 3. Targets
+
+`targets` holds the published behaviour, each value with a `tolerance` in (0, 1):
+
+| Target | Notes |
+| --- | --- |
+| `zeroToSixtyMphS` | |
+| `zeroToHundredKphS` | |
+| `quarterMileS` | |
+| `topSpeedKph` | The **ungoverned** figure (see "Top speed" below). |
+| `ungovernedTopSpeedKph` | Derestricted, drag-limited speed. Equal to `topSpeedKph`. |
+| `lateralG` | |
+| `brakingSixtyToZeroM` | |
+
+The width of each tolerance is itself a claim. Use about ±6 % on a manufacturer figure, and
+±10–15 % on derived figures such as a Fox/Hale quarter mile
+(`ET = 6.290 × (lb/hp)^(1/3)`) or a lateral g.
+
+**Braking:** take the median of the published stopping distances, from the same speed. Convert
+before comparing (70–0 mph = 1.36 × the 60–0 distance at the same deceleration), and never keep
+the shortest figure because it flatters the car.
+
+### Top speed: governed vs ungoverned
+
+**The platform car runs ungoverned.** A market or gentlemen's-agreement governor (a domestic-market 180 km/h cap, a 250 km/h agreement, a
+tyre-rated limiter) is a rule about the car, not its physics, and the live land solver never applies `physics.engine.speedLimiterKph`:
+only the `simulate_vehicle` instrument reads it. Authoring one makes the instrument, `targets.topSpeedKph`, the customizer figures and the
+description all say a number the live car does not obey.
+
+- `physics.engine.speedLimiterKph.value` is `null`. Say the real car's governor, if it had one, in the description only.
+- `targets.topSpeedKph` and `targets.ungovernedTopSpeedKph` are the **ungoverned** figure (the best derestricted instrumented test, else
+  the maker's claim, else the gearing/drag figure), with an honest tolerance.
+- `SPEED_LIMITER_IS_A_MARKET_GOVERNOR` (a warning from `simulate_vehicle` and `validate_vehicle`) fires when the limiter is below
+  0.9 × the ungoverned figure. Its fix is the two lines above.
+- No add-on can add or remove a limiter: the ECU slot's tune paths (`torqueCurve`, `limiterRpm`, …) have no speed-limiter path and the
+  backend refuses one. Do not describe an ECU part as "removing the limiter" on a car that has none.
+
+### Torque: target the declared crank figures
+
+The maker's declared peak crank torque and power (with their rpm) **are** the engine. Scale the curve to them, in both places
+(`physics.engine.torqueCurve` and `simulation.land.driveline.engine.torqueCurve.points`, which must stay identical), and state
+`peakTorqueNm` / `peakPowerKw` to match. Never tune to dyno folklore (a wheel dyno divided by a guessed efficiency, a forum "real"
+figure) or to a top-speed number.
+
+- Real-world losses live in `drivetrainEfficiency` (cited) and aero drag. 0–100 and top speed are met with grip, gearing, launch and
+  exact mass, not with a bigger engine.
+- Put the maker's figures in a `manufacturer` citation title (`"200 kW / 272 PS at 6,100 rpm, 330 N·m at 5,000 rpm"`):
+  `TORQUE_CURVE_EXCEEDS_DECLARED_CRANK_FIGURES` (a warning from `simulate_vehicle` and `validate_vehicle`) reads N·m / kgm / lb-ft and
+  kW / PS / hp from those titles, ignores "at the wheels" and dyno lines, and falls back to the package's own peak fields. It fires when
+  a curve or peak field is more than 5 % above the declared figure.
+- If a documented market cap (an industry agreement) understates the real car and the targets then miss, keep the declared curve, say so
+  in the description and the ledger, and close the gap only with the levers above. A car at its honest crank figure that is 10 % slow is
+  a better product than an inflated one.
+
+## 4. Checking it
+
+- **Before publish, structure:** `validate_vehicle`.
+- **Before publish, behaviour:** `simulate_vehicle({ target: <dir> })` drives the package on the
+  platform's own vehicle runtime (the live `humanoid-character` bundle, fetched and cached; it
+  prints the runtime version it ran) and reports 0–100 km/h, 0–60 mph, the quarter mile, top
+  speed (governed and ungoverned), 100–0 km/h and 60–0 mph braking, skidpad lateral g, turbo lag,
+  the gears used and the rest pose.
+  - Each figure with a `targets` entry is compared: it passes when
+    `|simulated − target| / target ≤ tolerance` (a fraction: 0.06 is ±6 %).
+  - The rest pose fails when the car is not grounded or rests with pitch or roll beyond 3°.
+  - `spec` adds an extra target file: a package, `{ targets: {…} }`, or a reference spec of
+    `perf.*` figures (`perf.0_100_kmh_s`, `perf.braking_100_0_m`, `perf.braking_60mph_0_m`,
+    `perf.turbo_lag_s`, …; a leaf is a number or `{ value, tol_pct }`, default ±10 %). Use it for
+    figures `targets` cannot hold, such as 100–0 braking and turbo lag.
+  - It also runs the keyboard launch and its hands-off yaw probe (see "Drivable on a keyboard"
+    above): keyboard 0–100 against the instrument, wheelspin per gear, post-shift yaw, lane offset.
+  - Exit 0: every compared figure passes and the keyboard launch does not FAIL. 1: a figure is out
+    of tolerance, the rest pose is wrong, or the car is not drivable on a keyboard. 2: it could not
+    simulate.
+  - `simulate_vehicle({ itemId })` drives a **published** car's stored package the same way. Run
+    it on a control car with known real figures (the live 993) to see the instrument's own bias.
+  - `validate_vehicle` runs the same check whenever the package has `targets`
+    (`SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE`, `SIMULATED_REST_POSE_INVALID`), and so does
+    `publish_vehicle`, which refuses before the mint. `noSimulate` skips it.
+
+  Iterate on `grip.peak`, `suspension.*`, launch behaviour and, for a turbo car, the derated low
+  end, never on cited engine or gearing values. Record the final figures in your ledger beside
+  the targets.
+- **On the live car:** time 0–100 in a hosted world, in a median of 3 runs, with a control car
+  of known real figures in the same world. A hosted control read 0.7–1 s slow against its real
+  figure, so judge the delta.
+  - Discard any sample after a wheel leaves the ground. The `universal-items-empty` floor ends
+    about 80 m from spawn, and an airborne car chain-shifts.
+  - Top speed cannot be measured live in that world.
+- **The clock origin matters.** Time from throttle application, not from motion.
+- **If the car is "slow" but revs high:** check for a kerb or wall contact (the chassis box clears
+  0.16 m) and for sim time against wall time before touching the drivetrain.
+
+The worked 993 values are: 1,370 kg; 0.39 front; CoM 0.48 m; wheel radius 0.315; static ride
+height 0.165; ride 1.55/1.75 Hz; damping 0.45; anti-roll bars 14,000/9,000; Cd 0.33; area 1.8 m²;
+330 N·m at 5,000 rpm; 200 kW at 6,100 rpm; limiter 6,800; gears
+3.818/2.15/1.56/1.242/1.027/0.821; final drive 3.444; reverse −3.545; shift 0.25 s; brakes
+7,400 N·m with 0.66 front bias; tyre peak 1.18 and sliding 1.08; lock 34°. They reproduced the
+manufacturer's 0–100 of 5.6 s offline (5.58 s on the solver `simulate_vehicle` runs), and
+5.3–5.55 s live.