Show a React UI root

quick start Beginner ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• See a declared React root mounted over the 3D scene
• Recognize the shared UI primitives (Panel, KeyHint, …)
• Understand the pointer-events overlay model

What you'll build: A look at the editor-tutorial HUD — React over the 3D viewport.

Walkthrough — Show a React UI root · generated by site/media/lessons/scenes2-batch.lesson.ts (4 steps)

In vgai, UI is a declared React adapter root. The host composes it over the gameplay canvas and owns its mount and disposal lifecycle.

Follow along in the live web editor

Open the scene in your browser — no install: ▶ Open the editor-tutorial scene. The HUD is React UI that mounts in Play mode, and Play works right in the browser — press Play and the panel overlays the viewport; the hosted editor transpiles the example in-browser and boots the real runtime.

Steps

1. Open a scene with a React HUD. The scene is already open — if you followed the link above, the editor-tutorial scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/editor-tutorial npm run dev).

   

   The scene whose example mounts a HUD.

2. Enter play mode. The manifest composer mounts the declared React root and wraps it in the engine GameProvider automatically.

   

   The declared React root mounts with the game.

3. The HUD Panel and KeyHints overlay the 3D scene. The panel uses the shared primitives (Panel, Button, Toggle, KeyHint). The overlay is pointer-events: none by default, so clicks fall through to the 3D scene; interactive widgets opt back in to auto.

   

   A Panel of KeyHints over the viewport.

4. Stop play mode. Press Stop (or Escape) — the host disposes every root.

Recap

New functionality

• Saw a React HUD over the 3D scene
• Recognized the shared UI primitives

New concepts & skills

• React UI is an explicit adapter root
• The host owns mount and disposal
• The layer is click-through; interactive widgets opt in to pointer events

Next lesson → Manual: React HUD

On Your Own!

Extend what you built:

• Add a Button to the HUD and wire an onClick
• Set pointer-events:auto on a widget and confirm clicks no longer fall through
• Select an OID-backed element in the React hierarchy and edit its style

See also

• React UI roots · React UI authoring