# 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

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

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

---

## File layout

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