The adapter architecture

vgai’s editor and host don’t depend on any one game’s internals. They depend on interfaces, and games — first-party TSX/R3F worlds or unmodified third-party three.js games — are peer implementers of those interfaces.

The adapter seam.

The core interfaces

• RootAdapter<K> (packages/engine/src/adapter/root-adapter.ts) — the host⇄runtime lifecycle, generic over the adapter surface (default 'three'). A “game” is anything that mounts via mount(host), returning its kind-tagged surface — MountedThreeWorld (which MountedRoot permanently names), MountedPixiWorld, or MountedReactWorld. The threejs surface exposes the live scene + camera and lifecycle hooks (update/fixedUpdate/ setPaused/step) plus optional authoring/systems providers.
• Host contexts (host-context.ts) — what the host provides, split PER SURFACE: HostContextBase carries only what every surface genuinely gets (the root handle, headless), and ThreeHostContext / CanvasHostContext / DomHostContext add that surface’s own primitives — three, renderer, surface and asset cache for three; the canvas plus compositing hints for canvas; a plain container for dom. HostContextFor<K> selects one, so mount’s parameter is kind-typed and a Pixi root is never handed a WebGL renderer it can’t use. HostContext is a permanent alias of the three context. Rapier/Colyseus are kept behind system adapters, not baked into the host.
• AuthoringAdapter (authoring.ts) — the editor’s authoring contract: hierarchy / selection / transform / inspector / structure / persistence, keyed by opaque string node ids. The editor UI never branches on which implementer it’s editing.

First-party implementers

vgai’s own content plugs into the same seams:

• SetupThreeRootAdapter wraps an imperative setup() export as a RootAdapter; fromSetup() adapts every existing example with zero edits.
• VgaiSceneAuthoringAdapter implements AuthoringAdapter by delegating to the editor’s existing store/scene logic — so the hierarchy/inspector/gizmo/save all route through it.

System adapters

Optional subsystem capability providers hang off MountedRoot.systems (system-adapter.ts) — the editor coordinates with a game’s systems without owning them: Physics, Networking, Input, Asset, Navigation. First-party implementers wrap Rapier, Colyseus, the input manager, the asset cache, and the navmesh manager.

Animation stays in world code

Animation runs as an ordinary XState machine bound to a THREE.AnimationMixer (bindXStateAnimation, see the animation manual), owned by the game’s own world code. It does not need a dedicated system adapter.

The anti-shim rule

No adapter may fabricate first-party data structures to sneak through first-party code paths. Each adapter implements the editor-facing interface directly over its own model — verified by tests that assert ingested objects have stable ids but no fabricated userData.entity.

See also

• Ingesting unmodified games — the render-accessor trap + overlays.
• Editor Guide — the authoring surface that rides on AuthoringAdapter.