Add a React root — JSX as truth, live game state, source write-back

tutorial lesson Intermediate ⏱ 12 min vgai 0.1.0

Prerequisites: Build a multi-world game

What you'll learn

• Declare React roots (entry .tsx modules) in the manifest root list
• Read live game state in a react world with useGameState — zero polling
• Edit a JSX style from the inspector and watch it write back to the .tsx source
• Opt interactive elements into clicks with pointer-events auto

What you'll build: A threejs world with a live-score React HUD world and an interactive React menu world stacked above it.

Walkthrough — Add a React root — JSX as truth, live game state, source write-back · generated by site/media/lessons/learn-reactworld.lesson.ts (5 steps)

React is a first-class adapter root: an entry with "adapter": "react" mounts as its own DOM layer in the host stack, z-ordered beside 3D and 2D canvases. A React root has no scene file — JSX source is the authoritative document, and the editor works directly against it. In this lesson you add two React roots to a 3D game: a HUD that displays a live score, and a menu with a clickable button. (Concept reference: React worlds.)

Follow along in a project

Add react worlds to the manifest — each entry is a .tsx module default-exporting a component:

vgai.game.json

{
  "manifestVersion": 2,
  "roots": [
    { "id": "main", "adapter": "threejs", "scene": "scenes/main.vscn.json" },
    { "id": "hud",  "adapter": "react", "entry": "hud.tsx", "zOrder": 10 },
    { "id": "menu", "adapter": "react", "entry": "menu.tsx", "zOrder": 20 }
  ]
}

The HUD reads live game state — the resolver auto-wraps every react world in <GameProvider>, so useGameState(selector) just works (re-renders on selected-value change, zero polling). Here it reads a counter off a Ticker GameComponent in the 3D world:

hud.tsx

import { useGameState } from '@engine/react/game-state';
import { Ticker } from './src/scripts/components/ticker';

export default function Hud() {
  const count = useGameState((g) => g.queryByComponent(Ticker)[0]?.count ?? 0);
  return (
    <div style={{ position: 'absolute', top: 16, left: 16 }}>
      <span style={{ fontSize: 22, color: '#3ddc65', fontFamily: 'monospace' }}>
        Score: {count}
      </span>
    </div>
  );
}

Steps

1. Press Play. The threejs world renders on its canvas; both react worlds mount as transparent DOM layers above it. The HUD’s Score: counter ticks live — driven by useGameState reading the Ticker component in the 3D world.

   

   React worlds are DOM layers in the same host stack — no canvas, no scene file.

2. Read the hierarchy. The native React group contains Hud and Menu, and beneath them the JSX elements as OID-derived nodes — span and button — named Component:tag from instrumentation of the served .tsx.

   

   The hierarchy is derived from the JSX — component:tag nodes, no scene tree.

3. Select the HUD’s span. The inspector shows its JSX style props (color, font size, spacing…). There is no scene document behind this panel — you are inspecting the .tsx source.

4. Edit the color. Change the span’s color and the edit writes back into hud.tsx on disk — a real source edit (you’ll see it in git), not an overlay or scene change. Reload and press Play again: the rewritten source now drives the HUD to the new color — no in-memory illusion, the .tsx file is what changed.

   

   Style edits land in the JSX source — reload, and the source drives the new color.

5. Click the menu button. React world layers have pointer-events: none by default; interactive elements opt back in with pointer-events: auto. The button takes clicks, while clicks on empty layer space fall through to the worlds below.

React roots host no GameComponents

Attaching a GameComponent to a React node throws: behavior lives in gameplay roots and the React tree renders from state. Do not create an imperative second React root; declare it in the manifest.

Recap

New functionality

• Mounted two react worlds (HUD + menu) as DOM layers over a 3D world
• Read live game state in the HUD via useGameState — no polling
• Edited a JSX style in the inspector and saw it write back to hud.tsx
• Clicked a pointer-events: auto button while empty space fell through

New concepts & skills

• adapter: react makes React a root-list peer of threejs/pixijs
• JSX is truth — no scene file; the editor derives hierarchy from OID instrumentation
• the host auto-wraps React roots in GameProvider
• layers default to pointer-events: none; interactive elements opt in

Next lesson → React worlds (manual)

On Your Own!

Extend what you built:

• Add a second stat to the HUD read from another component via useGameState
• Edit the button's className in the inspector and diff hud.tsx/menu.tsx in git
• Give the menu a Resume button that calls game.play.resume() — pair it with the play-control lesson

See also

• React worlds (manual) · React HUD overlay · Build a multi-world game · Pause, resume & step