Log inGet started
World

Save Point: Profiles, Levels and Unlocks Kit

README.md

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.18, built against the current controlsKit (1.3.2) and menusKit (1.3.19).

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:

WhereHow-to guideExample guide
The editor's Docs panel: type in its search box, then pick the entry under SAVEKITsave-playersave-slots
The shellzero guides read save-player-progresszero guides read save-slots-level-unlocks-continue
An agent's guides tool, path =save-player-progresssave-slots-level-unlocks-continue
The filesdocumentation/save-player-progress.guide/guide.mddocumentation/save-slots-level-unlocks-continue.guide/guide.md

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)

modeWhat it isSavesOn death (Save.died())Suits
profileOne automatic profile per player.By itself: a few seconds after any change, and at once on level up, unlock, checkpoint and finished level. A reload or a closed browser tab loses nothing.Counts a death; nothing is lost.platformer, party, shooter, open-world, sandbox, casual, social
slotsThree save slots the player picks from: new game, load, copy and delete. The picker opens by itself until a slot is chosen.By itself, into the chosen slot (same triggers as profile).Counts a death; nothing is lost.rpg, adventure, story, metroidvania, puzzle; shared devices
checkpointSaves only when the player reaches a checkpoint (Save.checkpoint).At checkpoints only (and Save.save() if the game calls it).Puts the profile back to what the last checkpoint saved. Leaving without a checkpoint loses what happened since.platformer, obstacle course, horror, survival, soulslike, action
rogueliteRuns. A run's level and XP are lost when the player dies or starts a new run; unlocks and meta currency stay forever.By itself (same triggers as profile), and when a run ends.The run ends: level and XP go back to the start, 10% of the run's XP is banked as meta currency, unlocks and currency are kept.roguelite, roguelike, arena, wave survival, deckbuilder, dungeon

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.

curveRuleXP for level 1→2, 2→3, … 10→11Total XP to reach level 5 / level 10Top level
steady100 XP for every level.100, 100, 100, 100, 100, 100, 100, 100, 100, 100400 / 90050 (4,900 XP)
steepThe first level costs 100 XP; each level after costs 40% more, rounded to the nearest 10: round(100 × 1.4^(n−1) / 10) × 10.100, 140, 200, 270, 380, 540, 750, 1,050, 1,480, 2,070 (then 2,890, 4,050, …)710 / 4,91050
quadraticThe XP from level n to n+1 grows with the square of n: 25 × n² + 75.100, 175, 300, 475, 700, 975, 1,300, 1,675, 2,100, 2,575 (then 3,100, 3,675, …)1,050 / 7,80050 (1,014,300 XP)
customYour own table: entry n is the XP from level n to n+1. The table's length sets the top level (length + 1).with the default table { 50, 120, 250, 400, 600, 850, 1200, 1600, 2100 }: 50, 120, 250, 400, 600, 850, 1,200, 1,600, 2,100820 / 7,17010 with the default table
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.

ScreenPresentations (first is not always the default)DefaultSuits
Level-up banner (banner)celebration big full-screen burst with the new level on the look's panel (2.6 s) · ribbon a ribbon across the upper third (2.2 s) · toast a small card at the top right (2 s) · falseribboncelebration: rpg, party, kids · ribbon: adventure, platformer · toast: shooter, racing, competitive
XP bar (bar)thin slim full-width line along the bottom · segmented ten blocks with a level badge, bottom left · ring a ring around the level number, top left · falsesegmentedthin: shooter, open-world · segmented: platformer, arcade, kids · ring: action, mobile, roguelite
Unlock grid (unlocks)grid tiles with icons, locked ones show a lock and what earns them · list rows with requirement and progress bargridgrid: cosmetics, party · list: achievements, rpg
Profile card (card)full name, title, level ring, XP, unlocks and play stats · badge a compact nameplatefullfull: rpg, lobby · badge: shooter, scoreboard
Save slot picker (slots)cards three cards side by side · list three rows (always used on narrow screens)cardscards: rpg, story · list: mobile, puzzle
Saved indicator (saved)badge disk icon and "Saved" bottom right · text "Progress saved" and the reason at the top · falsebadgeany

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

