DRincs-Productions/pixi-vn / skills/ui
pixi-vn-ui
VerifiedUse 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`.
pixijs.md
View on GitHub# Pixi'VN UI: building UI with PixiJS
Part of the `pixi-vn-ui` skill — read `SKILL.md` first. This file covers building UI screens out of
**plain PixiJS components**, either instead of an HTML framework or combined with one. Docs:
[pixi-vn.com/start/interface-pixijs](https://pixi-vn.com/start/interface-pixijs).
Since the entire rendering side of Pixi'VN is built on PixiJS (see `pixi-vn-canvas`), you don't need
React/Vue at all to build a UI — a **PixiJS UI Layer** lets you add ordinary PixiJS components
directly to the stage.
## `layers.add` / `layers.get` / `layers.remove`
`canvas.add`/`remove`/`find` (see `pixi-vn-canvas`) all operate on the single `gameLayer` — the
save-able scene graph. A PixiJS UI Layer is different: it's a plain `PIXI.Container` (the `Layer`
type is just an alias for `Container<ContainerChild>` — no special class) attached directly to the
PixiJS stage, a sibling of `gameLayer`, entirely outside the save system.
```ts
import { canvas, Container } from "@drincs/pixi-vn";
const uiLayer = canvas.layers.add("ui", new Container());
// ... later
const layer = canvas.layers.get("ui");
canvas.layers.remove("ui");
```
- **`canvas.layers.add(label, layer)`** — attaches a `Container` to the stage under `label` and
returns it (`Layer | undefined`).
- **`canvas.layers.get(label)`** — returns the `Layer | null` registered under `label`.
- **`canvas.layers.remove(label)`** — removes it from the stage.
Compared to `canvas.layers.gameLayer`, a PixiJS UI Layer:
- **Is not included in saves.** Its current state is never part of `Game.exportGameState()`/a save
file — see `pixi-vn-saves`. Persist anything that must survive a reload through
[game storage](https://pixi-vn.com/start/storage) instead (see `SKILL.md`'s "Connecting UI to game
data").
- **Has better performance** — Pixi'VN does no save/restore bookkeeping on it.
- **Can't use Pixi'VN-specific features** (aliases, `canvas.animate`'s save-tracked state,
transition helpers) — for animating raw PixiJS UI, the docs recommend importing `animate` from
`@drincs/pixi-vn/motion` directly instead of `canvas.animate`, since it skips that bookkeeping and
is cheaper (see `pixi-vn-canvas`).
- **Accepts any PixiJS-compatible component** — being a plain `Container`, anything that works with
raw PixiJS works here, including third-party PixiJS UI component libraries.
`canvas.layers.add`/`remove` refuse the reserved `CANVAS_APP_GAME_LAYER_ALIAS`
(`"__game_layer__"`) alias, same as `canvas.add`/`remove`.
## Combining PixiJS and HTML UI layers
A PixiJS UI layer and an HTML UI layer (see `SKILL.md`) aren't mutually exclusive — you can add
PixiJS components into the "ui" layer during the first render of an HTML screen, and clean them up
when that screen unmounts:
```tsx title="React"
import { useEffect } from "react";
import { Assets, canvas } from "@drincs/pixi-vn";
import { Sprite } from "pixi.js";
export default function MyScreen() {
useEffect(() => {
const layer = canvas.layers.get("ui");
if (layer) {
(async () => {
const texture = await Assets.load(
"https://pixijs.com/assets/bunny.png",
);
layer.addChild(new Sprite(texture));
})();
}
return () => {
canvas.layers.get("ui")?.removeChildren();
};
}, []);
return null;
}
```
Official templates create a PixiJS layer named `"ui"` on startup (see `SKILL.md`'s "Real-world
layer conventions") specifically so screens like this have a ready-made layer to attach to.
## Component libraries
Building an entire UI in raw PixiJS primitives (`Graphics`, `Text`, `Sprite`) gets tedious fast for
anything beyond a few elements — these libraries add higher-level, ready-made UI components on top
of PixiJS:
- [PixiJS](https://pixijs.com/) — the base rendering library itself.
- [PixiUI](https://github.com/pixijs/ui) — buttons, sliders, lists, scroll boxes, and other common
widgets built on PixiJS.
- [PixiLayout](https://github.com/pixijs/layout) — flex/CSS-like layout for PixiJS component trees,
useful once a UI has more than a handful of manually-positioned elements.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |