Scene I/O — the .vscn format & roundtrip idempotence

cli tutorial Intermediate ⏱ 5 min vgai 0.1.0

Prerequisites: Take the editor tour

What you'll learn

• Know the .vscn round-trip — parse → serialize → parse is stable
• See the three scene I/O modules (parse, serializer, diff)
• Understand how autosave writes back to the loaded .vscn path

What you'll build: A terminal proof that a .vscn parses, re-serializes, and re-parses identically.

A vgai scene is a plain .vscn.json file. The format isn’t ad-hoc: it’s defined by Zod schemas in the engine, so loading a scene validates it, and saving one produces a file that loads back to the same thing. This is a terminal proof of that round-trip (real captured output below).

Scene I/O — the .vscn format & roundtrip idempotence

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

Terminal — Scene I/O — the .vscn format & roundtrip idempotence · captured by site/media/capture-cli.mjs

Steps

1. Parse → serialize → parse is stable. parseSceneFile (engine/src/scene/parse.ts) runs the raw JSON through SceneFileSchema.safeParse — applying defaults and rejecting anything invalid. Re-stringifying the parsed result and parsing it again yields a byte-identical object (stable: true). The format is idempotent: a save never silently mutates a scene.

2. The three I/O modules. The ls shows the scene I/O spine:

   • parse.ts — parseSceneFile (validate raw JSON → typed SceneFile).
   • scene-serializer.ts — serializeScene(scene, meta) (a live THREE.Scene → SceneFile).
   • scene-diff.ts — the structural diff that merges external edits (a .vscn changed on disk underneath you) back into the live editor. Since T4.5 it has a proven inverse: applyDiff (engine/src/scene/scene-apply.ts) applies a SceneDiff patch to a scene file — surfaced as npm run vgai -- apply-diff <scene> <patch> [--report], the canonical programmatic edit op (validates scene + patch + result; writes nothing on failure).

Autosave writes back to the loaded path

The editor autosaves to the same .vscn.json you opened — there’s no separate “editor format”. Autosave serializes the full document with serializeScene and writes it to the loaded path (editor-store debounces it on a timer); parseSceneFile is the gate every load passes through. scene-diff is the other direction — it reconciles an externally-changed file back into the session. Because the round-trip is idempotent, hand-editing a .vscn and re-opening it is safe.

Recap

New functionality

• Proved a .vscn round-trips (parse → serialize → parse) identically
• Listed the three scene I/O modules

New concepts & skills

• parseSceneFile validates raw JSON against the Zod SceneFileSchema (defaults + rejection)
• serializeScene turns a live THREE.Scene back into a SceneFile
• autosave writes the full serialized document to the loaded .vscn path; scene-diff merges external edits — one format, idempotent

Next lesson → Editor architecture

See also

• Editor architecture · Scenes & prefabs (manual)