saveKit

Every player gets their own saved profile (level, XP, unlocks and play stats) that is still there when they leave and come back, with four ways of saving, four levelling curves, versioned save layouts and themed progression screens.

Version 1.3.0.

Guides

Two guides come inside the package, so every world that installs saveKit has them:

• How to save player progress with saveKit: what the kit is and how its pieces fit, saving and loading, the four ways of saving and when to pick each, profiles, levels, XP and unlocks, upgrading old saves, the save slot and load screens, and what each player's machine can change in multiplayer.
• Example: save slots, level unlocks and a Continue button: from an empty world to a small level-based game with three save slots, levels that unlock one after another and a Continue button on the title screen, with saveKit and menusKit from ZeroMind.

Open them any of these ways:

man does not open them yet, and ZeroMind search does not list them yet (see Known limits).

First example

Install saveKit into a new world, then replace the contents of the main scene's entrypoint (/source/scenes/main.scene/entrypoint.luau) with this and press Play:

local Save = require("saveKit.save")

-- onLoad runs when the scene starts in play.
function onLoad()
    Save.setup({ mode = "profile", curve = "steady" })

    -- A button that gives 40 XP each time it is pressed.
    ui.registerScreen("xpButton", {
        type = "button",
        props = { text = "+40 XP", onClick = "gainXP" },
        style = { position = "absolute", left = 24, top = 24, width = 140, height = 48, fontSize = 20 },
    }, 1000)
    ui.showScreen("xpButton")
end

-- Every button press in this scene lands here.
function onCallback(id: string)
    if id == "gainXP" then
        Save.addXP(40)
    end
end

Press +40 XP: the XP bar in the bottom-left corner fills, and on the third press you reach level 2. A ribbon says so, the save happens by itself and a small "Saved" badge appears. Stop and press Play again, or leave the world and come back: you are still level 2 with your XP. Nothing else is needed. saveKit starts its own host the first time it is used in play, and menusKit (which draws the looks) comes with it.

Styles

Every style works through the same calls. A world switches between them by changing one setting, for example Save.setup({ mode = "slots" }), and nothing else in its code.

Ways of saving (mode)

Each style keeps its own save, so switching style never mixes one style's data into another's. Aliases: auto, single, automatic (profile); slot, saveslots (slots); checkpoints (checkpoint); roguelike, runs, run (roguelite).

Levelling curves (curve)

A curve says how much XP each level costs. The level is always worked out from the player's total XP, so a world that changes curve re-reads everyone's level from their XP.

Save.setup({ curve = "custom", curveTable = { 50, 120, 250, 400, 600 } })   -- 6 levels
Save.setup({ curve = { 80, 160, 320 } })                                     -- a table is a custom curve too
Save.setup({ curve = "steady", maxLevel = 20 })                              -- any curve can be capped lower

steep is exponential: it grows by the same 40% every level, so it starts gentler than quadratic and ends much steeper (level 20→21 costs 59,760 XP on steep and 10,075 on quadratic).

Aliases: flat, linear, even (steady); steeper, exponential (steep); square, squared, polynomial (quadratic); table, own (custom).

Progression screens (screens)

Every screen has several presentations. Pick them with Save.setup({ screens = { bar = "ring", banner = "toast" } }) or Save.setScreens{...}. false turns a HUD screen off.

The unlock grid, profile card and slot picker open as panels: Save.showUnlocks(), Save.showProfile(player?), Save.showSlots(), Save.hidePanel().

Looks

saveKit draws every screen in menusKit's look, so a game that uses menusKit looks the same everywhere: scifi, fantasy (parchment), cartoon, pixel (retro), minimal, military, horror, cozy (menusKit's aliases work too). Each screen takes the look's colours, fonts and panel frame. Save.setTheme("pixel") restyles every saveKit screen and every menusKit menu at once, and a game calling Menus.setTheme restyles saveKit's screens too.

The list, for a world or another agent

