Editor SDK & storage backends

cli tutorial Intermediate ⏱ 6 min vgai 0.1.0

Prerequisites: Scaffolded a vgai project

What you'll learn

• Know the editor-sdk EditorClient API for programmatic control
• Understand the pluggable storage backends (OPFS / FSA / Mem / HTTP)
• See how the browser-first editor persists projects

What you'll build: A terminal tour of the EditorClient API surface and the storage backends.

Two complementary pieces: the editor-sdk (EditorClient) lets code/agents drive the editor programmatically, and the editor’s storage backends let it run browser-first (persisting projects without a server). The transcript below lists both API surfaces, captured live.

Editor SDK & storage backends

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

Terminal — Editor SDK & storage backends · captured by site/media/capture-cli.mjs

Steps

1. List the EditorClient API.

   import { EditorClient } from '@vgai/editor-sdk';
   const editor = new EditorClient();          // talks to a running editor
   await editor.openScene('scenes/level1.vscn.json');
   await editor.play();

   The transcript shows the full method surface: play / stop / pause / step, select / selectAll / focusEntity, openScene / createProject / openProject, view + gizmo setters, and getState / waitForState for synchronizing. This is the programmatic mirror of the vgai CLI.

2. List the storage backends.

   The editor persists projects through a pluggable backend (getStorageBackend / setStorageBackend):

   • OpfsStorage — Origin-Private File System (browser-first default).
   • FsaStorage — the File-System-Access API (a real local folder). The picked folder is remembered across reloads (restorePersistedProjectRoot) so browser-first authoring on disk survives a refresh.
   • MemStorage — in-memory (tests / ephemeral).
   • HttpStorage — a server/dev backend.

   This is what lets the same editor run as a static browser app and against a dev server.

Why two backends matter

getHostCapabilities picks a sensible default (OPFS in a plain browser, FSA when the user grants a folder, HTTP under the dev server). The browser-first build (npm run build:web) ships with the browser backends, which is why the hosted editor can open and save a project with no server.

Recap

New functionality

• Listed the EditorClient programmatic API
• Listed the editor storage backends

New concepts & skills

• editor-sdk EditorClient = programmatic editor control (mirror of the vgai CLI)
• storage is pluggable: OPFS / FSA / Mem / HTTP via get/setStorageBackend
• browser backends make the editor browser-first (no server needed)

Next lesson → Hot-reload in the browser

See also

• CLI, SDK & scaffolding (manual) · Hot-reload in the browser