# save The one interface game code uses. Every player gets their own profile (level, XP, unlocks, stats, meta currency and the game's own fields) that is still there when they leave and come back. Each machine works on its own player's profile only, in that player's own data store, and the game's calls are the same in every saving style. - Setup: `setup(opts)` (alias `configure`; mode, curve, curveTable, maxLevel, version, migrations, defaults, unlocks, xp, autosave, bankRate, namespace, screens, hud, kits, bridges, theme), `config`, `on(event, fn)` / `off(handle)` (event names in `EVENTS`). - Progress: `addXP`, `kill`, `coin`, `finishLevel`, `checkpoint`, `died`, `newRun`, `addStat`, `unlock`, `event`, `buy`, `addCurrency`, `get` / `set` / `data` for the game's own fields; read back with `level`, `xp`, `xpToNext`, `totalXP`, `progress`, `currency`, `stat`, `stats`, `isUnlocked`, `unlocks`, `lastCheckpoint`, `view`, `profile`. - Saving: `save(reason)`, `flush`, `reset`, `status` / `isReady`, `lastSaved`, `isDirty`, `migration`, `saveKey`. Autosave runs on level up, unlock, checkpoint, finished level and on a timer, as `autosave` says. - Slots (slots style): `slots`, `activeSlot`, `newGame(i)`, `load(i)`, `copy(from, to)`, `delete(i)`. - Other players: `isMine(player)`, `grant(player, xp)` for code that runs on every machine (takes effect only on that player's machine), `players`, `cardOf(player)`. - Screens: `setScreens`, `screens`, `setTheme`, `theme`, `showPanel` / `showUnlocks` / `showProfile` / `showSlots`, `hidePanel`, `panel`, `toast`. - Catalogue: `catalogue()` and `match(want)` list and rank the styles, curves and screens. Calls whose names start with `_` are for the `SaveHost` component and tests. The first call in play spawns the host by itself, so a game never places it.

# catalog Everything the kit offers, as plain data with tags: the four saving styles (`profile`, `slots`, `checkpoint`, `roguelite`), the levelling curves, and every presentation of each progression screen (`banner`, `bar`, `unlocks`, `card`, `slots`, `saved`). - `modeNames`, `mode(name)`: the saving styles and one style's entry (accepts aliases). - `presentations(kind)`, `hasPresentation(kind, name)`: the presentations of one screen kind. - `catalogue()`: the whole list as plain data. - `match(want)`: ranks entries against wanted genre, mood, size or kind, best first. `DEFAULT_SCREENS` holds the presentation each screen uses until a game changes it. Mostly internal: game code reaches it through `Save.catalogue()` and `Save.match(...)`; a world or another agent can use those to pick a setup by genre or pace.

# 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: | Where | How-to guide | Example guide | |---|---|---| | The editor's **Docs** panel: type in its search box, then pick the entry under SAVEKIT | `save-player` | `save-slots` | | The shell | `zero guides read save-player-progress` | `zero guides read save-slots-level-unlocks-continue` | | An agent's `guides` tool, `path` = | `save-player-progress` | `save-slots-level-unlocks-continue` | | The files | [documentation/save-player-progress.guide/guide.md](documentation/save-player-progress.guide/guide.md) | [documentation/save-slots-level-unlocks-continue.guide/guide.md](documentation/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: ```lua 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`) | `mode` | What it is | Saves | On death (`Save.died()`) | Suits | |---|---|---|---|---| | `profile` | One 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 | | `slots` | Three 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 | | `checkpoint` | Saves 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 | | `roguelite` | Runs. 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. | `curve` | Rule | XP for level 1→2, 2→3, … 10→11 | Total XP to reach level 5 / level 10 | Top level | |---|---|---|---|---| | `steady` | 100 XP for every level. | 100, 100, 100, 100, 100, 100, 100, 100, 100, 100 | 400 / 900 | 50 (4,900 XP) | | `steep` | The 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,910 | 50 | | `quadratic` | The 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,800 | 50 (1,014,300 XP) | | `custom` | Your 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,100 | 820 / 7,170 | 10 with the default table | ```lua 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. | Screen | Presentations (first is not always the default) | Default | Suits | |---|---|---|---| | 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) · `false` | `ribbon` | celebration: 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 · `false` | `segmented` | thin: 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 bar | `grid` | grid: cosmetics, party · list: achievements, rpg | | Profile card (`card`) | `full` name, title, level ring, XP, unlocks and play stats · `badge` a compact nameplate | `full` | full: rpg, lobby · badge: shooter, scoreboard | | Save slot picker (`slots`) | `cards` three cards side by side · `list` three rows (always used on narrow screens) | `cards` | cards: rpg, story · list: mobile, puzzle | | Saved indicator (`saved`) | `badge` disk icon and "Saved" bottom right · `text` "Progress saved" and the reason at the top · `false` | `badge` | any | 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 ```lua 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: ```lua 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 ```lua 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`): | Field | What | |---|---| | `version` | the game's save layout version (see below); `kit` is saveKit's own layout number | | `totalXp`, `level`, `best` | XP and level (this run, in roguelite), best level and XP ever | | `unlocks` | `{ [id] = os.time() when unlocked }` | | `stats` | `playTime` (s), `sessions`, `deaths`, `kills`, `coins`, `levels`, `checkpoints`, `runs`, `xpEarned`, and any the game adds | | `currency` | meta currency | | `checkpoint` | `{ id, label, at }` | | `game` | the game's own fields (`defaults`, `Save.set`) | | `created`, `saved`, `saves` | timestamps 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: ```lua 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: ```lua 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. | Event | `info` | |---|---| | `xp` | `amount, reason, level, xp, need, totalXp` | | `levelUp` | `level, from, unlocked` (names) | | `unlock` | `id, name, rule, why` (`level`, `stat`, `event`, `manual`, `bought`) or `atLoad` | | `stat`, `currency` | `name, value, amount` / `value, amount` | | `checkpoint`, `levelComplete` | `id, label, new` / `id` | | `died`, `runEnded` | `mode, reverted, checkpoint, banked` / `banked, runXp, runLevel, died` | | `saved`, `saveFailed`, `saveRefused` | `reason, key, slot, mode, saves` / `reason, error` / `reason, why` | | `loaded`, `ready`, `migrated`, `newerSave`, `recovered` | `key, mode, slot, status, migratedFrom, fresh` / `status` / `from, to, steps, backup` / `version, reads` / `error` | | `slot`, `mode`, `theme`, `screens`, `panel` | `action, 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: ```lua 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) | Pass | What 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. | Option | Default | | |---|---|---| | `mode` | `"profile"` | saving style | | `curve`, `curveTable`, `maxLevel` | `"steady"`, default table, curve's own | levelling | | `version`, `migrations`, `defaults` | `1`, none, `{}` | the game's save layout | | `unlocks` | the nine defaults | unlock 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 | | `bankRate` | `0.1` | share of a roguelite run's XP banked as currency | | `namespace` | `"main"` | a separate set of saves (for example per game mode) | | `screens` | see Progression screens | presentations | | `hud` | `true` | `false` hides the HUD screens (panels still open) | | `kits` | none | the other kits to link: `{ trapline = require("Trapline.api"), scoreKit = require("scoreKit.core"), pickups = require("pickupsKit.api") }`; `false` unlinks one (see Other kits) | | `bridges` | all on, `scoreToXp = 0.1` | turn a linked kit off, and the share of scoreKit points that becomes XP | | `theme` | menusKit's | the look | | `loadWait`, `minSaveGap` | `2.5`, `0.5` | seconds 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: ```lua 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.