Validate scenes & regenerate schema

cli tutorial Intermediate ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• Run validate-scenes to check scenes against the component registry
• Regenerate the JSON Schema from the Zod scene schemas
• Understand when each runs (pre-commit, after schema edits)

What you'll build: A terminal walkthrough of the two schema-guardrail commands.

vgai’s scene formats (.vscn.json, .prefab.json) are defined by Zod schemas in the engine — the single source of truth. Two commands keep everything in sync: generate-schema regenerates the JSON Schema (which powers VS Code autocomplete) from those Zod definitions, and validate-scenes checks that scene files only use components/fields the registry defines. This is a terminal tutorial — the transcript below is real captured output (including a real, honestly-reported gotcha).

Validate scenes & regenerate schema

# transcript pending capture — run: node site/media/capture-cli.mjs

Terminal — Validate scenes & regenerate schema · captured by site/media/capture-cli.mjs

Steps

1. Regenerate the JSON Schema from the Zod source.

   npm run generate-schema

   This writes vscn.schema.json, prefab.schema.json, scn2d.schema.json, vgai-game.schema.json (T3.1), and inputmap.schema.json (into packages/engine/schemas/) from the Zod schemas — the transcript shows it completing cleanly. Run it after any schema change so editor autocomplete and the on-disk JSON Schema match the code; a pre-commit hook verifies it’s up to date. (animgraph.schema.json was removed by E5 along with the AnimGraph format it described — there is no schema to regenerate for it any more.)

2. Validate scenes against the component registry.

   npm run validate-scenes

   This is the scene guardrail: it walks the .vscn.json / .prefab.json files and checks each entity’s components and fields against the engine’s component registry + Zod schemas, exiting non-zero on a violation (so bad scenes can’t land in CI). It also content-parses every .mat.json / .inputmap.json / .instances.json under public/ through the same Zod schemas the runtime rejects them with at fetch time — previously these formats were only existence-checked when a scene referenced them, so a present-but-malformed asset passed the command and failed at load. (.animgraph.json no longer exists as a format — animation is authored as meta.animation inside an ordinary XState machine, not a separate fetched JSON asset — so there is nothing left for this step to content-parse for animation.)

Honest gotcha: validate-scenes over-reports from the monorepo source layout

In the captured run, validate-scenes exits non-zero with 53 “unknown field” errors — but these are false positives, not real scene drift. Run from the monorepo source tree, a cross-package GameComponent identity mismatch (the validator imports @vgai/engine via a different module instance than the components) makes isGameComponentClass() return false, so the validator can’t see the components’ static schema and mis-flags every valid field (e.g. moveSpeed/jumpVelocity — which do exist in the component’s Zod schema). The command and its output are real; we’re reporting the limitation rather than dressing it up. The fix is in how the engine module is resolved for the validator; the schema-generation half (generate-schema) is unaffected and runs clean.

Recap

New functionality

• Regenerated the JSON Schema from the Zod source (clean)
• Ran validate-scenes and learned to read its output critically

New concepts & skills

• Zod schemas are the single source of truth for .vscn/.prefab
• generate-schema keeps the on-disk JSON Schema (and autocomplete) in sync
• validate-scenes is the scene guardrail — but from the monorepo source layout it currently over-reports due to a cross-package GameComponent identity mismatch (false positives, not drift)

Next lesson → Scene schemas (manual)

See also

• Tooling & build (manual) · Scenes & prefabs