Skip to content
VGAI voxel logo VGAI Learn

The adapter seam (game, authoring & system adapters)

cli tutorial Advanced ⏱ 7 min vgai 0.1.0

Prerequisites: Loading existing games — overview

What you'll learn

  • Know the host⇄runtime RootAdapter / MountedRoot / HostContext contract
  • See the system-adapter factories (Physics/Net/Audio/Navigation)
  • Understand the neutral AuthoringAdapter that drives every surface uniformly

What you'll build: A terminal tour of the adapter seam — the contracts behind first-party, ingest, and 2D.

The reason one editor can drive a first-party TSX/R3F world, an unmodified ingested three.js game, and a 2D PixiJS scene — with the same hierarchy/inspector/gizmo — is a small set of adapter contracts. This is a terminal tour of that seam (real captured output below).

# transcript pending capture — run: node site/media/capture-cli.mjs
Terminal — The adapter seam (game, authoring & system adapters) · captured by site/media/capture-cli.mjs

Steps

Section titled “Steps”

  1. The runtime adapter seam. @vgai/engine/adapter exports two layers:

    • Host⇄runtime: RootAdapter<K> (mount a root — generic over the adapter surface, default 'three'), the surface-tagged MountedRoot handles (MountedThreeRoot — which MountedRoot permanently names — MountedPixiRoot, MountedReactRoot), and the per-surface host contexts — HostContextBase (the root handle + headless, all any surface is promised) plus ThreeHostContext (three, renderer, surface, asset cache), CanvasHostContext and DomHostContext, selected by HostContextFor<K> so mount’s PARAMETER is kind-typed too. HostContext is a permanent alias of the three one. The host knows nothing about any document format or engine-specific component class.
    • First-party + system adapters: SetupThreeRootAdapter / fromSetup (the default game adapter) and the system-adapter factories — createRapierPhysicsAdapter, createColyseusNetworkingAdapter, createAudioSystemAdapter, createNavigationAdapter — one per subsystem.

  2. The editor authoring adapters. The editor edits through a neutral AuthoringAdapter; the ls shows its implementations: vgai-scene-authoring-adapter (first-party), live-three-authoring-adapter (any live Object3D tree, first-party or foreign — ingested games included), pixi-authoring-adapter (any live PIXI.Container tree, first-party or ingested — one class, parameterized by identity and write target), react-world-authoring-adapter (React), and composite (multi-root). Same contract → the hierarchy/inspector work everywhere.

Recap

New functionality

  • Listed the runtime adapter seam
  • Listed the editor authoring adapters

New concepts & skills

  • RootAdapter/MountedRoot/HostContext = host⇄runtime contract (host knows no document format)
  • system-adapter factories wrap each subsystem (physics/net/input/asset/animation/nav)
  • one neutral AuthoringAdapter drives first-party, ingest, 2D, and UI uniformly

Next lesson → Ingest an unmodified game

See also

Section titled “See also”