Pixi'VN Saves: exporting, restoring, and persisting game state

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 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
```
.

const json = JSON.stringify(Game.exportGameState());
// ... later, possibly after a page reload ...
await Game.restoreGameState(Game.jsonToGameState(json));

What's inside a

GameState

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

— 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 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-getting-started —
```
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.).

pixi-vn-saves

NPX Install

Tags

SKILL.md Content

Pixi'VN Saves: exporting, restoring, and persisting game state

When to use this skill

The core trio

What's inside a
`GameState`

Real-world persistence convention (official React template)

Related skills