# DemoPad
A floor pad for the showcase's own demos. This is this world's own showcase content, not part of saveKit. Like saveKit's `SavePad`, each machine checks only its own player, and the pad draws its own glowing disc and floating label; it needs no sibling components.
Fields: `action`, `label` (text over the pad), `radius` (metres), `color`.
`action` values:
- `writeV1`: write a real version 1 save for your player.
- `upgradeV2`: load that save with the version 2 layout, upgrading it.
- `tamper`: try to write another player's profile card and report whether the engine refused it.
- `gallery`: open or close the screen gallery overlay.
# ShowcaseBoard
One live board in the showcase. This is this world's own showcase content, not part of saveKit.
Put it on an entity placed where the board should stand; it needs no sibling components and spawns its own panel and text as temporary children. The board faces the entity's forward (local -Z) and is drawn in the current menusKit look, with its title and lines from the showcase's `boards` module. The text is redrawn only when what it shows changes: the local player's profile, the look or the screens, or every couple of seconds for boards that show times and players.
Fields:
- `kind`: `welcome`, `mode`, `curve`, `screen`, `migration` or `players`.
- `arg`: the saving style, curve or screen kind the board shows (for `mode`, `curve` and `screen` boards).
# boards
The text of each showcase board, built as plain lines from the local player's live profile. This is this world's own showcase content, not part of saveKit.
- `content(kind, arg)`: `{ title, lines, inUse?, note?, mono? }` for one board. Kinds: `welcome`, `mode` (one per saving style), `curve` (one per curve), `screen` (one per screen kind, listing its presentations), `migration` (the v1 to v2 save upgrade before/after) and `players` (every connected player's card).
- `size(kind)` and `SIZES`: each board's width and height in metres.
Used by the showcase's `ShowcaseBoard` component, which draws the boards in the world. Reads from `saveKit.save`, `saveKit.catalog`, `saveKit.curves`, `saveKit.screens` and the showcase's `demo` module.
# demo
The showcase's saveKit setup and its live demos. This is this world's own showcase content, not part of saveKit.
- `config()`: the setup the showcase plays with (profile style, steady curve, game layout version 2).
- `V1_DEFAULTS`, `V2_DEFAULTS`, `MIGRATIONS`: the two game layouts and the migration from 1 to 2 (gold becomes coins, loose fields are grouped).
- `writeV1()`: writes a real version 1 save for the local player through saveKit running the version 1 layout.
- `upgradeV2()`: loads that save with the version 2 layout, so saveKit upgrades it, keeps the old copy at `<key>.v1` and saves the new one; `migrationState()` returns the before/after for the migration board.
- `tamper()`: tries to write another player's profile card from this machine and records whether the engine refused it; `tamperState()` returns the last result.
- `lines(rec)`: flattens a record into `path = value` lines for display.
Used by the showcase's `DemoPad` component and the `boards` module.
# gallery
The screen gallery overlay: every presentation of every saveKit progression screen side by side, each labelled with its name and the setting that picks it (e.g. `bar = "ring"`), with the one in use marked. Drawn by saveKit's own `screens` builders in the current look with the local player's profile. This is this world's own showcase content, not part of saveKit.
`tree(w, h)` returns the gallery widget tree for a screen of that size; `SCREEN` and `LAYER` are the UI screen id and layer it registers under.
Used by the showcase's `DemoPad` component (`action = "gallery"`), which opens and closes the overlay.
# 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.
# screens
The progression screens as widget trees, in every presentation, drawn in the current menusKit look (palette, fonts, panel frame).
- `skin(look)`: the drawing kit for a look; unknown names fall back to scifi.
- Builders, each returning one sized element: `bar` (thin, segmented, ring), `banner` (celebration, ribbon, toast), `saved` (badge, text), `toast`, `unlocks` (grid, list), `card` (full, badge), `slots` (cards, list), `button`.
- Whole trees: `hud(state, w, h, safe)` for the HUD and `panelTree` for the unlocks, card and slot panels over a dimmed screen.
Mostly internal: the `SaveHost` component places these on the HUD. Other content can call the builders directly to draw the same screens elsewhere, as the showcase does on its world boards. Requires menusKit (`menusKit.themes`, `menusKit.icons`).
# curves
The levelling curves: how much XP each level costs, and how a total XP turns into a level, the XP into that level and the XP the next level needs.
- `steady`: 100 XP for every level, up to level 50.
- `steep`: 100 XP for the first level, then 40% more each level (rounded to tens), up to level 50.
- `quadratic`: `25 × n² + 75` XP from level n to n+1 (100, 175, 300, 475, 700, …), up to level 50.
- `custom`: your own table of XP costs; its length sets the top level.
`get(name, opts)` builds a curve object with `cost(n)`, `totalFor(level)`, `levelFor(total)` and `table(n)`; `canonical` normalises a name (aliases such as `linear` or `exponential`) and `describe` returns the catalogue entry.
Mostly internal: `saveKit.save` picks the curve from `Save.setup({ curve = ... })`, and game code reaches the live curve through `Save.curve()`. Pure functions with no engine calls, so tests and tools can use it directly.
# bridges
Optional links to other kits. saveKit names none of them, so installing saveKit brings none of them along. A game links a kit by passing it in its setup:
```lua
Save.setup({ kits = { trapline = require("Trapline.api"), scoreKit = require("scoreKit.core"), pickups = require("pickupsKit.api") } })
```
- Trapline: reaching a checkpoint calls `Save.checkpoint`; losing a life calls `Save.died`.
- scoreKit: points awarded become XP (10% by default, `bridges.scoreToXp`).
- pickupsKit: XP orbs give their XP, coins count through `Save.coin`.
Each event is acted on only by the machine of the player it belongs to. `start(Save, cfg, kits)` connects the kit modules passed in (never one that was not), `stop(name?)` disconnects one or all, `active` reports which are connected, `available` which of the three are installed (checked with `asset.exists`, which loads nothing and records no dependency), `failures` the modules that were passed in but are not the kit they were passed as (each is tried once, with one warning), and `reset` disconnects and forgets those failures. `canonical` turns any spelling of a kit name into `trapline`, `scoreKit` or `pickups`. The `_trapline`, `_score`, `_pickup` handlers and `_wire` are exposed for tests.
Internal: `Save.setup` and the `SaveHost` component call `start`. Games turn a linked kit off with `Save.setup({ kits = { scoreKit = false } })` or `bridges = { scoreKit = false }`.
# 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.
# api
The one interface to pickupsKit: `local Pickups = require("pickupsKit.api")`.
- **Pickups:** `spawn`, `burst`, `setLook`, `collect`, `available`, `all`, `openChest`.
- **Counters:** `get`, `counts`, `allCounts`, `add`, `set`, `spend`, `reset`, `ledger`.
- **Letters:** `letters`, `spelled`, `giveLetter`, `clearLetters`.
- **Power-ups:** `givePowerup`, `powerup`, `powerupLeft`, `activePowerups`, `damageMultiplier`.
- **Catalog:** `looks` (filter by style, kind, effect or size), `look`, `styles`, `kinds`, `effects`, `powerups`, `counters`, `sizes`, `dependencies`.
- **Identity and collectors:** `keyOf`, `nameOf`, `localKey`, `localAvatar`, `owns`, `addCollector`, `removeCollector`.
- **Setup and events:** `setup`, `installDamageFilter`, and `on` for collect, counter, letter, powerup, powerupEnd, respawn, expire, burst and chest.
It also runs the components. The owner of each pickup decides claims and announces them with event ids that every peer de-duplicates, and only the ledger's owner writes counts. Functions starting with `_` are the components' hooks. The package README lists every argument.
# core
The runtime behind `scoreKit.score`: who the keeper is, player keys, the keeper's checks on requests from other machines, prediction on the other machines, the synced snapshot, events, rounds (with or without MatchFlow), time runs and posting to the board. Game code uses `scoreKit.score` instead.
# profile
The rules applied to one saved record, as pure functions with no engine calls.
- XP and levels: `view`, `addXP`, `relevel`.
- Stats and unlocks: `addStat`, `unlock`, `ruleMet`, `checkUnlocks` (rules by level, by stat, by event) and `buy` (rules with a `cost`, paid in meta currency).
- Roguelite: `endRun` resets the run's XP and level, keeps unlocks, currency and lifetime stats, and banks part of the run's XP as currency.
- Public card: `card` builds what other players see, `sanitizeCard` makes a card read from another player safe to draw, `title` picks the best `title_` unlock.
`DEFAULT_UNLOCKS` is the unlock list used when a game names none.
Internal: `saveKit.save` drives these for the local player. Tests and tools can call them on any record.
# store
Where saves live. Each player's saves sit in their own `runtime_data.player(id)` store under `saveKit/<namespace>/...`, which survives leaving and rejoining. Any machine can read any player's store; the engine refuses a write to a store that is not the writer's own, so one player cannot change another's profile.
- Local player: `localId`, `localName`, `mine`, `get`, `set`, `delete`, `onChange`.
- Other players: `of`, `read`, `onAnyChange`, `users` (everyone connected).
- `key(ns, name)` builds a save's path; `writeOther` attempts a write to another player's store and returns the engine's refusal (used by tests and the showcase's tamper check).
- `use(fn, others)` swaps the live store for a stand-in in tests; `use(nil)` restores it.
Internal: `saveKit.save` does all reading and writing through this module. Read and write calls never raise; they return nil or `ok, error`.
# score
The module a game talks to: `local Score = require("scoreKit.score")`. `Score.add(player, 10)` and friends, ratings, rounds, time runs, boards, styles and events. The package README is its full reference.
# Trapline.api
The kit's public interface: TL.attach for players, per-player state (lives, checkpoint, game over), checkpoints and respawn (through Lifeline's spawn picker and SecondWind's revive), hazard hits through SecondWind, events (TL.on), the shared clock hazards run on (TL.now), switching looks and themes, and the labelled catalog (TL.catalog, TL.find). Required by every Trapline component and by game code. Full reference in the package README.