Utility·phaserthree·v1.0.0·MIT

Save Load

Type-safe localStorage-backed save system with versioning and migrations. Engine-agnostic.

#save#persistence#localstorage

Install

npx gamecn add save-load

Source preview

Compatibility

Engines
phaser >=3.80.0 <4.0.0three >=0.160.0
Frameworksvanilla, react
Languagestypescript
Bundlersvite

Files installed

  • {src}/utilities/SaveLoad.ts
  • docs/gamecn/save-load.md(docs)

Notes

Usage

import { SaveLoad } from "@/utilities/SaveLoad";

interface Save {
  level: number;
  hp: number;
  inventory: string[];
}

const save = new SaveLoad<Save>({
  namespace: "my-rpg",
  version: 1,
});

// Save
save.save("slot-1", { level: 3, hp: 100, inventory: ["sword"] });

// Load
const loaded = save.load("slot-1");
if (loaded) console.log(loaded.level);

// Slot management
save.has("slot-1");        // true
save.list();               // ["slot-1"]
save.remove("slot-1");

Migrations

When you change your save shape, bump version and provide migrate:

const save = new SaveLoad<Save>({
  namespace: "my-rpg",
  version: 2,
  migrate: (old, from) => {
    if (from === 1) {
      const v1 = old as { level: number; hp: number };
      return { ...v1, inventory: [] };
    }
    throw new Error(`unsupported save version ${from}`);
  },
});

API

Method Description
save(slot, data) Persist data.
load(slot) Read; returns undefined if missing or unmigrateable.
has(slot) Existence check.
remove(slot) Delete a slot.
list() All slot ids in this namespace.

Related