# ladder
`Ladder.new({ id, steps, start, goals, match, store? })` makes an unlock ladder. Steps are passed in order; each one's `reward` list of `{ category, id }` pairs unlocks items on top of `start`. API: `done()`, `complete(id, info)`, `level(done?)`, `unlocked(done?)`, `unlockedBy(cat, id)`, `goalText(goal)`, `goalMet(goal, result)`, `matches(step, result)`, `credit(result, activeId?, extra?)`, `savePref(key, v)`, `loadPref(key, default)`, `count()`, `byId`, `steps`, `session` (unsaved scratch). `Ladder.memoryStore()` gives an in-memory store for tests. Saved per player under `<id>/done/` and `<id>/prefs/` in `runtime_data.player(localId)`. Used by `crashSession` and the Crumple Zone game.
# unlockLadder
An ordered **ladder of challenges** with **unlocks** and **saved progress**, for any game. Each step has a
fixed config, a goal read off whatever result your game produces, and a reward that unlocks items for free
play. Pure rules and data: no UI and no game types, so a racing game, a puzzle game or a crash-test game
uses the same module (Crumple Zone's 15-test programme is built on it, with `crashSetup.goals`).
## First example
Put this in any scene's `entrypoint.luau` and press Play; the Output shows the ladder moving.
```lua
local Ladder = require("unlockLadder.ladder")
function onLoad()
local L = Ladder.new({
id = "demoLadder", -- save key root
store = Ladder.memoryStore(), -- drop this line to save per player
start = { car = { "hatch" } }, -- unlocked from the start
steps = {
{ id = "first", title = "First lap", goal = { kind = "run" }, reward = { { "car", "coupe" } } },
{ id = "fast", title = "Under a minute", goal = { kind = "under", value = 60 }, reward = { { "car", "truck" } } },
},
goals = { under = {
text = function(g) return "Finish under " .. g.value .. " s" end,
met = function(g, r) return r.time < g.value, string.format("%.1f s", r.time) end,
} },
})
print(L:level(), L:goalText(L.steps[2].goal)) -- 1 Finish under 60 s
local c = L:credit({ time = 72 }) -- passes "first" (run)
print(c.step.id, c.met, c.unlocked[1][2]) -- first true coupe
print(L:credit({ time = 55 }).step.id, L:level()) -- fast 3
print(L:unlocked().car.truck, L:unlockedBy("car", "truck").title) -- true Under a minute
end
```
With `store` left out, progress is saved per player: the next session starts at level 3.
## Steps, goals and matching
- A **step** is `{ id, title, sub?, std?, config?, goal = { kind, value? }, reward = { { category, id }, ... } }`.
`index` is filled in. `config` is yours (the set-up the step fixes); the ladder never reads it.
- A **goal kind** is `{ text = function(goal) -> string, met = function(goal, result) -> (boolean, valueText) }`.
`run` (always met) is built in; pass your own in `goals`.
- `match(step, result) -> boolean` says whether a result counts for a step (default: every result does).
`credit(result, activeId?)` tries the active step first, then every open step not yet passed, and returns
`{ step, met, value, already, unlocked, nextStep }` for the first match (nil when none). A met goal is
saved with `complete`.
## API
| Call | Returns |
|---|---|
| `Ladder.new(opts)` | a ladder; `opts`: `id`, `steps`, `start`, `goals`, `match`, `store` |
| `L:done()` | `{ [stepId] = info }` of passed steps |
| `L:complete(id, info?)` | saves a pass |
| `L:level(done?)` | index of the first unpassed step (`count()+1` when all are) |
| `L:unlocked(done?)` | `{ [category] = { [id] = true } }` |
| `L:unlockedBy(cat, id)` | the step that unlocks it, or nil |
| `L:goalText(goal)`, `L:goalMet(goal, result)`, `L:matches(step, result)` | goal rules |
| `L:credit(result, activeId?, extra?)` | the credit record above |
| `L:savePref(key, v)`, `L:loadPref(key, default)` | per-player preferences |
| `Ladder.memoryStore()` | a store for tests (`store = Ladder.memoryStore()`) |
## Saving
`runtime_data.player(runtime_data.localId())`, under `<id>/done/<stepId>` and `<id>/prefs/<key>`. Only the
local player's own store is written, so it works the same on every peer. A guest (no id) keeps progress in
memory for the session. Pass `store` (anything with `get`, `set`, `list`) to keep it elsewhere.
## Tests
`unlockLadder` suite (`zero tests run unlockLadder`, edit mode): levels, unlocks, `unlockedBy`, goals,
matching and crediting (active step first, a failed goal saves nothing, a re-pass is `already`), prefs, a
custom store, and the first example above run as written against a memory store.