DRincs-Productions/pixi-vn / skills/saves
pixi-vn-saves
VerifiedUse 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, auto-save-on-refresh, downloadable JSON). Load this before writing any save-file, save-slot, or "continue game" feature.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.5 KB |
SKILL.md
View on GitHub---
name: pixi-vn-saves
description: 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, auto-save-on-refresh, downloadable JSON). Load this before writing any save-file, save-slot, or "continue game" feature.
---
# Pixi'VN Saves: exporting, restoring, and persisting game state
Official docs: [pixi-vn.com/start/save](https://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
```ts
import { Game } from "@drincs/pixi-vn";
Game.exportGameState(): GameState
Game.restoreGameState(data: GameState): Promise<void>
Game.jsonToGameState(json: string): GameState
```
- **`Game.exportGameState()`** returns a plain `GameState` object — version info plus the current
storage, canvas, sound, and history data — suitable for `JSON.stringify`.
- **`Game.restoreGameState(data)`** restores everything from a previously exported `GameState`,
using whatever navigate function was set via `Game.onNavigate`/`Game.init`'s `navigate` option —
it no longer takes a navigate function as a second argument.
- **`Game.jsonToGameState(json)`** just parses a JSON string back into a `GameState` — a thin
wrapper around `JSON.parse` with the right type, for symmetry with `exportGameState`.
```ts
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.
## Extending the save state (export/restore hooks)
A third-party library (or a game) that keeps its own state outside Pixi'VN's modules can add it to
every save and read it back on load, without wrapping `exportGameState`/`restoreGameState`:
```ts
import { Game } from "@drincs/pixi-vn";
// Type the custom data with module augmentation of the public GameState interface.
declare module "@drincs/pixi-vn" {
interface GameState {
myLibraryData?: { score: number };
}
}
// Runs on the complete object before exportGameState() returns it; mutate it in place.
Game.addOnExportGameState(async (state) => {
state.myLibraryData = { score: await getScore() };
});
// Receives the exact object passed to restoreGameState().
// timing "before" (default): before any built-in module is restored.
// timing "after": after built-in restoration and navigation have completed.
Game.addOnRestoreGameState((state) => myLibrary.load(state.myLibraryData));
Game.addOnRestoreGameState(() => myLibrary.refresh(), { timing: "after" });
```
- Handlers may be sync or async; they are awaited **sequentially in registration order**, and an
error thrown by a handler propagates to the `exportGameState`/`restoreGameState` caller.
- Both `add*` methods return a function that unregisters the handler; `Game.removeOnExportGameState(handler)`
/ `Game.removeOnRestoreGameState(handler)` do the same and leave other handlers registered.
- Handler types are exported from the root: `OnExportGameStateHandler`, `OnRestoreGameStateHandler`,
`OnRestoreGameStateOptions`, `GameStateHookTiming`.
- Make custom properties optional (`?`) — saves created before the library was added won't have them.
## 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**:
```ts
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 from `0`.
- **Quick save slots**, also via IndexedDB (`quickSaveGameToIndexDB`), reserved to a fixed negative-id
range below the numbered saves (e.g. ids `-2..-7` for 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 a `useAutoSaveOnPageClose` hook bound to
the `beforeunload` and `visibilitychange` events) stringified straight into `localStorage` under
its own key — not through IndexedDB — so an accidental tab close or reload doesn't lose progress.
- **A "Continue" button**: `getLastSaveFromIndexDB` powers a main-menu "Continue" action by comparing
the latest numbered IndexedDB save against the auto exit save and returning whichever is newer
(synthesizing id `-1` for the auto exit save for that comparison) — `null` if neither exists, to
disable the button; the result feeds straight into `loadSave`.
- **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.onNavigate` and the rest of the top-level `Game` API.
- pixi-vn-storage — variables/flags/stored classes that end up inside a save, and reserved keys.
- pixi-vn-history — `stepHistory.stepLimitSaved` and 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.).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |