Pixi Vn Minigames

Pixi'VN Minigames

Official docs: pixi-vn.com/start/minigames.

Pixi'VN has no dedicated minigame API — a minigame is just PixiJS code (and, for its HUD/UI, a regular framework UI) wired into the game through the same primitives used elsewhere: canvas layers, hotkeys, and navigation. This skill is about how those pieces fit together for a minigame specifically, not about introducing new APIs.

When to use this skill

Load this skill whenever a task involves building or wiring in a minigame: a snake/arcade-style game, a timing/reaction challenge, a puzzle, a quiz mini-mode, or anything else the player breaks away from the main narration to play. Not for the narrative canvas itself (pixi-vn-canvas) or for general app UI screens unrelated to a minigame (pixi-vn-ui).

Core mental model

• A minigame renders on its own PixiJS layer, not on canvas.gameLayer. gameLayer is the save-able narrative scene graph (backgrounds, characters — see pixi-vn-canvas); a minigame's moving pieces (snake segments, falling blocks, ...) are transient and don't belong there. Use canvas.layers.add(name, new Container()) to get a separate, non-save-able layer for the minigame, exactly like a PixiJS UI layer (pixi-vn-ui) — the official template even reserves a constant for it, CANVAS_MINIGAME_LAYER_NAME.
• The minigame's HUD/menus (score, game-over overlay, control buttons) should be regular UI, not PixiJS — built with React/Vue/whatever the project's UI already uses (pixi-vn-ui), positioned over the canvas the same way any other UI is.
• A minigame is launched from the narrative, then the player returns to it. The recommended approach is to link the minigame to its own route (e.g. /minigame/snake) and navigate to it from a step, then navigate back when it ends — see pixi-vn-ui's "Navigating between UI screens" section and interface-navigate. Every minigame example below is written as a route file for this reason, not a bare component.
• Saving and restoring the minigame's current state (score, board, position, ...) is entirely the developer's responsibility. Game.exportGameState() does not know about a minigame in progress — see pixi-vn-saves. If a minigame's progress must survive a save/reload, persist it yourself (e.g. via game storage, see pixi-vn-storage).

Routing structure: one route per minigame, plus a shared layout route

With file-based routing (e.g. TanStack Router, used by the official templates), each minigame gets its own file under src/routes/minigame/, so a project with several minigames ends up with /minigame/snake, /minigame/quiz, etc.:

import { createFileRoute } from "@tanstack/react-router";
import SnakeGame from "@/screens/minigames/SnakeGame";

export const Route = createFileRoute("/minigame/snake")({
  component: SnakeGame,
});

Anything shared by every minigame (pausing narration/audio while one is open, common hotkeys, a shared HUD wrapper) doesn't belong copy-pasted into each of those files. Factor it into a single pathless layout route, src/routes/minigame.tsx, that renders an <Outlet /> for whichever minigame route is active — the same pattern the official React template already uses for /game (src/routes/game.tsx wraps every /game/* screen with usePauseGameWhenMenuIsOpen + useGameHotkeys + <Outlet />):

import { createFileRoute, Outlet } from "@tanstack/react-router";

export const Route = createFileRoute("/minigame")({
  component: MinigameLayout,
});

function MinigameLayout() {
  // hooks/providers shared by every minigame go here
  return <Outlet />;
}

What actually goes in src/routes/minigame.tsx is a judgment call to make while building the first minigame, not a file to scaffold reflexively — work through these questions before adding anything to it:

• Is there actually anything shared across minigames? If the game's settings menu, pause menu, or quick-actions wheel aren't reachable while a minigame is open, and there's no common hotkey/HUD/provider every minigame needs, src/routes/minigame.tsx has nothing to do — leave it empty (just the <Outlet />) or skip creating it at all and let each minigame route stand alone.
• Are there menus specific to minigames only (a minigame pause menu, a "quit minigame and return to story" confirmation, a minigame-specific settings panel)? If so, that's exactly what belongs in the shared layout, the same way src/routes/game.tsx centralizes usePauseGameWhenMenuIsOpen and useGameHotkeys for every /game/* screen.
• Should the same menus as src/routes/game.tsx (settings, save/load, quick actions) be reachable from inside a minigame? If yes, don't assume they behave identically — check case by case whether each one still makes sense mid-minigame. Saving is the clearest example: Game.exportGameState() knows nothing about in-progress minigame state (see the Gotchas section below), so a save triggered from inside a minigame either needs to be disabled/hidden there, or the minigame needs to persist its own state first (pixi-vn-storage) so the save is still meaningful. Don't wire in the game's menus unchanged and assume they "just work" inside a minigame.