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 GameAdapter / MountedGame / HostContext contract
• See the system-adapter factories (Physics/Net/Input/Asset/Animation/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 .vscn scene, 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).

The adapter seam (game, authoring & system adapters)

# 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

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

   • Host⇄runtime: GameAdapter<K> (mount a game — generic over the world kind, default 'threejs'), the kind-tagged MountedWorld handles (MountedThreeWorld — which MountedGame permanently names — MountedPixiWorld, MountedReactWorld), and HostContext (canvas/loop/systems the host provides) — the host knows nothing about .vscn or GameComponent.
   • First-party + system adapters: VgaiSceneGameAdapter / fromSetup (the default game adapter) and the system-adapter factories — createRapierPhysicsAdapter, createColyseusNetworkingAdapter, createInputManagerAdapter, createVgaiAssetAdapter, createAnimationAdapter, 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), ingest-authoring-adapter + ingest-game/iframe (foreign games), world2d-authoring-adapter (2D), react-world-authoring-adapter (React), and composite (multi-root). Same contract → the hierarchy/inspector work everywhere.

Why the seam matters

The split is the inversion that makes ingest possible: the host owns the canvas/loop and asks a GameAdapter to mount something; first-party scenes and foreign games are both just adapters. The AuthoringAdapter is the editor-side mirror — opaque node ids over any tree — so the editor never special-cases what it’s editing.

Recap

New functionality

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

New concepts & skills

• GameAdapter/MountedGame/HostContext = host⇄runtime contract (host knows no .vscn)
• 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

• Adapter architecture (manual) · Ingest an unmodified game