roblox-progression

Progression mechanics for hurreman's Roblox games:

stats that grow, and gates and requirements that need them;
upgrades and multipliers;
rebirth with declared resets;
carry and deposit;
objectives;
an idempotent ledger;
binding to roblox-world-builder maps;
an offline balance sim.

The game writes one config (shared/Config/Progression), builds the runtime objects in its own service with adapters, and keeps its own save, remotes and UI.

# wally.toml
[dependencies]
Progression = "hurreman/roblox-progression@0.1.2"

local Progression = require(ReplicatedStorage.Packages.Progression) -- modules load on first access
local problems = Progression.Config.validate(Config)

Modules

Module	Where	What
`Curves`	any	constant / linear / exponential / polynomial / steps / piecewise, with round and cap; `sum`, `maxAffordable`
`State`	any	the `Progress` save section, the view rules read, counter refs, reward amounts
`Requirements`	any	conditions as data with typed blockers, plus custom checks (`Register`)
`Modifiers`	any	the multiplier stack `(base + Σadd) × (1 + Σbonus) × Πmul`, scoped to a stat or source
`Sources`	any	passive, zone and action gains, and their rates
`Upgrades`	any	leveled and tiered prices and effects; quotes against the level the buyer saw
`Gates`	any	gauntlet thresholds, in-order passing, first-time gate and milestone rewards, gate pad pay
`Rebirth`	any	eligibility, cost, reward and a reset plan from declared `reset` / `keep`
`Objectives`	any	the next goal with `{need}` / `{have}` and progress
`Carry`	any	retrieval: access by area, capacity, drops, haul worth
`Config`	any	validation of the whole config with paths; wallet currencies
`Ledger`	server	all-or-nothing grants over a roblox-data wallet, once per op id (ids saved with the grant)
`Stats`	server	the authoritative ticker, zone sources from the server's position check, actions capped per second
`Shop`	server	upgrade purchases as ledger ops
`Gauntlet`	server	gate runs on a bound lane (GateBarrier fields or Breakable walls), put-back positions, first-time rewards, gate pads (free and paid, each ending the run), the finish per run token
`Prestige`	server	rebirth as one ledger op
`Carrier`	server	hauls: picks, hits, deposits per haul token, leave policy
`Binder`	server, client	binds by `WB_World` / `WB_Zone` / `WB_Role` / `WB_Id` keys (or a tag), never names; volumes and world-aligned bounds
`Sim`	offline	a persona playing a config; game-tools Recorder-shaped results

Every module's header has its full API. The roblox-progression-builder skill has the guide: mechanics, archetypes, binding, authority and testing.

Tests

lune run tests/run

The specs run on luau-spec. The server specs use the real roblox-data Currency and Profiles with its FakeProfileStore: from DevPackages, or else copied from ../roblox-data into build/. They cover:

authoritative gains;
costs and grants;
requirements;
idempotent grants;
rebirth resets;
replayed requests;
crash and rejoin;
the sim;
binding to world-builder-shaped maps, including a rebuilt zone.

roblox-progression

By @hurreman

roblox-progression

Modules

Tests

Package Details

Install command (Click to copy)

Version

License