Log inGet started
World

Crumple Zone: Crash Test Dummy Simulator

Branchmain
Commit8d4e06b8c8

README.md

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.

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

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