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`.

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

@@ -0,0 +1,56 @@
+# Tasks: enterprise-gaming-vehicle-physics
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/rigs/vehicle-physics/` (`@suaveplan/vehicle-physics`, `0.1.0`, `sideEffects: false`)
+- [ ] `tsconfig.json`, `vitest.config.ts`
+
+## Phase 2 — Error codes & constants
+
+- [ ] `src/error-codes.ts` + `src/constants/index.ts` (air density, default torque curve, shift thresholds)
+
+## Phase 3 — Types
+
+- [ ] `src/types/common.ts` + `common.md`
+
+## Phase 4 — Pacejka tire model
+
+- [ ] `src/models/pacejka/pacejka.ts` — lateral force + longitudinal force from slip angle/ratio + BCDE coefficients
+- [ ] Tests: symmetry at zero slip, force direction
+- [ ] Docs
+
+## Phase 5 — Suspension
+
+- [ ] `src/models/suspension/suspension.ts` — spring-damper PD controller per wheel, compression ratio
+- [ ] Tests + docs
+
+## Phase 6 — Drivetrain
+
+- [ ] `src/models/drivetrain/drivetrain.ts` — torque distribution FWD/RWD/AWD, gear ratio, differential slip, auto-shift
+- [ ] Tests + docs
+
+## Phase 7 — Null backend
+
+- [ ] `src/backends/null-backend/null-backend.ts` — flat infinite ground; all wheels grounded
+- [ ] Tests + docs
+
+## Phase 8 — Vehicle
+
+- [ ] `src/core/vehicle/vehicle.ts` — integrate all models per tick, OTel, events
+- [ ] Tests + docs
+
+## Phase 9 — Property tests
+
+- [ ] `tests/property.test.ts` — tire symmetry, suspension convergence, throttle → speed monotone
+
+## Phase 10 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/vehicle-physics` green
+- [ ] 100% coverage
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/vehicle-physics`