Pixi Vn Storage

Pixi'VN Storage

When to use this skill

Use this skill whenever a task involves storing game state that must persist across steps and saves: flags ("has the player met Liam?"), counters (gold, affection points), arbitrary objects, or a custom class whose instances need to survive save/load (e.g. a quest-tracking model). It does not cover characters specifically (see the characters skill, which is itself built on top of the pattern described here) or how the history/go-back system is implemented internally (see the history skill).

Official docs (authoritative for terminology and recommended patterns): storage, flags, storage classes, temporary storage, save & load.

import { storage, StoredClassModel } from "@drincs/pixi-vn";

(Also available from the narrower @drincs/pixi-vn/storage subpath — see pixi-vn-getting-started for when to prefer that.) storage is a ready-made singleton (StorageManagerInterface) — you never instantiate StorageManager yourself.

1. Simple variables: storage.set / storage.get

See pixi-vn.com/start/storage.

storage.set("test", "test1");
storage.get("test"); // "test1"

storage.set("Test", "test2"); // keys are case-sensitive, "Test" !== "test"
storage.get("nope"); // undefined

storage.set("variable1", { test: "test", test2: 1 }); // objects/arrays are fine too
storage.set("variable6", null);
storage.set("variable7", undefined); // undefined removes the key entirely

Allowed value types (StorageElementType, from src/storage/types/StorageElementType.ts): strings, numbers, booleans, null/undefined, plain objects and arrays of these — no functions, class instances, or Maps/Sets. For anything richer, use a StoredClassModel (below).

Other storage methods:

• storage.remove(key) — deletes a variable.
• storage.flags.set(key, value: boolean) / storage.flags.get(key) — a dedicated boolean-flag store (docs), kept separate from set/get; flags default to false when never set. Keys are case-sensitive here too. The docs recommend flags over storage.set for booleans specifically because of save size: internally all active flags are kept as a single array of names, which is much lighter to serialize than one storage entry per boolean. A documented pattern is exposing a class boolean property that's backed by a flag name (a string) instead of a literal boolean, so the getter/setter transparently reads/writes storage.flags.get/set.
• storage.default = { key: value, ... } — sets the starting values used when the game boots or after storage.clear(); if you later remove() a key (or it was never set()), reading it falls back to this default instead of undefined.
• storage.clear() — wipes all stored variables (used by tests/new-game flows), after which reads fall back to storage.default.

Temporary (label-scoped) variables

See pixi-vn.com/start/temp-storage. storage.temp.set(key, value) behaves like storage.set for reads — storage.get(key) checks temp variables first, then falls back to the permanent store — but the value is deleted once the label it was set in closes. It's for scratch state that should reset once the player moves on:

storage.temp.set("counter", counter + 1);
// ... reads still go through storage.get("counter")
storage.temp.remove("counter");

Per the docs' own description of the lifecycle: if the label that set the temp variable calls another label (nested call, e.g. call), the variable stays accessible from that child label too — it's only deleted once the originating label itself closes. But if control moves on via jump (closing the current label and starting a new one instead of nesting into it), the temp variable is gone immediately, since it belonged to the now-closed label. Implementation-wise this is tracked as a deadline against how many labels are open on the call stack at the moment temp.set runs — see tests/storage.test.ts, setTempVariable & getTempVariable, where a temp counter set inside a called label keeps incrementing across narration.continue() steps but is reset once narration.labels.closeCurrent() /closeAll() unwind the label stack. Don't rely on temp variables for state that must outlive the label that set it — use storage.set for that.