Editor architecture — the data-flow spine

cli tutorial Advanced ⏱ 6 min vgai 0.1.0

Prerequisites: Take the editor tour

What you'll learn

• Know the editor's core modules and what each owns
• Understand the one-way data flow (store → sync → factory → viewport)
• See that state is a single useSyncExternalStore source

What you'll build: A terminal tour of the editor's core modules and reactive-state core.

The editor is small and deliberately one-directional: user input mutates a single store, and everything downstream rebuilds from it. Knowing these modules is enough to find your way around the editor source (which the engine philosophy expects you to read). This is a terminal tour of that spine (real captured output below).

Editor architecture — the data-flow spine

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

Terminal — Editor architecture — the data-flow spine · captured by site/media/capture-cli.mjs

Steps

1. The core modules. The ls shows the data-flow spine:

   • editor-store.ts — central state: entity tree, selection, tools, undo stack.
   • scene-sync.ts — converts store entities → Three.js objects (prefab resolution, shading).
   • entity-factory.ts — creates the actual Object3Ds from entity descriptors.
   • editor-viewport.ts — the renderer, OrbitControls, TransformControls, raycast selection.
   • main.tsx — the entry point (mounts <AppRoot />). The RAF render loop and global keyboard shortcuts (registerEditorHotkeys) actually live in components/ViewportPanel.tsx.
   • action-registry.ts / command-listener.ts — named editor actions and the command bus the palette / CLI / SDK drive.
   • play-mode.ts — runs the real engine loop inside the editor for play-testing.

2. State is one reactive source. The grep confirms editor-store exposes its state through useSyncExternalStore — React’s official external-store hook. The UI subscribes to it, and so does scene-sync; a store mutation is the only thing that triggers a rebuild.

One-way data flow

User input → EditorStore mutation → (React UI re-renders) + (scene-sync rebuilds Three.js) → EditorViewport renders. There’s no two-way binding and no second source of truth. The one hot path that bypasses a full rebuild is a live gizmo drag (updateTransformLive), which writes the transform directly; it pushes one undo snapshot at drag-start and then commits the live transform on drag-end (commitLiveTransform) without pushing another — otherwise everything flows through the store.

Recap

New functionality

• Listed the editor's core modules and what each owns
• Confirmed state is a single useSyncExternalStore source

New concepts & skills

• One-way flow: store mutation → scene-sync rebuild → viewport render
• entity-factory builds Object3Ds from descriptors; scene-sync orchestrates it
• the action-registry/command-listener bus is what the palette, CLI, and SDK drive

Next lesson → Scene I/O

See also

• Scene I/O · The adapter seam