progressionKit
Give every player XP and levels, an adventurer guild rank (F to S, or metals, stars, belts, military, kyu and dan grades, Roman numerals, security clearance or your own ladder) and skill trees to spend points in, behind one API, `Prog`. Every variant swaps with one setting: the X…
progressionKit: Levels, Adventurer Ranks and Skill Trees
Give every player XP and levels, an adventurer guild rank (F to S, or metals, stars, belts, military, kyu and dan grades, Roman numerals, security clearance or your own ladder) and skill trees to spend points in, behind one API, Prog. Every variant swaps with one setting: the XP curve, the rank ladder, the skill tree layout and the look. It works with mouse, keyboard, gamepad and touch (phone portrait and landscape), in multiplayer (the room host validates every change, late joiners get correct values) and saves each player's progress so it survives a restart.
Version 1.0.1. No dependencies.
Version notes
- 1.0.1: the open key is a setting. The Progression component's
openKey(defaultTab, any key name such asKeyP,PorF1,""for none),altKey(defaultKeyK,""for none) andpadOpen(defaultselect,""for none) replace the hard-wired Tab / K / View, so a game that uses Tab for lock-on setsopenKey = ""or another key; the HUD tooltip names the real keys. A client request the host never answers (for example the host runs no Progression) now emitsdeniedwithreason = "timeout"andqueued = trueafterProg.REQUEST_TIMEOUT(4 s); the request stays queued and is sent again until the host answers, and the host applies each request number once, so a resend never doubles a grant.Prog.pending()counts unanswered requests. New rank ladderskyuDan(6th kyu to 3rd dan),roman(I to X) andclearance(Level 0 Visitor to Level 5 Omega), each with its own badge (belt with grade tab and dan bars, laurel shield, keycard). New skill tree layoutcards: each tier is a hand of cards fanned in an arc. All are in the gallery. 32 tests. - 1.0.0: first release.

