Initial Commit
This commit is contained in:
154
openspec/changes/enterprise-gaming-controller/proposal.md
Normal file
154
openspec/changes/enterprise-gaming-controller/proposal.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# OpenSpec Change: enterprise-gaming-controller
|
||||
|
||||
- **Change ID**: enterprise-gaming-controller
|
||||
- **Package**: `@suaveplan/controller`
|
||||
- **Category**: gaming/engine
|
||||
- **Target path**: `gaming/engine/controller`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/controller.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/controller` on the genesis branch from scratch at enterprise quality. The package provides controller abstractions — a unified input layer that normalises keyboard, mouse, gamepad (Web Gamepad API), touch, and virtual on-screen controls into a single `ActionMap`. Actions are named bindings mapped to digital (pressed/released) and analog (axis) values. A `ControllerManager` polls inputs each tick, resolves conflicts, applies deadzone and sensitivity curves, and fires `@suaveplan/events` action events. Genesis adds Zod binding schemas, structured errors, OTel input-latency histogram, and 100% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis yet — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `ControllerError`; `CONTROLLER.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | `Clock` |
|
||||
| `@suaveplan/events` (`workspace:^`) | Action-pressed/released events |
|
||||
| `zod` (`catalog:forms`) | Binding config schemas |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Input-latency histogram |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
```ts
|
||||
function createControllerManager(options?: ControllerManagerOptions): ControllerManager
|
||||
|
||||
interface ControllerManagerOptions {
|
||||
deadzone?: number // analog deadzone 0–1, default 0.1
|
||||
bindings?: ActionBinding[]
|
||||
clock?: Clock
|
||||
}
|
||||
|
||||
interface ControllerManager {
|
||||
registerBinding(binding: ActionBinding): void
|
||||
removeBinding(action: string): void
|
||||
isPressed(action: string): boolean
|
||||
getAxis(action: string): number // -1 to 1
|
||||
poll(dt?: number): void // called each game tick
|
||||
destroy(): void
|
||||
}
|
||||
|
||||
type InputSource = 'keyboard' | 'mouse' | 'gamepad' | 'touch' | 'virtual'
|
||||
|
||||
interface ActionBinding {
|
||||
action: string
|
||||
source: InputSource
|
||||
key?: string // keyboard: e.g. 'KeyW', 'Space'
|
||||
button?: number // gamepad button index
|
||||
axis?: number // gamepad axis index
|
||||
mouseButton?: number // 0=left, 1=middle, 2=right
|
||||
touchId?: number
|
||||
invert?: boolean
|
||||
sensitivity?: number
|
||||
}
|
||||
|
||||
// Keyboard/mouse adapter (for environments with DOM)
|
||||
function createKeyboardAdapter(): InputAdapter
|
||||
function createGamepadAdapter(): InputAdapter
|
||||
function createVirtualAdapter(): InputAdapter & { setAxis(action: string, value: number): void }
|
||||
|
||||
interface InputAdapter {
|
||||
readonly source: InputSource
|
||||
isPressed(key: string | number): boolean
|
||||
getAxis(index: number): number
|
||||
attach(): void
|
||||
detach(): void
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type ControllerErrorCode =
|
||||
| 'CONTROLLER_ACTION_NOT_FOUND'
|
||||
| 'CONTROLLER_DUPLICATE_BINDING'
|
||||
| 'CONTROLLER_INVALID_AXIS'
|
||||
| 'CONTROLLER_ADAPTER_ERROR'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Multi-source conflict resolution** — when multiple sources bind the same action, the last non-zero value wins.
|
||||
2. **Sensitivity curves** — linear, quadratic, and cubic response curves for analog axes.
|
||||
3. **Virtual adapter** — headless adapter for touch/on-screen controls; state driven by caller (used by `@suaveplan/react-controller`).
|
||||
4. **OTel** — `controller.poll_duration_ms` histogram; `controller.active_bindings` gauge.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
gaming/engine/controller/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/index.ts
|
||||
types/common.ts
|
||||
types/common.md
|
||||
core/
|
||||
controller-manager/
|
||||
controller-manager.ts
|
||||
controller-manager.md
|
||||
controller-manager.types.ts
|
||||
controller-manager.test.ts
|
||||
index.ts
|
||||
adapters/
|
||||
keyboard-adapter/
|
||||
keyboard-adapter.ts
|
||||
keyboard-adapter.md
|
||||
keyboard-adapter.test.ts
|
||||
index.ts
|
||||
gamepad-adapter/
|
||||
gamepad-adapter.ts
|
||||
gamepad-adapter.md
|
||||
gamepad-adapter.test.ts
|
||||
index.ts
|
||||
virtual-adapter/
|
||||
virtual-adapter.ts
|
||||
virtual-adapter.md
|
||||
virtual-adapter.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
sensitivity.ts
|
||||
sensitivity.md
|
||||
sensitivity.test.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: `@suaveplan/react-controller` wraps virtual adapter in React hooks; `@suaveplan/r3f-controller` drives Three.js camera/character from action map. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.
|
||||
56
openspec/changes/enterprise-gaming-controller/tasks.md
Normal file
56
openspec/changes/enterprise-gaming-controller/tasks.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Tasks: enterprise-gaming-controller
|
||||
|
||||
## 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/engine/controller/` (`@suaveplan/controller`, `0.1.0`, `sideEffects: false`)
|
||||
- [ ] `tsconfig.json`, `vitest.config.ts`
|
||||
|
||||
## Phase 2 — Error codes & constants
|
||||
|
||||
- [ ] `src/error-codes.ts` — `ControllerError`, `CONTROLLER.*` codes
|
||||
- [ ] `src/constants/index.ts` — `DEFAULT_DEADZONE`, `AXIS_MIN`, `AXIS_MAX`
|
||||
|
||||
## Phase 3 — Types
|
||||
|
||||
- [ ] `src/types/common.ts` + `common.md`
|
||||
|
||||
## Phase 4 — Sensitivity curves
|
||||
|
||||
- [ ] `src/utils/sensitivity.ts` — linear/quadratic/cubic response + deadzone clamp
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 5 — Virtual adapter
|
||||
|
||||
- [ ] `src/adapters/virtual-adapter/virtual-adapter.ts` — headless; state set by caller
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 6 — Keyboard adapter
|
||||
|
||||
- [ ] `src/adapters/keyboard-adapter/keyboard-adapter.ts` — attach/detach DOM listeners
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 7 — Gamepad adapter
|
||||
|
||||
- [ ] `src/adapters/gamepad-adapter/gamepad-adapter.ts` — navigator.getGamepads() poll
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 8 — Controller manager
|
||||
|
||||
- [ ] `src/core/controller-manager/controller-manager.ts` — multi-source poll, conflict resolution, OTel
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 9 — Integration tests
|
||||
|
||||
- [ ] `tests/integration.test.ts` — binding registration, poll cycle, action read
|
||||
|
||||
## Phase 10 — Pre-publish gate
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/controller` green
|
||||
- [ ] 100% coverage
|
||||
- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/controller`
|
||||
Reference in New Issue
Block a user