144 lines
4.4 KiB
Markdown
144 lines
4.4 KiB
Markdown
# 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`.
|