/ui

name: pixi-vn-ui
description: Use when building game UI (menus, HUD, dialogue box, settings/save screens) on top of Pixi'VN with an external JS framework (React, Vue) or with plain PixiJS components — mounting HTML or PixiJS UI layers over the canvas, navigating between UI screens/routes, theming a shadcn/ui-based template, and connecting UI components to game storage/settings. Covers `canvas.htmlLayers.add`/`get`/`remove` and the PixiJS-only layer helpers `canvas.layers.add`/`get`/`remove`.

Pixi'VN User Interface (UI)

Pixi’VN does not ship its own UI components (buttons, menus, forms, HUD). Instead of reinventing what already exists in the JavaScript ecosystem, it lets a project use any external framework (React, Vue, ...) — or plain PixiJS — to build the UI, and just provides the plumbing to mount that UI on top of the canvas and keep it in sync with game data. Official docs: [pixi-vn.com/start/interface](https://pixi-vn.com/start/interface).

Because the UI is built with standard, widely-used frameworks rather than a proprietary system, AI coding assistants already know these tools well — this is a deliberate design choice, not just a missing feature.

When to use this skill

Load this skill whenever a task involves:

• Building a menu, HUD, dialogue box, settings screen, or save/load screen for a Pixi'VN game.
• Mounting an HTML UI layer (React/Vue root) or a PixiJS UI layer on top of the canvas.
• Navigating/switching between UI screens (routing).
• Reading or writing game storage/settings from UI components, or keeping the UI in sync with

changes made elsewhere (a label, a step, loading a save).

• Theming/styling a template's generated UI (colors, radius, fonts).

For the rendering primitives the UI sits on top of (images, sprites, text, transitions), see `pixi-vn-canvas`. For building UI screens purely out of PixiJS components (no HTML framework), see **`pixijs.md`** in this same skill folder.

UI vs canvas

The UI and the canvas are two distinct, independent systems:

• **The canvas is save-able; the UI is not.** All canvas element state (by alias) is included in a

save and restored when loading one — see `pixi-vn-storage`/`pixi-vn-saves`. The UI's current state is never included; you must persist whatever UI state matters yourself, into [game storage](https://pixi-vn.com/start/storage) or browser storage (see "Connecting UI to game data" below).

• **The canvas is stepped; the UI is navigated.** In the canvas you add/replace components during

each narration step. The UI instead is built as several distinct "screens", and you move between them with a router (see "Navigating between UI screens" below) — you don't swap UI content per step the way you swap canvas elements.

• **The canvas is Pixi'VN-only; the UI is anything.** The canvas only accepts Pixi'VN's own

save-able component classes (`Container`, `Sprite`, `ImageSprite`, `Text`, ...). The UI layer can hold any HTML/PixiJS component or any UI component library, so it's where the actual interface complexity (forms, animations, component libraries) belongs.

HTML UI layers

An HTML UI Layer is a `<div>` added above the PixiJS canvas, sized and positioned to match it — this is how a React/Vue (or any DOM-based) UI gets mounted on top of the game.

const root = document.getElementById("root");
if (!root) {
  throw new Error("root element not found");
}
const htmlLayer = canvas.htmlLayers.add("ui", root, {
  position: "absolute",
  pointerEvents: "none",
  userSelect: "none",
});
// createRoot(htmlLayer).render(<App />)

<!doctype html>
<html lang="en">
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

• **`canvas.htmlLayers.add(id, element, style?)`** creates the layer and returns the `HTMLDivElement`

to render into. `style` is `Partial<Pick<CSSStyleDeclaration, "position" | "pointerEvents" | "userSelect">>`, defaulting to `{ position: "absolute", pointerEvents: "none", userSelect: "none" }`.

• **`canvas.htmlLayers.get(id)`** returns the layer's `HTMLElement | undefined`.
• **`canvas.htmlLayers.remove(id)`** removes it.

**Enabling interaction**: every HTML UI layer defaults to `pointer-events: none`, so by default none of its elements intercept mouse/touch — the PixiJS canvas gets all events. This matters when you want an image/video on the canvas to receive clicks/taps unobstructed by an overlay. Set `pointer-events: auto` explicitly, and only, on the components that must be interactive:

export default function NextButton() {
  return <button style={{ pointerEvents: "auto" }}>Next</button>;
}

@layer components {
  [data-slot="button"],
  [data-slot="card"],
  [data-slot="toggle"] {
    pointer-events: auto;
  }
}

PixiJS UI layers

You can also build a UI screen directly out of PixiJS components (no HTML framework at all), or mix PixiJS components into an HTML-based UI. This uses a **PixiJS UI Layer** — a plain PixiJS `Container` attached directly to the PixiJS stage, outside the save-able `canvas.gameLayer` — via `canvas.layers.add`/`get`/`remove`. See **`pixijs.md`** in this skill folder for the full API, the differences from `gameLayer`, combining PixiJS and HTML layers, and recommended component libraries (PixiUI, PixiLayout).

Real-world layer conventions (official React template)

The API above is library-level; here's _one_ concrete way it's used in practice, from the official "TS narration + React" template (what `npm create pixi-vn@latest` scaffolds) at `src/main.tsx` / `src/constants.ts`. This is **the template's convention, not a library requirement**.

• **Named constants for layer ids**, not string literals: `CANVAS_UI_LAYER_NAME`,

`HTML_UI_LAYER_NAME`, `HTML_CANVAS_LAYER_NAME`. A separate `CANVAS_MINIGAME_LAYER_NAME` constant reserves a layer for future minigame content.

• **A ded