Ingest an unmodified three.js game

tutorial lesson Advanced ⏱ 9 min vgai 0.1.0

Prerequisites: Loading existing games — overview

What you'll learn

• Ingest an unmodified three.js game into the editor
• Understand the render-accessor trap that captures its scene
• Know how in-realm capture and ownership-based persistence work

What you'll build: An unmodified three.js game running inside the editor, captured live.

Walkthrough — Ingest an unmodified three.js game · generated by site/media/lessons/ingest-game.lesson.ts (4 steps)

Ingest a real game in the hosted editor

Do it in your browser — no install: ▶ Ingest the unmodified Interactive Cubes game. A vendored game carries its own vgai.project.json, so it opens under the one boot param, ?project=<id>, exactly like a bundled example. The link boots the editor and loads the upstream three.js example byte-for-byte unmodified — the render-accessor trap captures its live scene, so the hierarchy panel fills with the game’s own Object3D tree while the game runs untouched in the viewport. Give it a moment to import and capture.

vgai can load a real, unmodified three.js game and edit it in-place. It doesn’t ask the game to use a vgai API — it traps the game’s render call, reads the Scene the game hands its WebGLRenderer, and exposes that live Object3D tree to the editor through a neutral AuthoringAdapter. An edit is then written back to the game’s own source — a surgical literal edit anchored by the serve-time creation-site index — because a persistence artifact that is not the game’s own code or data is exactly what this lane refuses to invent. Where a property cannot yet be honestly anchored, that single edit refuses with its reason rather than being stashed somewhere else.

Steps

1. Open the editor. A normal editor session. Use the ?project=three-interactive-cubes link above to launch it in your browser (the same flow runs headlessly via the ingest dev hook).

   

   An ordinary editor session.

2. Ingest an unmodified three.js game. The link loads the upstream Interactive Cubes example — no vgai changes to its code.

   

   Loading an unmodified three.js game.

3. The foreign game runs live — via the render-accessor trap. adapter/ingest/scene-capture.ts wraps the host WebGLRenderer.render so the first (scene, camera) the game renders is captured. The game runs exactly as written; vgai just observes its scene.

   

   An unmodified three.js game, running inside the editor.

4. The editor panels drive the ingested tree. The captured Object3D tree is presented through the same neutral AuthoringAdapter the 3D and 2D surfaces use, so the hierarchy/inspector work on a foreign game with no special-casing.

   

   One authoring contract drives a foreign game's tree.

Marquee ingests — real games, zero source diff

Real upstream games enter the same way, vendored under lock with every divergence recorded: pmndrs/racing-game (a full R3F racer, vendored from source with the editor’s own source-authoring lane live on its TSX), dgreenheck/simcity-threejs-clone, and the colyseus/realtime-tanks-demo multiplayer client. They’re listed in the examples gallery.

In-realm capture & ownership-based persistence

• Capture is in-realm: the game’s modules are served against the editor’s own three instance, so the capture trap sees the real scene and every editor capability operates on the live objects. A game whose bundle pins a second three is not capturable — the mount fails loudly by name; ingest from source. Every editor capability the mount has not reached is a standing warning naming the mechanism that would close it.
• Persistence is ownership-based: a vendored reference copy is live-only — edits drive the running game and are never written anywhere. A game you own persists through ordinary source edits in your files; there is no sidecar.

Recap

New functionality

• Ingested an unmodified three.js game into the editor
• Saw its live Object3D tree in the editor panels

New concepts & skills

• The render-accessor trap captures the Scene the game renders — no game-side API
• A neutral AuthoringAdapter drives the foreign tree (same contract as 3D/2D)
• An unreached capability is a standing warning, never a silent degrade; persistence follows ownership — live-only on a vendored copy, your own source edits in a folder you own

Next lesson → Loading existing games (manual)

Ingest your own folder

The mechanism is not vendored-games-only: the same { ingest } manifest works for a three.js game folder that has never seen this repo. Put a vgai.project.json next to your game:

{
  "manifestVersion": 2,
  "name": "My Existing Game",
  "version": "0.1.0",
  "engine": { "version": "0.1.0" },
  "roots": [
    {
      "id": "main",
      "adapter": {
        "surface": "three",
        "ingest": { "entry": "src/main.js" }
      }
    }
  ]
}

then open the folder in the editor (npx @vgai/cli@latest edit <folder>, or the editor’s open-project flow). The resolver mounts it through the same ingest machinery you just used. The ingest block declares mounting FACTS only — entry names your game’s own module entry point, and the host serves it in-realm with three deduped to the editor’s instance; there is no route menu to pick from, and a game the capture trap cannot see fails to mount, loudly. Persistence is ownership-based: edits to a game you own are ordinary source edits in your files. The JSON-Schema for the manifest (autocomplete + field docs) ships in the engine package.

Scope honesty: this bring-your-own path works for three.js, PixiJS, and React games — declare an { ingest, surface } adapter root in your own vgai.project.json and open the folder (React’s manifest/external-folder route is the newest of the three). The vendored games shown in this section exist to prove the mechanism in CI, not because any of the three kinds is vendored-only — see docs/BRINGING-AN-EXISTING-GAME.md in the checkout for the full per-kind capability map and the adapt-vs-port decision guide.

See also

• Ingesting games (manual) · Adapter architecture