Initial Commit

openspec/changes/enterprise-gaming-vehicle-physics/proposal.md

@@ -0,0 +1,173 @@
+# OpenSpec Change: enterprise-gaming-vehicle-physics
+
+- **Change ID**: enterprise-gaming-vehicle-physics
+- **Package**: `@suaveplan/vehicle-physics`
+- **Category**: gaming/rigs
+- **Target path**: `gaming/rigs/vehicle-physics`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/vehicle-physics.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/vehicle-physics` on the genesis branch from scratch at enterprise quality. The package provides engine-agnostic vehicle physics using Pacejka Magic Formula tire model, spring-damper suspension per wheel, multi-wheel drivetrain (FWD/RWD/AWD), differential, braking, and aerodynamic drag. All math is pure TypeScript with no runtime deps — physics backends plug in via interface. Genesis adds Zod config schemas, structured errors, injectable clock, OTel telemetry, and property tests verifying tire force symmetry and suspension convergence.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis yet — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `VehiclePhysicsError`; `VEHICLE.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock` |
+| `@suaveplan/events` (`workspace:^`) | `vehicle:collision`, `vehicle:flip`, `vehicle:stall` events |
+| `zod` (`catalog:forms`) | `VehicleConfig` schema |
+| `@opentelemetry/api` (`catalog:observability`) | Step duration histogram |
+
+---
+
+## Public API surface
+
+```ts
+function createVehicle(config: VehicleConfig): Vehicle
+
+interface VehicleConfig {
+  mass: number
+  wheelBase: number
+  trackWidth: number
+  centerOfMassY: number
+  engine: EngineConfig
+  transmission: TransmissionConfig
+  wheels: WheelConfig[]
+  aerodynamics?: AeroConfig
+  backend?: VehiclePhysicsBackend
+  clock?: Clock
+}
+
+interface EngineConfig {
+  maxTorque: number           // Nm
+  maxRpm: number
+  torqueCurve?: [rpm: number, torque: number][]
+  idleRpm?: number
+}
+
+interface TransmissionConfig {
+  type: 'FWD' | 'RWD' | 'AWD'
+  gearRatios: number[]
+  finalDrive: number
+  differentialSlip?: number
+}
+
+interface WheelConfig {
+  position: Vec3
+  radius: number
+  suspensionRestLength: number
+  suspensionStiffness: number
+  suspensionDamping: number
+  tireGripLateral: number
+  tireGripLongitudinal: number
+}
+
+interface Vehicle {
+  update(dt: number, input: VehicleInput): void
+  teleport(position: Vec3, rotation: Quat): void
+  applyImpulse(impulse: Vec3): void
+  flip(): void
+  readonly position: Vec3
+  readonly rotation: Quat
+  readonly velocity: Vec3
+  readonly speed: number        // m/s
+  readonly rpm: number
+  readonly gear: number
+  readonly wheelsGrounded: boolean[]
+}
+
+interface VehicleInput {
+  throttle: number    // 0–1
+  brake: number       // 0–1
+  steering: number    // -1 to 1
+  handbrake: boolean
+  clutch?: number
+}
+```
+
+### Error codes
+
+```ts
+type VehicleErrorCode =
+  | 'VEHICLE_INVALID_CONFIG'
+  | 'VEHICLE_BACKEND_NOT_SET'
+  | 'VEHICLE_UPDATE_FAILED'
+  | 'VEHICLE_INVALID_GEAR'
+```
+
+---
+
+## New additions for genesis
+
+1. **Pacejka tire model** — lateral and longitudinal force from slip angle / slip ratio; configurable B/C/D/E coefficients.
+2. **Automatic gear shifting** — RPM-based shift logic with configurable up/down thresholds.
+3. **Aerodynamic drag + downforce** — `0.5 * rho * Cd * A * v²` drag; downforce scales with speed².
+4. **Suspension raycast** — `VehiclePhysicsBackend.castRay()` for each wheel per tick; ground contact from hit distance.
+
+---
+
+## File layout
+
+```text
+gaming/rigs/vehicle-physics/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      vehicle/
+        vehicle.ts
+        vehicle.md
+        vehicle.types.ts
+        vehicle.test.ts
+        index.ts
+    models/
+      pacejka/
+        pacejka.ts
+        pacejka.md
+        pacejka.test.ts
+        index.ts
+      suspension/
+        suspension.ts
+        suspension.md
+        suspension.test.ts
+        index.ts
+      drivetrain/
+        drivetrain.ts
+        drivetrain.md
+        drivetrain.test.ts
+        index.ts
+    backends/
+      null-backend/
+        null-backend.ts
+        null-backend.md
+        null-backend.test.ts
+        index.ts
+  tests/
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/r3f-vehicle` wires this to Rapier. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.