first commit

docs/foundation/bitpacker/bitpacker-game/src/schema-factory/schema-factory.md

@@ -0,0 +1,68 @@
+# Game Schema Factory
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Programmatic schema construction for game-specific bitpacker schemas. `createGameSchema(options)` returns a tuned `BitPackerSchema` based on the consumer's choice of position bit-width, rotation precision, health/speed caps, and other gameplay-domain knobs. The function lets a consumer derive a schema from per-game design parameters (e.g. "this game has 1024 m world bounds with 0.01 m precision") rather than hand-rolling the same schema across multiple sources.
+
+The `GameSchemaFactory` const is a curated set of named factory presets — `small`, `medium`, `large`, `precise`, `arcade` — each producing a `BitPackerSchema` with appropriate trade-offs. New presets can be appended; the consumer's `createGameSchema(options)` always overrides preset defaults with explicit options.
+
+## Features
+
+- `createGameSchema(options?)` — main factory that returns a fully-tuned `BitPackerSchema`
+- `GameSchemaFactory` — const map of named presets (`small`, `medium`, `large`, `precise`, `arcade`)
+- `GameSchemaOptions` — `maxPosition`, `positionPrecision`, `maxRotation`, `rotationPrecision`, `maxHealth`, `maxSpeed`, plus optional fields for actions, effects, animations
+- All numeric inputs are checked at construction; out-of-range values produce an error rather than a corrupted schema
+
+## Usage: Basic Example
+
+```ts
+import { createGameSchema } from "@suaveplan/bitpacker-game";
+
+const schema = createGameSchema({
+    maxPosition: 512,
+    positionPrecision: 1,
+    maxHealth: 100,
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    createGameSchema,
+    GameBitPacker,
+    GameSchemaFactory,
+} from "@suaveplan/bitpacker-game";
+
+// Pick a preset for arcade-style games (small world, low precision):
+const arcade = GameSchemaFactory.arcade;
+const arcadeBP = new GameBitPacker(arcade);
+
+// Or compose: start from a preset and override a single knob:
+const customLarge = createGameSchema({
+    ...GameSchemaFactory.large,
+    rotationPrecision: 0.1, // fine yaw for first-person aim
+    maxSpeed: 20,
+});
+const customBP = new GameBitPacker(customLarge);
+```
+
+## API Reference
+
+### `createGameSchema(options?: GameSchemaOptions): BitPackerSchema`
+
+Builds a `BitPackerSchema` for a player state with position, rotation, stats, and optional metadata. `options` defaults to `{ maxPosition: 1024, positionPrecision: 2, maxRotation: 180, rotationPrecision: 1, maxHealth: 100, maxSpeed: 8 }`. Returns a schema ready to pass to `new GameBitPacker(schema)`.
+
+### `GameSchemaFactory: { small, medium, large, precise, arcade }`
+
+Const map of pre-built schemas. Each preset is a fully-tuned `BitPackerSchema` produced by `createGameSchema` with appropriate options. Consumers use these as starting points or as drop-in choices for typical game shapes.
+
+## Implementation Notes
+
+- **Precision is a divisor, not a digit count.** `positionPrecision: 0.01` means the schema rounds positions to 2-decimal places (1/100). `positionPrecision: 1` means whole units. The fixed-point bit width is computed from `maxPosition / precision`.
+- **Rotation is wrapped to `[-180, 180]`.** Values outside this range are treated as out-of-range at pack time; consumers handling continuous rotations must wrap to this range first.
+- **Schema shape is stable across presets.** All factory output shares the same top-level keys (`position`, `rotation`, `stats`, `optional`); only the per-field bit-widths differ. This lets a consumer swap presets at runtime without re-deriving downstream code.
+- **No defaults in the schema itself.** The output is a pure schema; default values for missing fields are the consumer's responsibility (e.g. via the optional-with-default strategy in `@suaveplan/bitpacker-strategies`).