Quick start
- Install progressionKit (
zero zeromind installAsset <guid>or search ZeroMind for "progressionKit"). - Add the Progression component to any entity of your scene. Press Play: a HUD with your level, XP bar and rank badge appears top left. Press Tab or K (gamepad View, or tap the HUD) for the progression screen; the component's
openKey,altKeyandpadOpenfields change those keys. - From game code:
local Prog = require("progressionKit.api")
-- an enemy died: XP and renown for the local player
Prog.addXp(nil, 60, "kill")
Prog.addRenown(nil, 30, "kill")
Prog.completeQuest(nil, "rescue_the_cat", 50) -- counts once, +50 renown
if Prog.has(nil, "cleave") then hitEverythingInArc() end
local damage = Prog.stat(nil, "atk")
For a playable sample, add ProgressionDemo to an entity: it builds a training yard of dummies to level up on.
Choose a style (one setting each)
Prog.setup({
curve = "quadratic", -- linear | quadratic | exponential | table (or a list of costs)
maxLevel = 50,
ladder = "letters", -- letters | lettersSS | metals | stars | belts | military | kyuDan | roman | clearance | your own
layout = "classic", -- classic | radial | grid | linear | hex | cards
look = "anime", -- anime | parchment | holo | minimal | pixel
trees = { "vanguard", "arcanist", "whisperer" },
pointsPerLevel = 1, -- or a table { [level] = n } or function(level)
})
Prog.setLadder("belts"); Prog.setLayout("hex"); Prog.setLook("pixel"); Prog.setCurve("exponential")
| Setting | Ids |
|---|---|
| XP curves | linear (base + step per level), quadratic (base x n squared + step), exponential (base x growth ^ n, rounded), table (your own list; its length sets the cap) |
| Rank ladders | letters F E D C B A S (adventurer guild), lettersSS adds SS, metals bronze silver gold platinum mithril adamantite, stars 1 to 5, belts white yellow orange green blue purple brown black, military recruit to general, kyuDan 6th kyu to 1st kyu then 1st to 3rd dan, roman tiers I to X, clearance sci-fi security clearance Level 0 Visitor to Level 5 Omega, or Prog.defineLadder |
| Tree layouts | classic branching tree (turns sideways on wide panels), radial constellation, grid board, linear track, hex web, cards card deck (one fanned hand of cards per tier) |
| Looks | anime, parchment, holo (sci-fi hologram), minimal, pixel |
| Built-in trees | vanguard (melee: Iron Skin, Power Strike, Cleave, Battle Cry, Berserk), arcanist (magic with a fire OR frost choice, Meteor), whisperer (Software Whispering: Read the Source, Debug Sight, Hotfix, Overclock, Rewrite, Root Access) |
The API
XP and levels: Prog.addXp(pid, n, source), Prog.level(pid), Prog.xp(pid) (total), Prog.progress(pid) ({ level, into, need, pct, maxed }), Prog.levelCap(), Prog.xpForLevel(level).
Ranks: Prog.addRenown(pid, n, source), Prog.completeQuest(pid, questId?, renown?), Prog.rank(pid) ({ id, name, short, color, title, perks, index }), Prog.nextRank(pid) (next rank and what is missing), Prog.canPromote(pid), Prog.promote(pid, force?). A rank asks for renown and/or gates (level, quests); the ladder's rule (points, gates, both) says which. With autoPromote (default) players climb by themselves; turn it off for a guild exam and call Prog.promote.
Skill trees: Prog.unlock(pid, nodeId), Prog.canUnlock(pid, nodeId) (ok, reason, cost), Prog.has(pid, nodeId), Prog.nodeRank, Prog.points(pid), Prog.grantPoints(pid, n), Prog.respec(pid, treeId?), Prog.abilities(pid), Prog.commands(pid), Prog.hasAbility(pid, name). Refusal reasons: unknown, maxed, points, level, requires, exclusive.
Stats: Prog.stats(pid) = base + growth per level + node stats + rank perks, then every Prog.useStats(fn) hook (fn(pid, stats) changes the table: gear, buffs, a health kit). Prog.stat(pid, name), Prog.statBonus(pid, name) (nodes + rank perks only).
Events: Prog.on(event, fn) for xp, level, renown, quest, rank, unlock, respec, change, ready, denied, saved, open, close; shortcuts Prog.onLevel, Prog.onRank, Prog.onUnlock, Prog.onXp; Prog.off(handle). Every info carries pid.
Screen: Prog.open(treeId?), Prog.close(), Prog.toggle(), Prog.isOpen(). Reading: Prog.view(pid), Prog.players(), Prog.record(pid). Prog.reset(pid) starts over; Prog.save() saves now.
pid is a player id; nil means the local player (Prog.localId(), the account identity).
Your own content
Prog.defineTree({ id = "chef", name = "Chef", color = "#ffb347", nodes = {
{ id = "knife_work", name = "Knife Work", stats = { atk = 2 }, maxRank = 3 },
{ id = "flambe", name = "Flambe", ability = "flambe", requires = { "knife_work" }, cost = 2, minLevel = 5 },
{ id = "sous_vide", name = "Sous Vide", exclusive = "style", requires = { "knife_work" } },
{ id = "smoker", name = "Smoker", exclusive = "style", requires = { "knife_work" } },
} })
Prog.defineLadder({ id = "pirates", name = "Crew", style = "custom", rule = "both", ranks = {
{ id = "swab", name = "Swabbie" }, { id = "mate", name = "First Mate", renown = 300, level = 5 },
{ id = "captain", name = "Captain", renown = 1200, quests = 5, perks = { atk = 5 } },
} })
Prog.defineLook({ id = "ocean", accent = "#1fb5ff", panel = "#0a2236" }) -- the rest comes from minimal
Controls
| Mouse / keyboard | Gamepad | Touch | |
|---|---|---|---|
| Open / close | Tab or K (openKey, altKey), Esc | View (padOpen, select), B | tap the HUD, X |
| Move between skills | arrows or WASD | d-pad or left stick | tap a skill |
| Unlock | Enter or Space, or click twice | A | tap twice, or the Unlock button |
| Switch tree | Q / E | LB / RB | tabs or < > |
| Respec | Respec button | X | Respec button |
Screens sit on UI layers 205 (HUD), 210 (screen) and 220 (banners), above touch-control layers, so taps reach them.
Multiplayer
Each player has their own XP, level, rank, renown, skill points and unlocks. A change on the room host (or offline) applies at once and is sent to everyone. A client sends a request (multiplayer.send) and the host checks it: the amount is valid, the request comes from the peer that owns that player, the unlock rules hold. The host then sends the result to all peers. A joining player sends their saved record; the host checks it (sanitize: level from XP, impossible unlocks dropped) and answers with everyone's records, so late joiners see correct values. The host leaving is fine: every peer already holds every record. A request the host does not answer within Prog.REQUEST_TIMEOUT seconds (4) emits denied with reason = "timeout" once, stays queued and is sent again every 4 s until the host answers; each request carries a number the host applies only once.
Saving
Each player's own machine saves their record in their own runtime_data.player(id) store under progressionKit/<namespace>, a moment after a change and at once on level up, rank up and unlock. The engine refuses writes to anyone else's store. A record that arrives late after joining is waited for; requests made meanwhile are queued, never lost. A save that is broken or edited is sanitized on load. Use namespace to keep two games in one world apart.
Plugging in your game's stats
local Gear = require("gearStatsKit.api") -- or SecondWind health, or your own
Prog.useStats(function(pid, stats)
stats.atk += Gear.bonus(pid, "atk")
end)
Prog.onLevel(function(info) Health.setMax(info.pid, Prog.stat(info.pid, "hp")) end)
Prog.onUnlock(function(info) if info.ability then Abilities.grant(info.pid, info.ability) end end)
What is inside
| Asset | What |
|---|---|
api | Prog, the one interface |
curves, ladders, trees, layouts, looks, state, store | pure building blocks, usable alone |
ui | widget-tree builders: badges, ladder strip, tree panel, screen, HUD, banners |
Progression component | HUD, screen, input, banners for the local player |
ProgressionGallery component | every ladder and layout in every look; phone previews |
ProgressionDemo component | the training yard demo |
progressionKitTests | 32 tests: curves, ranks (including kyuDan, roman, clearance), unlock rules, layouts (including cards), open keys and the HUD hint, save/load, multiplayer and the request timeout. Run zero tests run progressionKitTests |
| guides | how-to and example (below) |
Guides
- How to add a skill tree and adventurer ranks to my game (
how-to-add-a-skill-tree-and-adventurer-ranks-to-my-game) - Example: build a small RPG with levels, guild ranks and a skill tree (
example-build-a-small-rpg-with-levels-guild-ranks-and-a-skill-tree)
Open them with zero guides read <name> or the editor's Docs panel.
Known limits
- The demo's dummies are local to each machine (each player trains on their own); kills still give XP through the host.
- Two sessions of the same account share one save: the last write wins.
- Abilities and commands are names: the game decides what they do (the demo shows Cleave, Debug Sight and an Overclock aura).
Scoped to this part · feeds back into the world's score.