Skip to content
VGAI voxel logo VGAI Learn

Validate assets and regenerate schemas

cli tutorial Intermediate ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

  • Run validate-assets to content-parse the asset formats
  • Regenerate the JSON Schema from the Zod sources
  • Understand when each runs (pre-commit, after schema edits)

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

vgai’s structured project formats are defined by Zod schemas in the engine — the single source of truth. A world has no document schema at all: its TSX/JSX source is the document. What is schema’d is the .inputmap.json input map and the vgai.project.json manifest. Ecosystem assets such as glTF, PNG, and audio retain their native formats. Two commands keep the structured formats in sync: generate-schema regenerates the JSON Schema (which powers VS Code autocomplete) from those Zod definitions, and validate-assets content-parses the asset files through the same schemas the runtime rejects them with. This is a terminal tutorial — the transcript below is real captured output (including a real, honestly-reported gotcha).

# transcript pending capture — run: node site/media/capture-cli.mjs
Terminal — Validate assets and regenerate schemas · captured by site/media/capture-cli.mjs

Steps

Section titled “Steps”

  1. Regenerate the JSON Schema from the Zod source.

    Terminal window
    npm run generate-schema

    This writes vgai-project.schema.json and inputmap.schema.json (into packages/engine/schemas/) from the Zod schemas. Run it after any schema change so editor autocomplete and the on-disk JSON Schema match the code; a pre-commit hook verifies it is up to date.

  2. Validate the asset files.

    Terminal window
    npm run validate-assets

    This is the structured-asset guardrail: it content-parses every .inputmap.json under public/ through the same Zod schema the runtime uses at fetch time. Native formats such as glTF, images, audio, and fonts remain governed by their native loaders rather than a vgai schema.

Recap

New functionality

  • Regenerated the JSON Schema from the Zod source (clean)
  • Ran validate-assets over the shipped asset files

New concepts & skills

  • Zod schemas are the single source of truth for the fetched asset formats and the manifest — a world has no document schema because its source IS the document
  • generate-schema keeps the on-disk JSON Schema (and autocomplete) in sync
  • validate-assets content-parses every shipped asset through the same schemas the runtime rejects with

Next lesson → Worlds and roots (manual)

See also

Section titled “See also”