local all = Save.catalogue()   -- { version, modes, curves, screens, themes, events }, each entry with tags
local best = Save.match({ genre = "roguelike" })          -- ranked: { kind, name, label, score }, best first
local screens = Save.match({ kind = "screen", size = "small" })

Each mode carries tags.genres, tags.session, tags.players, saves and death; each curve rule, firstCosts and tags.pace/tags.genres; each screen presentation tags.size, tags.mood, tags.fits; each look menusKit's own mood/genre/input tags.

Install

Install saveKit from ZeroMind (search "saveKit", home world Save Point: Profiles, Levels and Unlocks Kit), or in one call:

tools.use("zeromind", "installAsset", "6a0ed0da-0111-457f-b61e-d4040eaee34a")   -- saveKit

It brings menusKit (and menusKit's controlsKit) along as dependencies, and nothing else. Any folder works: the kits find each other by name (saveKit.save, menusKit.themes).

Without code, add the saveKit.SaveSetup component to any entity: its inspector picks mode, curve, each screen's presentation and the look, and changing a field while playing switches at once.

What a game calls

local Save = require("saveKit.save")

Save.addXP(25, "quest")        -- any reason word; returns levels gained
Save.kill()                    -- kills +1 and 25 XP (setup xp.kill)
Save.coin(5)                   -- coins +5 and 5 XP each (xp.coin)
Save.finishLevel("level_2")    -- levels +1, 100 XP (xp.level) and a save
Save.checkpoint("cp_3", "Bridge")  -- remembered, 10 XP the first time, and a save in every style
Save.died()                    -- what dying means in the current style (see Styles)
Save.newRun()                  -- roguelite: give up the run
Save.unlock("red_hat")         -- unlock anything by id (saves)
Save.event("boss")             -- grants unlocks that have event = "boss"
Save.addCurrency(10); Save.buy("lucky_charm")   -- meta currency, kept through roguelite deaths
Save.set("loadout", { "sword" }); Save.get("loadout")   -- the game's own saved fields
Save.save()                    -- save now, whatever the style

Reading: level(), xp() (into the level), xpToNext(), progress() (0..1), totalXP(), view(), currency(), stat(name), stats(), isUnlocked(id), unlocks(), lastCheckpoint(), data(), profile(), status(), lastSaved().

What is saved

One record per save, in the player's own data (runtime_data.player(id)), under saveKit/<namespace>/<style> (saveKit/main/profile, …/checkpoint, …/roguelite, …/slot1 to slot3, plus …/activeSlot):

A public card (saveKit/card: name, level, XP, title, unlock count, a few stats) is written beside it for other players to read.

Unlocks

Without an unlocks list a world gets nine to earn at once: Bronze Frame (level 2), Spark Trail (3), Silver Frame (5), Title: Veteran (8), Gold Frame (10), First Blood (1 kill), Collector (50 coins), Pathfinder (3 checkpoints), Finisher (1 finished level). A game passes its own:

Save.setup({ unlocks = {
    { id = "red_hat", name = "Red Hat", icon = "star", level = 3 },           -- by level
    { id = "sharpshooter", name = "Sharpshooter", stat = "kills", atLeast = 50 }, -- by stat
    { id = "boss_slayer", name = "Boss Slayer", event = "boss" },             -- by Save.event("boss")
    { id = "lucky_charm", name = "Lucky Charm", cost = 25 },                  -- bought with Save.buy
} })

Icons are menusKit's icon names (star, starFill, trophy, heart, flag, lock, profile, …). An id starting title_ becomes the player's title on their card.

Versions and upgrading old saves

Games change. Give your save layout a version and, when you change it, add a function that upgrades a save from the version before. A returning player's old save is upgraded step by step when it loads, never lost or broken:

Save.setup({
    version = 2,
    defaults = { coins = 0, cosmetics = { hat = "none", trail = "none" }, records = { bestTime = 0, bestScore = 0 } },
    migrations = {
        [1] = function(save)                 -- version 1 -> 2
            local g = save.game
            g.coins = g.gold or 0            -- "gold" was renamed "coins"
            g.cosmetics = { hat = g.hat or "none", trail = "none" }
            g.records = { bestTime = g.bestTime or 0, bestScore = 0 }
            g.gold, g.hat, g.bestTime = nil, nil, nil
            return save
        end,
    },
})

• setup refuses a version without a migration from every older number.
• The upgraded save is written straight away, and the save as it was is kept beside it at <key>.v<old> (saveKit/main/profile.v1). Save.on("migrated", fn) hears it; Save.migration() returns { from, to, steps }.
• Fields added to defaults reach old saves without a migration.
• A migration that errors or returns nothing leaves the stored save untouched and the profile read-only for that session (status() == "failed"), so a bug in an update never destroys anyone's progress.
• A save from a newer build than the one running is read but never overwritten (status() == "newer", event newerSave).
• A stored value that isn't a save at all is set aside at <key>.broken and a new profile starts (recovered).

The showcase does this for real: step on Write a v1 save (saveKit running the version 1 layout writes a save into your own data) and Read it with v2; the board shows the stored version 1 record and the upgraded version 2 record side by side.

Multiplayer

• Each profile is its player's own. Every machine loads, changes and saves only its own player's profile, in that player's own runtime_data store. The engine refuses a write to another player's store ("runtime_data: you can only write your own player's data"), so no machine, modified or not, can change someone else's profile. The showcase's Tamper test pad tries it and shows the refusal.
• Everyone can read everyone's card. Save.players() lists every connected player with their card; Save.cardOf(player) takes a user id, peer id or avatar entity; Save.showProfile(player) opens it read-only. Cards from other players are checked before use (types, lengths), so a malformed card can't break your screen.
• Code that runs on every machine uses Save.grant(player, xp, reason): it takes effect only on that player's own machine and returns false, "not yours…" everywhere else, so a kill seen by all machines gives XP exactly once. Save.isMine(player) answers the same question.
• Save.addXP, kill, coin, and the rest always act on the local player.
• Pads (saveKit.SavePad) test only the local player against themselves, so stepping on one changes your profile and nobody else's.
• A player's saved data can reach their machine a moment after they join. saveKit waits up to 2.5 s (loadWait) for it before starting a new profile, keeps whatever the player earned meanwhile and adds it, exactly once, to the save when it arrives, or to the new profile when none arrives. The same holds right after switching to another namespace or mode. A guest with no identity plays on in memory; saves then fail with a reason and the indicator says "Not saved".

Profiles and accounts

A profile belongs to an account, not to a machine or a session. saveKit stores it in that account's own player data for this world (runtime_data.player(<account id>)), so the same person gets the same profile on the desktop app, in a web browser and on any other machine they sign in on. Two different accounts always have two separate profiles, even on the same computer.

Two sessions signed in to the same account at the same time (two browser tabs, the desktop app and a browser, two engines) are one player to the platform. They share one identity and one store, so they share one profile:

• both load the same saved profile when they start;
• when one session saves, the other takes that newer copy as long as it has no unsaved changes of its own;
• if both change the profile before either save reaches the other, the save written last wins, and the other session's changes since its own last save are lost;
• each session draws its own HUD, but other players see one card for that account, the one saved last.

saveKit can't tell two sessions of one account apart (open engine issue #14448, see Known limits). To test two players, sign in with two different accounts.

Events

Save.on(event, fn) returns a handle for Save.off(handle); an unknown name raises. A handler added during play ends when play stops.

Other kits

saveKit can link to these kits and needs none of them. Installing saveKit brings none of them along, and a link switches on only when your game hands saveKit the kit in its setup, which it can do only if the kit is installed in your world:

Save.setup({
    mode = "checkpoint",
    kits = {
        trapline = require("Trapline.api"),     -- only the kits your world has
        scoreKit = require("scoreKit.core"),
        pickups = require("pickupsKit.api"),
    },
})

• Leave out a kit your world does not have. Nothing else changes: saveKit never looks a kit up on its own, so a world without them logs nothing about them.
• Why the game passes the kit in. A kit saveKit loaded by name would be recorded as one of saveKit's dependencies and installed with it everywhere; a name worked out while the game runs would stop a world that uses saveKit from publishing. Passing the kit in keeps saveKit's install to menusKit and controlsKit.
• Each link acts only for the local player's own events. scoreKit is listened to in scoreKit.core, which carries both the award event and the local player's key.
• Turning one off: Save.setup({ kits = { scoreKit = false } }), or bridges = { scoreKit = false }. A module that is not the kit it is passed as is refused once, with one warning (require("saveKit.bridges").failures() says why).
• What is linked: Save.kits() answers { trapline, scoreKit, pickups }, true for each kit linked. require("saveKit.bridges").available() says which of the three are installed in the world (it checks without loading them).

Setup options

Save.setup(opts) can be called any time; only the options given change.

Components

• saveKit.SaveSetup: the whole setup from the inspector (see Install).
• saveKit.SavePad: a glowing floor pad that does one thing to your own save when you step on it: xp, kill, coin, currency, finishLevel, checkpoint, died, newRun, save, reset, unlock, buy, event, unlocks, profile, playerCard, slots, mode, curve, theme, screen. Fields: action, amount, id, label, radius, cooldown, color, showLabel, labelHeight (stagger neighbouring pads so their labels never overlap).
• saveKit.SaveHost: spawned by the kit in play; ticks autosaves, draws the HUD and panels, routes their clicks and connects the other kits.

API

saveKit.save (what games use):

• Setup: setup(opts) (alias configure), config(), kits(), VERSION, MODES, CURVES, SCREENS, EVENTS, SLOT_COUNT.
• Progress: addXP, kill, coin, finishLevel, checkpoint, died, newRun, addStat, unlock, event, buy, addCurrency, set, get, data, reset.
• Reading: level, xp, xpToNext, totalXP, progress, view, currency, stat, stats, isUnlocked, unlocks, rules, lastCheckpoint, profile, status, isReady, mode, curve, curveName, curveTable, isDirty, lastSaved, migration, saveKey.
• Saving: save(reason?), flush().
• Slots: slots, activeSlot, newGame, load, copy, delete.
• Other players: isMine, grant, players, cardOf.
• Screens: setScreens, screens, setTheme, theme, showPanel, showUnlocks, showProfile, showSlots, hidePanel, panel, toast.
• Events: on, off.
• Catalogue: catalogue, match.

Functions starting with _ are for the host and tests.

Supporting modules: saveKit.curves (the curves as pure functions), saveKit.schema (layouts, upgrade, sanitize), saveKit.profile (rules on one record), saveKit.catalog (the tagged list), saveKit.store (where saves live; use swaps in a stand-in store for tests), saveKit.screens (every presentation as a widget tree, for your own UI), saveKit.bridges (the links to other kits: start, stop, reset, active, available, failures, canonical, KITS).

Tests

saveKitTests covers every public call: the curves' exact numbers, layouts and upgrades (missing, failing and newer migrations), each saving style, slots, unlock rules, the public card, refused writes to another player's data, the bridges, the catalogue, every screen in every presentation and look, that the first example in this README runs as written (its button pressed three times reaches level 2, saves, and is still level 2 after a rejoin), and that the version matches in package.yaml, this README and the code (88 tests). XP, coins and currency earned while a save is still loading are checked to count exactly once: when no save arrives, when it arrives late, and right after switching save name or style. The bridges are tested with stand-in kits, and one test reads every saveKit source file to check that none names Trapline, scoreKit or pickupsKit, so saveKit works and installs on its own. It saves through a stand-in store, so running it never touches a real player's progress. Run it in edit mode:

tools.use("tests", "run", { suite = "saveKitTests", onWorker = true })

Showcase

The Save Point world opens on a square plaza with every saving style, levelling curve and progression screen on labelled boards facing the spawn, with glowing pads to use each one (move the mouse to look around: saving styles ahead, curves and the pink look pads on the left, the save upgrade, profiles and Trapline on the right, screens, scoreKit and pickupsKit behind): pink pads switch the look, green ones switch style or curve, blue ones give XP, kills and coins, and others reach checkpoints, die, start new runs, open panels and slots. A Screen gallery pad shows every presentation of every screen side by side, the save upgrade board shows a real version 1 save read by the version 2 layout, Everyone's profile lists every player's card with the tamper test, and the kit stations run the real Trapline, scoreKit and pickupsKit: touch a Trapline flag or campfire and saveKit saves at that checkpoint, step on a points pad and scoreKit's points turn into XP, walk through pickupsKit's XP orbs and coins and they give XP and coins. Those three kits are installed in the Save Point world for the showcase only; saveKit itself needs none of them.

Changelog

• 1.3.0: two guides inside the package, and a check on today's engine. saveKit's own code is unchanged from 1.2.1 (only its version number moved).
  • Two guides ship with the kit in documentation/: How to save player progress with saveKit (the ideas: saving and loading, the four ways of saving and when to pick each, profiles, levels, XP and unlocks, upgrading old saves, the save slot and load screens, and what each player's machine can change in multiplayer) and Example: save slots, level unlocks and a Continue button (an empty world to a four-level game with three save slots, levels unlocking in order and a Continue button, using saveKit and menusKit from ZeroMind). Every step of the example was done and seen working in a fresh world. The guides link to each other and the README's new Guides section says how to open them.
  • Checked on today's engine. saveKit installed on its own into a fresh world (it brought menusKit and controlsKit and nothing else), the first example above ran as written (three presses of +40 XP reached level 2 with 20 XP and saved by itself), and the level was still there after the world was closed and opened again. The tests passed twice in the Save Point world and once in the fresh world (88 of 88 each time). Nothing needed fixing.
  • Known limits name the open issues that apply today.
  • The store listing and the world description say 1.3.0 and mention the guides.
• 1.2.1: a tidy showcase, and a store listing and world description that match the kit. saveKit's own code is unchanged from 1.2.0 (only its version number moved).
  • The store listing and the world description are corrected. The world's description still began "saveKit 1.1.0" and its store page described the kit links as working just by having the kits installed. Both now say 1.2.1 and describe what the kit does today: autosave also a few seconds after any change, the steep curve growing 40% a level, the Trapline, scoreKit and pickupsKit links switching on only when a game passes those kits to Save.setup({ kits = ... }), and installing saveKit bringing menusKit and none of the other kits. The store page also says where each station stands in the showcase.
  • The Save Point showcase is laid out on a grid you can read from the spawn. Every station faces the spawn from one of four sides of a square plaza (ahead: saving styles; left: curves and looks; right: save upgrade, everyone's profile and Trapline; behind: screens, scoreKit and pickupsKit). Each row of pads has its labels on its own line, so no label, board or pickup covers another from the spawn, whichever way the camera turns. scoreKit's counter moved to the bottom-right corner, over open floor. The section headings (saving styles, curves, screens) lie flat on the wall with clear space above and below, and every board has a single title. The curve, saving style and profile boards break their text into short lines so it is large enough to read from the spawn, and the tamper test reports its result in one plain sentence ("changing another player's profile was refused: only a player's own machine can change their profile") instead of the engine's error text.
• 1.2.0: installs on its own, XP counted once, readable showcase.
  • Installing saveKit brings only menusKit and controlsKit again. 1.1.0 looked the other kits up by name, and because they were installed in the world saveKit is published from, the install recorded them, and their own dependencies, as saveKit's: eleven extra packages. saveKit now names no other kit. A game links one by passing it in setup({ kits = ... }), and only then does that link switch on (see Other kits). New: Save.kits().
  • XP earned while a save is loading counts once. When no save arrived in time (a new player, or right after switching save name or style), what was earned while waiting was added twice: 70 XP became 140. Fixed, with tests for each case.
  • The card and the unlock grid count the same unlocks: every unlock rule, plus anything unlocked that no rule names.
  • SavePad.labelHeight: how high a pad's label floats, so neighbouring pads can stagger theirs.
  • Tests. 88 tests (5 new: XP earned while loading with no save, with a late save and after a switch; saveKit on its own; kits linked only when passed in).
• 1.1.0: a quadratic curve, kit links that work and stay quiet.
  • New curve quadratic: 25 × n² + 75 XP from level n to n+1 (100, 175, 300, 475, 700, …). SaveSetup offers it too.
  • scoreKit points give XP again. saveKit listened on scoreKit.score, which has no localKey, so it could not tell which awards were yours and gave XP for none of them. It now listens on scoreKit.core, which has both.
  • No log spam without a kit. The links find each kit by package name (~pickupsKit.api), which also reaches a kit installed as another kit's dependency. A kit that is installed but fails to load is warned about once and not retried every few seconds. New: bridges.failures() and bridges.reset().
  • README: how profiles belong to accounts and what happens when two sessions share one account; known limits name the open engine issues.
  • Tests. 83 tests (4 new: the quadratic curve, a broken or missing kit tried once, scoreKit wired through its core, Trapline and pickupsKit wired to their events).
• 1.0.2: Save.theme() checks quietly that menusKit is there before loading it, so a world unloading menusKit logs no error. Install checked in a clean private world: the first example ran as written and the level came back in a fresh session.
• 1.0.1: nothing is lost on a reload, and setup keeps unsaved progress.
  • Saves a few seconds after any change (autosave.afterChange, 3 s). Before, XP gained without a level-up waited for the 60-second timer or a clean exit, so a browser reload or a closed tab could lose up to a minute of it.
  • setup keeps unsaved progress. Calling setup again with the same version and migrations used to reload the save from the store and drop anything not yet saved. It now reloads only when the layout really changes (saving first), or when the loaded save had been refused as newer or not upgradable.
  • Every play session loads fresh. The host now loads the player's save in its start() (play only), so a profile read in edit mode, for example by an editor board before the game's setup ran, is never carried into play. Each session is counted once and the count is saved.
  • Late fonts on the web player. The host re-registers the look's fonts while they are missing and redraws when they arrive, so the HUD uses the look's fonts in a game that never opens a menusKit menu.
  • Tests. 79 tests (5 new: save after a change, setup keeping progress, one count per session, the first README example run as written with only saveKit, and one version in package, README and code).
• 1.0.0: first release.

Known limits

Each of these is an open issue in the engine or in ZeroMind, not in saveKit, and each says where it applies.

• #14448: two sessions on one account are one player. Sessions signed in to the same account (two browser tabs, the desktop app and a browser) are one player identity with one player data store, so they collide as one player and share one profile: both load the same saves, and when both change it before either save reaches the other, the save written last wins (see Profiles and accounts). Two-player saves need two accounts.
• #20750: frame time spent on multiplayer sync. The engine spends part of every frame keeping multiplayer state in step. saveKit adds little to it (it writes only the local player's own data and reads other players' cards), but in a busy world that sync is part of the frame budget your game shares.
• #19849: long waits. Some engine calls take a long time to come back: running the kit's tests, installing, and switching worlds can run on in the background for several seconds or more. Wait for them to finish before judging the result.
• #20946: checking the world on the web build happens outside your session. The browser build can't be started from an editor session, so a check that saving works in a web browser has to be done by opening the world in a browser tab yourself.
• #21420: installs with several dependencies are slow. Installing saveKit brings menusKit and controlsKit; linking Trapline, scoreKit or pickupsKit means installing those too, and each brings its own dependencies. Install one kit per call and let each finish.
• #19258: the ZeroMind description can lag one version behind after a release. Right after a new version is published, the kit's description on ZeroMind may still describe the version before. The README in the installed package is always current.
• ZeroMind#3099: guides inside a package don't show up in ZeroMind search yet. The two guides install with saveKit and open inside the engine (see Guides), but searching ZeroMind doesn't find them yet.
• #22286, #22291 and #22315: opening and searching a package's guides only works in some forms. In this release, the Docs panel's search box, zero guides read <name> and the guides tool with the guide's short name open them; man <name> does not, and neither does the guide's dotted identity in the guides tool. The Guides section lists the forms that work.