Initial Commit
This commit is contained in:
@@ -0,0 +1,143 @@
|
||||
# OpenSpec Change: enterprise-gaming-game-state-schemas
|
||||
|
||||
- **Change ID**: enterprise-gaming-game-state-schemas
|
||||
- **Package**: `@suaveplan/game-state-schemas`
|
||||
- **Category**: gaming/engine
|
||||
- **Target path**: `gaming/engine/game-state-schemas`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/game-state-schemas.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/game-state-schemas` on the genesis branch from scratch at enterprise quality. The package provides bit-level quantization schemas for multiplayer state compression — essential for reducing network bandwidth in real-time games. A `BitPacker` encodes typed fields (bool, uint, int, float, enum, string) into compact binary buffers using field descriptors. A `StateSchema` composes multiple `BitField` descriptors into a versioned schema with `encode`/`decode` round-trips. Genesis adds Zod schemas for all descriptor types, `@suaveplan/serialize` for framing, structured errors, OTel bandwidth gauges, and 100% coverage with round-trip property tests.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis yet — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `GameStateError`; `GAME_STATE.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | Shared primitives |
|
||||
| `@suaveplan/serialize` (`workspace:^`) | Framing for state snapshots |
|
||||
| `zod` (`catalog:forms`) | Field descriptor schemas |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Bandwidth histogram |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
```ts
|
||||
// Field descriptors
|
||||
type BitField =
|
||||
| { type: 'bool'; name: string }
|
||||
| { type: 'uint'; name: string; bits: number }
|
||||
| { type: 'int'; name: string; bits: number }
|
||||
| { type: 'float'; name: string; bits: number; min: number; max: number }
|
||||
| { type: 'enum'; name: string; values: string[] }
|
||||
| { type: 'string'; name: string; maxBytes: number }
|
||||
|
||||
// Schema
|
||||
function defineStateSchema<T extends Record<string, unknown>>(
|
||||
name: string,
|
||||
version: number,
|
||||
fields: BitField[]
|
||||
): StateSchema<T>
|
||||
|
||||
interface StateSchema<T> {
|
||||
readonly name: string
|
||||
readonly version: number
|
||||
readonly bitsPerFrame: number
|
||||
encode(state: T): Uint8Array
|
||||
decode(buffer: Uint8Array): T
|
||||
patch(prev: T, next: T): Uint8Array // delta encoding — only changed fields
|
||||
applyPatch(prev: T, patch: Uint8Array): T
|
||||
}
|
||||
|
||||
// BitPacker (low-level, exposed for custom schemas)
|
||||
function createBitPacker(capacityBits: number): BitPacker
|
||||
|
||||
interface BitPacker {
|
||||
writeBool(value: boolean): void
|
||||
writeUint(value: number, bits: number): void
|
||||
writeInt(value: number, bits: number): void
|
||||
writeFloat(value: number, bits: number, min: number, max: number): void
|
||||
toBuffer(): Uint8Array
|
||||
}
|
||||
|
||||
function createBitReader(buffer: Uint8Array): BitReader
|
||||
|
||||
interface BitReader {
|
||||
readBool(): boolean
|
||||
readUint(bits: number): number
|
||||
readInt(bits: number): number
|
||||
readFloat(bits: number, min: number, max: number): number
|
||||
readonly bytesRead: number
|
||||
}
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type GameStateErrorCode =
|
||||
| 'GAME_STATE_BUFFER_OVERFLOW'
|
||||
| 'GAME_STATE_DECODE_FAILED'
|
||||
| 'GAME_STATE_SCHEMA_MISMATCH'
|
||||
| 'GAME_STATE_INVALID_FIELD'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Delta/patch encoding** — `patch()` writes only fields that differ; `applyPatch()` merges on receiver side.
|
||||
2. **Float quantization** — normalised float mapped to N-bit fixed-point; round-trip error bounded by `(max-min) / 2^bits`.
|
||||
3. **OTel** — `game_state.encode_bytes` histogram; `game_state.decode_duration_ms` histogram.
|
||||
4. **Property tests** — fast-check: `decode(encode(state)) deepEquals state` for all field types.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
gaming/engine/game-state-schemas/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/index.ts
|
||||
types/common.ts
|
||||
types/common.md
|
||||
core/
|
||||
bit-packer/
|
||||
bit-packer.ts
|
||||
bit-packer.md
|
||||
bit-packer.types.ts
|
||||
bit-packer.test.ts
|
||||
index.ts
|
||||
state-schema/
|
||||
state-schema.ts
|
||||
state-schema.md
|
||||
state-schema.types.ts
|
||||
state-schema.test.ts
|
||||
index.ts
|
||||
tests/
|
||||
property.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: `@suaveplan/r3f-networking` uses state schemas for delta sync; `@suaveplan/character-vehicle-picker` uses `BitPacker` for catalog compression. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/serialize`.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Tasks: enterprise-gaming-game-state-schemas
|
||||
|
||||
## 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/game-state-schemas/` (`@suaveplan/game-state-schemas`, `0.1.0`, `sideEffects: false`)
|
||||
- [ ] `tsconfig.json`, `vitest.config.ts`
|
||||
|
||||
## Phase 2 — Error codes & constants
|
||||
|
||||
- [ ] `src/error-codes.ts` — `GameStateError`, `GAME_STATE.*` codes
|
||||
- [ ] `src/constants/index.ts`
|
||||
|
||||
## Phase 3 — Types
|
||||
|
||||
- [ ] `src/types/common.ts` + `common.md` — `BitField`, `StateSchema<T>`, `BitPacker`, `BitReader`
|
||||
|
||||
## Phase 4 — BitPacker / BitReader
|
||||
|
||||
- [ ] `src/core/bit-packer/bit-packer.ts` — writeBool/writeUint/writeInt/writeFloat, dynamic buffer growth
|
||||
- [ ] `BitReader` counterpart in same module
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 5 — StateSchema
|
||||
|
||||
- [ ] `src/core/state-schema/state-schema.ts` — `defineStateSchema()`, encode/decode, patch/applyPatch
|
||||
- [ ] Float quantization helper (min/max → N-bit fixed-point)
|
||||
- [ ] OTel histograms
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 6 — Property tests
|
||||
|
||||
- [ ] `tests/property.test.ts` — fast-check round-trip for all field types, delta idempotence
|
||||
|
||||
## Phase 7 — Pre-publish gate
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/game-state-schemas` green
|
||||
- [ ] 100% coverage
|
||||
- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/game-state-schemas`
|
||||
Reference in New Issue
Block a user