pixi-vn-saves
Use when implementing save/load in a Pixi'VN game — Game.exportGameState()/restoreGameState()/jsonToGameState(), what the exported GameState contains, and how to persist it (save slots, quick-save, au
SKILL.mdskills/saves/SKILL.md
GitHubPixi'VN Saves: exporting, restoring, and persisting game state
Official docs: pixi-vn.com/start/save.
When to use this skill
Use this skill whenever a task involves saving/loading the game: a save-file format, save slots, a
quick-save shortcut, "continue where I left off" after a page refresh, or exporting/importing a save
as a file. This skill does not cover the module-level details of what's inside a save (storage
variables — pixi-vn-storage; canvas element state — pixi-vn-canvas; step/backlog history —
pixi-vn-history) — only the save/load flow itself and how those pieces fit together.
The core trio
import { Game } from "@drincs/pixi-vn";
Game.exportGameState(): GameState
Game.restoreGameState(data: GameState): Promise<void>
Game.jsonToGameState(json: string): GameState
Game.exportGameState()returns a plainGameStateobject — version info plus the current storage, canvas, sound, and history data — suitable forJSON.stringify.Game.restoreGameState(data)restores everything from a previously exportedGameState, using whatever navigate function was set viaGame.onNavigate/Game.init'snavigateoption — it no longer takes a navigate function as a second argument.Game.jsonToGameState(json)just parses a JSON string back into aGameState— a thin wrapper aroundJSON.parsewith the right type, for symmetry withexportGameState.
const json = JSON.stringify(Game.exportGameState());
// ... later, possibly after a page reload ...
await Game.restoreGameState(Game.jsonToGameState(json));
What's inside a GameState
A GameState bundles every module's current state: storage variables, the canvas's saved
element/layer state (if the canvas was initialized), sound's channel/media state, and go-back
history (capped by stepHistory.stepLimitSaved, default 20 — see pixi-vn-history for what that
limit means for how far a player can go back after loading). Game.exportGameState/
restoreGameState is the layer application code should use — there's no need to go through any
individual module directly for a full game save.
Real-world persistence convention (official React template)
Game.exportGameState() says nothing about where that payload lives or what metadata a save-slot
UI needs (title, timestamp, thumbnail). That part is entirely up to the app. The official React+TS
template (npm create pixi-vn@latest, source at src/models/GameSaveData.ts /
src/lib/utils/save-utility.ts) shows one concrete way to close that gap — this is the template's
convention, not a library requirement:
interface GameSaveData {
saveData: GameState; // the raw Game.exportGameState() output
gameVersion: string;
date: Date;
name: string;
image?: string; // thumbnail, e.g. canvas.extractImage() — see pixi-vn-canvas
}
function createGameSave(options?: { image?: string; name?: string }): GameSaveData {
return {
saveData: Game.exportGameState(),
gameVersion: __APP_VERSION__,
date: new Date(),
name: options?.name ?? "",
image: options?.image,
};
}
async function loadSave(saveData: GameSaveData) {
await Game.restoreGameState(saveData.saveData);
}
The pattern: wrap exportGameState()'s return value in an app-level object carrying save metadata,
and pass the inner saveData field back into restoreGameState() when loading.
From there, the template persists that wrapped GameSaveData object (not the raw game state alone)
through several concrete mechanisms — illustrative, not exhaustive:
- Numbered save slots via IndexedDB (
saveGameToIndexDB/getSaveFromIndexDB/deleteSaveFromIndexDB), auto-incrementing from0. - Quick save slots, also via IndexedDB (
quickSaveGameToIndexDB), reserved to a fixed negative-id range below the numbered saves (e.g. ids-2..-7for 6 slots) so they never collide with manual saves. Each quick-save fills the first empty slot, then cycles by overwriting the least-recently-used slot once all slots are full. - An "auto exit save" (
addAutoExitSave, paired with auseAutoSaveOnPageClosehook bound to thebeforeunloadandvisibilitychangeevents) stringified straight intolocalStorageunder its own key — not through IndexedDB — so an accidental tab close or reload doesn't lose progress. - A "Continue" button:
getLastSaveFromIndexDBpowers a main-menu "Continue" action by comparing the latest numbered IndexedDB save against the auto exit save and returning whichever is newer (synthesizing id-1for the auto exit save for that comparison) —nullif neither exists, to disable the button; the result feeds straight intoloadSave. - A downloadable/importable JSON file (
downloadGameSave/loadGameSaveFromFile) for backing up or sharing a save outside the app.
None of this is prescribed by @drincs/pixi-vn — treat it as one worked example of gluing
exportGameState/restoreGameState to a real persistence layer, not the only way to do it.
Related skills
- pixi-vn —
Game.init/Game.onNavigateand the rest of the top-levelGameAPI. - pixi-vn-storage — variables/flags/stored classes that end up inside a save, and reserved keys.
- pixi-vn-history —
stepHistory.stepLimitSavedand what survives a save/load for "go back". - pixi-vn-canvas —
canvas.extractImage()for save thumbnails, and what canvas state gets saved. - pixi-vn-migration — renames affecting this area (
getSaveData→Game.exportGameState, etc.).