The XP bar stays on screen the whole game, so saveKit states where it is: its measured rect is listed in ui.safeArea().controls under the owner saveKit_hud (stated with ui.setControlRegions, restated whenever the bar moves, resizes or turns off). A game's own HUD reads it there to keep clear of the bar on any screen size, and other screens' anchors keep clear of it by themselves. The segmented bar also keeps clear of others: on a screen narrower than its 390 points (a phone held upright) its segments narrow so the whole bar fits on screen, and when its bottom-left corner lands on a rect another screen states (the engine's touch buttons, a kit's button column, a level's panel) it steps up above it. Where nothing is in the way it stands exactly where it always has. The HUD draws on UI layer 900 (Screens.HUD_LAYER) and panels on 940 (Screens.PANEL_LAYER): put something that has to show over the bar and the level-up banner, such as notice signs over people's heads, between the two.

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):

FieldWhat
versionthe game's save layout version (see below); kit is saveKit's own layout number
totalXp, level, bestXP and level (this run, in roguelite), best level and XP ever
unlocks{ [id] = os.time() when unlocked }
statsplayTime (s), sessions, deaths, kills, coins, levels, checkpoints, runs, xpEarned, and any the game adds
currencymeta currency
checkpoint{ id, label, at }
gamethe game's own fields (defaults, Save.set)
created, saved, savestimestamps and save count

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.

Eventinfo
xpamount, reason, level, xp, need, totalXp
levelUplevel, from, unlocked (names)
unlockid, name, rule, why (level, stat, event, manual, bought) or atLoad
stat, currencyname, value, amount / value, amount
checkpoint, levelCompleteid, label, new / id
died, runEndedmode, reverted, checkpoint, banked / banked, runXp, runLevel, died
saved, saveFailed, saveRefusedreason, key, slot, mode, saves / reason, error / reason, why
loaded, ready, migrated, newerSave, recoveredkey, mode, slot, status, migratedFrom, fresh / status / from, to, steps, backup / version, reads / error
slot, mode, theme, screens, panelaction, slot, from / mode, from / name / screens / name, open

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"),
    },
})
Kit (kits key)PassWhat happens
Trapline (trapline)require("Trapline.api")Reaching a Trapline checkpoint calls Save.checkpoint (a checkpoint save); losing a life calls Save.died.
scoreKit (scoreKit)require("scoreKit.core")Points the local player scores become XP: 10% by default (bridges = { scoreToXp = 0.1 }), fractions carried over.
pickupsKit (pickups)require("pickupsKit.api")Taking an XP orb gives its XP; coins count as Save.coin.
  • 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.

