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

OpenSpec Change: enterprise-gaming-r3f-controller

• Change ID: enterprise-gaming-r3f-controller
• Package: @suaveplan/r3f-controller
• Category: gaming/character
• Target path: gaming/character/r3f-controller
• Status: PROPOSED
• Date: 2026-04-24
• Reference spec: /mnt/s/web/suaveplan/enterprise/r3f-controller.md

---

Summary

Deliver @suaveplan/r3f-controller on the genesis branch from scratch at enterprise quality. The package provides an input controller for 3D scenes in React Three Fiber. It bridges @suaveplan/controller's ControllerManager to Three.js camera and character movement: a CameraController listens to mouse/gamepad look-axes and applies yaw/pitch to a camera rig; a MovementController maps WASD/joystick to a velocity vector in camera-relative space. A ControllerScene component wraps both and exposes useR3FController(). Genesis adds structured errors and 100% coverage.

---

Available workspace deps

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

---

Public API surface

function ControllerScene(props: ControllerSceneProps): JSX.Element
// manager, mode: 'fps' | 'third-person' | 'orbit'

function useR3FController(): R3FControllerState
// moveVelocity: Vec3, lookEuler: Euler, isAiming: boolean

---

File layout

gaming/character/r3f-controller/
  package.json / tsconfig.json / vitest.config.ts
  src/
    index.ts / error-codes.ts
    types/common.ts + md
    core/
      camera-controller/ (ts + md + types + test + index)
      movement-controller/ (ts + md + types + test + index)
    hooks/use-r3f-controller.ts + md + test
    components/
      ControllerScene/ (tsx + md + test + stories + index)
  tests/integration.test.ts