Save progress

Read and write#

await Velven.ready();const level = Number(Velven.data.getItem("level") ?? 1); // a string, or nullVelven.data.setItem("level", level + 1);                 // stored as a string, like localStorageVelven.data.removeItem("tutorial");Velven.data.clear();

Reads are synchronous once ready() has settled. Calling Velven.data before then throws, because the save is not loaded yet.

Where saves live#

• Inside Velven, the save is kept in the player's browser. On a published space with a verified owner, a signed-in player's save is kept in their account too, so it follows them to another device.
• Writes land in memory at once and are sent a second later, and at once when the frame is hidden or closed. A write in the last moment before a tab closes may not arrive, so save at checkpoints, not only on exit.
• On your own site (site), the save is the page's own localStorage, under the key velven:data. It never reaches Velven and is separate from the save inside Velven.

When a guest signs in#

A new account takes the guest's save. An account that already has a save keeps its own, and the guest's stays in that browser for when they sign out. Either way, the account's save is in place before onAuth runs, so read it again there:

Velven.onAuth(() => loadProgress(Velven.data.getItem("level")));

When the save is slow#

If the save cannot be fetched in time, the game starts from an empty save. It stays in memory and is never sent over the real one. Velven asks for the save again before the next send; when it arrives, it replaces what was written meanwhile, with a warning in the console.

Limits#

• One save per player per space, up to 1 MB as JSON. A setItem that would go over throws a RangeError and changes nothing, as localStorage does when full.
• The key __proto__ throws a TypeError.
• Nobody can read a player's save, you included. To let a player start over, give the game a reset that calls Velven.data.clear().
• Keep a personal best on a board, where scores.mine reads it, not in a save.