suaveplan/openspec/changes/enterprise-gaming-r3f-vehicle/proposal.md

OpenSpec Change: enterprise-gaming-r3f-vehicle

• Change ID: enterprise-gaming-r3f-vehicle
• Package: @suaveplan/r3f-vehicle
• Category: gaming/devices
• Target path: gaming/devices/r3f-vehicle
• Status: PROPOSED
• Date: 2026-04-24

---

Summary

Deliver @suaveplan/r3f-vehicle on the genesis branch from scratch at enterprise quality. The package provides React Three Fiber vehicle rendering and controller integration: a Vehicle component that drives a Three.js mesh from physics state provided by @suaveplan/vehicle-physics, animated wheel joints, chassis lean, suspension travel visualization, headlight beams, exhaust particles, and skid-mark decals. useVehicle() exposes throttle/brake/steer inputs and vehicle telemetry. Genesis adds 100% coverage and Storybook stories.

---

Available workspace deps

@suaveplan/vehicle-physics, @suaveplan/controller, @suaveplan/error, @suaveplan/types, react, @react-three/fiber, @react-three/drei, three.

---

Public API surface

interface VehicleProps {
  physicsRef: VehiclePhysicsRef
  chassisModel: THREE.Object3D
  wheelModels: THREE.Object3D[]
  enableSkidMarks?: boolean
  enableExhaust?: boolean
  enableHeadlights?: boolean
}

function Vehicle(props: VehicleProps): JSX.Element
function VehicleCamera(props: VehicleCameraProps): JSX.Element
// follows vehicle with spring arm, configurable offset

function useVehicle(): VehicleContext
// throttle, brake, steer, telemetry (speed, rpm, gear)

---

File layout

gaming/devices/r3f-vehicle/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    hooks/use-vehicle.ts + md + test
    components/
      Vehicle/ (tsx + md + test + stories + index)
      VehicleCamera/ (tsx + md + test + stories + index)
  tests/integration.test.ts