Skip to main content

JSON schemas

Zylem config that crosses the wire—entities, stages, game and stage config, input, songs, cutscenes—is described with TypeBox schemas in @zylem/game-lib/schema. On build, scripts/emit-json-schemas.ts writes plain JSON Schema Draft 07 files to dist/schema/*.schema.json for editors, Monaco, and external validators.

Importing in TypeScript​

import {
  EntityJsonSchema,
  GameConfigJsonSchema,
  SongDefinitionSchema,
  CutsceneDefinitionSchema,
} from '@zylem/game-lib/schema';

Runtime blueprints use slightly looser shapes (EntitySchema, StageSchema) with open data records; editor-oriented unions (EntityJsonSchema, StageJsonSchema) discriminate known entity types (text, sprite, line) for validation and autocomplete.

Types re-exported from the same module include EntityBlueprint, StageBlueprint, GameConfigJson, StageConfigJson, GameInputConfigJson, and entity data helpers.

Published JSON Schema files​

After pnpm build in @zylem/game-lib, import static JSON from package subpaths:

Export subpathFileSource schema
@zylem/game-lib/schema/entityentity.schema.jsonEntityJsonSchema
@zylem/game-lib/schema/stagestage.schema.jsonStageJsonSchema
@zylem/game-lib/schema/game-configgame-config.schema.jsonGameConfigJsonSchema
@zylem/game-lib/schema/stage-configstage-config.schema.jsonStageConfigJsonSchema
@zylem/game-lib/schema/input-configinput-config.schema.jsonGameInputConfigSchema
@zylem/game-lib/schema/songsong.schema.jsonSongDefinitionSchema
@zylem/game-lib/schema/cutscenecutscene.schema.jsonCutsceneDefinitionSchema

Example in a Vite or bundler project:

import entitySchema from '@zylem/game-lib/schema/entity';

Use these in $schema URLs, AJV, or IDE YAML/JSON language services.

Schema modules covered​

Beyond blueprints, the package exports schemas for:

  • Input — keyboard/mouse mappings, virtual touch layouts, player bindings
  • Stage config — colors, gravity, GLTF loader options, asset loader config
  • Game config — resolution, device profiles, fullscreen, debug flags

Song and cutscene schemas are duplicated from @zylem/game-lib/audio and @zylem/game-lib/cinematics so one import path covers all serialized documents.

Emit pipeline​

The emit script imports compiled schemas from dist/schema.js (built by tsup), strips TypeBox symbols, adds $schema, and writes one file per document. Run via pnpm schema:emit inside packages/game-lib (also part of the library build script).

Pitfalls​

  • Build order — JSON files exist only after game-lib build; TypeScript types come from dist/schema.d.ts.
  • Runtime vs editor entity shape — prefer EntityJsonSchema for saved files; EntitySchema for factory spreading at runtime.
  • Validation only — schemas do not load assets or spawn entities; pair with blueprints and stage factories.

API reference​