Build a multi-root game — a 3D root with a 2D overlay

tutorial lesson Intermediate ⏱ 10 min vgai 0.1.0

Prerequisites: Take the editor tour · Scaffold a project

What you'll learn

• Declare a two-world game (threejs + pixijs) in vgai.game.json
• Navigate the per-world hierarchy groups and inspect entities in each world
• Persist a play-mode edit to a world's own overlay file

What you'll build: A 3D scene with a 2D pixijs HUD overlay stacked above it, edited live in one session.

Walkthrough — Build a multi-root game — a 3D root with a 2D overlay · generated by site/media/lessons/learn-multiworld.lesson.ts (5 steps)

A vgai game is a manifest-backed adapter-root list: vgai.game.json can declare any number of threejs, pixijs, and react adapters, and one Game mounts them as stacked layers — one shared loop, per-root zOrder, each root with its own scene and its own components. In this lesson you build the classic shape: a 3D world with a 2D HUD overlay above it, then edit both through one editor session. (Concept reference: Multi-world games & play control.)

Follow along in a project

Scaffold a project (how) and replace the roots array in its vgai.game.json:

vgai.game.json

{
  "manifestVersion": 2,
  "roots": [
    { "id": "main",    "adapter": "threejs", "scene": "scenes/main.vscn.json" },
    { "id": "overlay", "adapter": "pixijs", "scene": "scenes/hud.scn2d.json", "zOrder": 10 }
  ]
}

scenes/main.vscn.json is a normal 3D scene — save this next to the template’s default.vscn.json in public/scenes/:

public/scenes/main.vscn.json

{
  "version": 1,
  "name": "MultiWorldMain",
  "entities": [
    { "name": "Camera", "camera": { "type": "perspective" }, "transform": { "position": [0, 2, 6] } },
    { "name": "AmbientLight", "light": { "type": "hemisphere", "color": "#ffffff", "groundColor": "#444444", "intensity": 0.6 } },
    { "name": "Sun", "light": { "type": "directional", "color": "#ffffff", "intensity": 1.2 }, "transform": { "position": [5, 10, 5] } },
    { "name": "MainCube", "mesh": { "type": "box" }, "material": { "type": "standard", "color": "#4ecdc4" }, "transform": { "position": [0, 0.5, 0] } },
    { "name": "Ground", "mesh": { "type": "box" }, "material": { "type": "standard", "color": "#2b2d42" }, "transform": { "position": [0, -0.75, 0], "scale": [8, 0.5, 8] } }
  ]
}

scenes/hud.scn2d.json is a 2D scene — "surface": "world2d" with a sprite entity:

public/scenes/hud.scn2d.json

{
  "version": 1,
  "surface": "world2d",
  "entities": [
    { "name": "HudBadge", "transform2d": { "position": [120, 80] }, "sprite": { "tint": "#ffd23f", "width": 64, "height": 64 } }
  ]
}

Steps

1. Press Play. One Game mounts the root list: the Three.js root renders on the bottom canvas, and the pixijs overlay stacks above it (zOrder: 10) on its own transparent canvas — you see the yellow sprite floating over the 3D scene.

   

   Two worlds, one Game: the pixijs overlay's canvas stacks above the threejs canvas.

2. Read the hierarchy. The hierarchy shows native Three.js and PixiJS roots, with each root’s entities beneath it.

   

   Native adapter roots organize their own entities.

3. Select the cube in the threejs world. The inspector shows its transform like any entity — the same panels you know from single-world editing.

4. Select the sprite in the pixijs overlay. The same hierarchy + inspector route to the 2D world: HudBadge shows 2D position, scale, alpha, and tint.

   

   The same panels drive the 2D world — position, alpha, tint.

5. Edit Position-Y and save. Change the sprite’s Position Y to 240. In a multi-world session, play-mode edits persist to per-world overlay files — this one lands in .vgai/overlays/overlay.json in your project, keyed by the world id.

   

   The edit persists to the overlay world's own file: .vgai/overlays/overlay.json.

Persistence changes at the 1→2 world boundary

A single-world game’s play edits are ephemeral — discarded on stop. A multi-world game persists play edits as per-world overlays (.vgai/overlays/<world-id>.json). Both are deliberate; see the runtime manual for why.

Cross-world code works the same way: game.queryByComponent(Cls) spans every first-party world in one call (narrow with {worldId} or {kind}). And the world node is the entity in every kind — Object3D in threejs worlds, PIXI.Container in pixijs worlds.

Recap

New functionality

• Declared a two-world game (threejs + pixijs overlay) in vgai.game.json
• Played it — two stacked canvases, one Game, one loop
• Inspected entities in both worlds and persisted a 2D edit to the world's overlay file

New concepts & skills

• a game is a manifest-backed adapter-root list mounted by one Game
• roots stack as layers by zOrder; upper canvases are transparent
• the hierarchy presents native adapter roots
• multi-root play edits persist per root

Next lesson → Pause, resume & step

On Your Own!

Extend what you built:

• Add a second pixijs overlay at zOrder 20 and watch the layer order
• Give the 2D scene more sprites and tint them from the inspector
• Add a react world to the list — see the React worlds tutorial

See also

• Multi-world games & play control (manual) · 2D worlds (world2d) · React worlds tutorial