OptionDefault
mode"profile"saving style
curve, curveTable, maxLevel"steady", default table, curve's ownlevelling
version, migrations, defaults1, none, {}the game's save layout
unlocksthe nine defaultsunlock rules
xp{ kill = 25, coin = 5, level = 100, checkpoint = 10 }XP per event
autosave{ interval = 60, afterChange = 3, levelUp = true, unlock = true, checkpoint = true, levelComplete = true }autosave triggers: afterChange saves that many seconds after the last change (0 turns it off), interval every that many seconds (0 turns it off); the checkpoint style ignores both
bankRate0.1share of a roguelite run's XP banked as currency
namespace"main"a separate set of saves (for example per game mode)
screenssee Progression screenspresentations
hudtruefalse hides the HUD screens (panels still open)
kitsnonethe other kits to link: { trapline = require("Trapline.api"), scoreKit = require("scoreKit.core"), pickups = require("pickupsKit.api") }; false unlinks one (see Other kits)
bridgesall on, scoreToXp = 0.1turn a linked kit off, and the share of scoreKit points that becomes XP
thememenusKit'sthe look
loadWait, minSaveGap2.5, 0.5seconds to wait for a late save; least time between autosaves

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.18: the Saved flash is stated to other screens while it shows, the way the XP bar and the level-up banner are: its rect is in ui.safeArea().controls under saveKit_hud (widget id sk:saved), so another kit's notice signs or prompts keep off it instead of drawing over it. Nothing else changes.

  • 1.3.17: the Saved badge stands in the bottom-right corner when that spot is free, as before; otherwise it takes the nearest free spot above it on the right edge, then on the left edge, clear of every rect another screen states with ui.setControlRegions and of this HUD's own XP bar (on a touch tablet it sat on the engine's Jump button, and on a phone held upright on the XP bar). With no free spot anywhere the badge is not drawn: a short Saved is not worth covering a button or a panel. Found in Dockhands.

  • 1.3.16: the segmented XP bar fits on a phone held upright and never covers a button: it narrows its segments to the screen's width (it ran 18 points off the right edge of a 390-point screen) and steps up above any rect another screen states with ui.setControlRegions that its corner would land on (on a portrait phone it covered the engine's Jump button and a kit's Act button). Landscape phones, tablets and desktops are unchanged. Found in Dockhands.

  • 1.3.15: the level-up ribbon keeps clear of what other screens state with ui.setControlRegions (a level's objectives panel, a kit's touch buttons): it narrows to the widest free stretch of its band, or moves down below what is in the way when that stretch is too narrow to read. While it shows, its rect is stated in ui.safeArea().controls beside the XP bar's (owner saveKit_hud), so things drawn over the picture, such as notice signs over people's heads, can step clear of it. New Screens.BANNER_ID. Found in Dockhands, where the ribbon covered the objectives and the guards' notice signs sat on it.

  • 1.3.14: the XP bar states its rect in ui.safeArea().controls (owner saveKit_hud, via ui.setControlRegions), so other screens and a game's own HUD can keep clear of it on phones and desktops. Before, the bar told nobody what part of the screen it covered, and things drawn on a lower layer ended up underneath it. New Screens.BAR_ID.

  • 1.3.13: built against menusKit 1.3.19, the first menusKit whose files all name one controlsKit release (1.3.17 and 1.3.18 still named older controlsKit releases in MenusHost and themes, so an install landed three controlsKit copies). No saveKit behaviour changed.

  • 1.3.12: built against controlsKit 1.3.2 and menusKit 1.3.17, the first releases of those two that install as a single copy each (controlsKit 1.3.1 still pointed some of its own files at 1.3.0, so every kit on it landed two controlsKit releases). The test suite names saveKit modules relatively. No saveKit behaviour changed.

  • 1.3.11: built against menusKit 1.3.16 (was 1.3.13), the release inventoryKit, questKit, dialogueKit, economyKit and arpgKit move to, so one world can install all of them with one menusKit and one saveKit. The world also moved to the current engine library. No saveKit code changed.

  • 1.3.10: built against the current controlsKit (1.3.1) and menusKit (1.3.13), the releases economyKit, inventoryKit and navUiKit use, so a world that installs saveKit beside them holds one controlsKit and one menusKit instead of older copies beside the current ones. The world also moved to the current engine library. No saveKit code changed; the suite runs 88 of 88.

  • 1.3.9: built against controlsKit 1.2.8 and menusKit 1.3.11. 1.3.8 installed, but a fresh world still held three controlsKit releases: a dependency on controlsKit resolves to the release controlsKit's world ships, so only the newest one can be shared. Every package that ships with sideScrollerKit now moves to 1.2.8 together. Code unchanged.

  • 1.3.8: installs again, on one controlsKit release. This world held its own copy of controlsKit (old 1.0.1 files over the release menusKit brings), and every install of saveKit failed reading a controls module ZeroMind never received. The copy is gone (controlsKit needed none of it), and saveKit is built against menusKit 1.3.10 and the published controlsKit 1.2.4, the release the kits it ships beside (twoDKit, sideScrollerKit) are built against. Code unchanged.

  • 1.3.7: states menusKit at exactly 1.3.6, so an install no longer takes menusKit 1.3.7 to 1.3.9, whose controlsKit copy ZeroMind cannot serve. Code unchanged.

  • 1.3.6: installs again. menusKit's newest commit in its world (a merged pull request) references a controlsKit build ZeroMind never received, so an install of saveKit 1.3.4 or 1.3.5 failed reading it. saveKit now holds menusKit at the published 1.3.6 release. Code unchanged.

  • 1.3.5: installs again. 1.3.4 was published with a locally changed copy of controlsKit in its world, so an install asked ZeroMind for a controlsKit build it never received and failed. 1.3.5 holds controlsKit exactly as published. Code unchanged.

  • 1.3.4: built against controlsKit 1.2.4 like the kits it ships with, so a world on 1.2.4 can take the update. menusKit stays at 1.3.6. Code unchanged.

  • 1.3.3: built against menusKit 1.3.6, so an install no longer carries older copies of two menusKit modules. Code unchanged.

  • 1.3.2: the README names the current version and carries the 1.3.1 entry (1.3.1 shipped without them). Code unchanged.

  • 1.3.1: with the HUD off (hud = false) saveKit draws no screen at all. It used to register an empty full-screen root on its HUD layer, which took every click and drag meant for the game's own UI beneath it.

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