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

Game Schema Factory

(no submodules)

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

import { createGameSchema } from "@suaveplan/bitpacker-game";

const schema = createGameSchema({
    maxPosition: 512,
    positionPrecision: 1,
    maxHealth: 100,
});

Usage: Advanced Example

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).