api
The one interface: `local Prog = require("progressionKit.api")`. XP and levels (`addXp`, `level`, `progress`), ranks (`addRenown`, `completeQuest`, `rank`, `canPromote`, `promote`), skill trees (`unlock`, `canUnlock`, `has`, `points`, `respec`, `abilities`), stats (`statBonus`, `…
progressionKit.api (Prog)
The one interface: local Prog = require("progressionKit.api"). XP and levels (addXp, level, progress), ranks (addRenown, completeQuest, rank, canPromote, promote), skill trees (unlock, canUnlock, has, points, respec, abilities), stats (statBonus, stats, useStats), events (on, onLevel, onRank, onUnlock), live swaps (setLadder, setCurve, setLayout, setLook) and the screen (open, close, toggle). Host-validated in multiplayer, saved per player.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2progressionKit.api (Prog): the one interface a game uses for levels, adventurer ranks and skill trees. Every player has their own XP, level, rank, renown, skill points and unlocks. Changes are decided by the room host (or locally when offline): a client asks the host with `multiplayer.send`, the host checks the request and sends everyone the result, so all peers and late joiners agree. Each player's own machine saves their record in their own runtime data, so it survives restarts.
buildConfig(opts: any) → any
| arg | type | description |
|---|---|---|
| opts | any |
emit(event: string, info: any) → void
| arg | type | description |
|---|---|---|
| event | string | |
| info | any |
config( ) → any
isPlay( ) → boolean
connected( ) → boolean
isAuthority( ) → boolean
send(channel: string, ...: any) → void
| arg | type | description |
|---|---|---|
| channel | string | |
| ... | any |
myPeer( ) → number
localId( ) → string
The local player's id: their account identity (runtime_data.localId), or "local" for a guest or outside play.
pidOf(pid: any) → string
| arg | type | description |
|---|---|---|
| pid | any |
rec(pid: string) → any
| arg | type | description |
|---|---|---|
| pid | string |
persistNow(pid: string) → void
| arg | type | description |
|---|---|---|
| pid | string |
persistSoon(pid: string, now: boolean?) → void
| arg | type | description |
|---|---|---|
| pid | string | |
| now | boolean? |
rankInfo(i: number) → any
| arg | type | description |
|---|---|---|
| i | number |
apply(op: string, pid: string, a: any, b: any) → void
Apply one operation to a record on the authority. Returns ok, reason, events.
| arg | type | description |
|---|---|---|
| op | string | |
| pid | string | |
| a | any | |
| b | any |
promoteAuto( ) → void
fire(pid: string, events: { any }) → void
| arg | type | description |
|---|---|---|
| pid | string | |
| events | { any } |
broadcastState(pid: string, events: { any }, ack: number?) → void
| arg | type | description |
|---|---|---|
| pid | string | |
| events | { any } | |
| ack | number? |
now( ) → number
sweepPending(t: number) → void
Client: emit 'timeout' once for each request the host left unanswered past REQUEST_TIMEOUT, keep it queued and send it again (the host applies a request number only once).
| arg | type | description |
|---|---|---|
| t | number |
scheduleSweep( ) → void
tick( ) → void
allowed(op: string, pid: string, fromPeer: number?) → boolean
What a request from `fromPeer` may do (host side).
| arg | type | description |
|---|---|---|
| op | string | |
| pid | string | |
| fromPeer | number? |
request(op: string, pid: string, a: any, b: any) → void
| arg | type | description |
|---|---|---|
| op | string | |
| pid | string | |
| a | any | |
| b | any |
onReq(fromPeer: number, op: any, pid: any, a: any, b: any, seq: any) → void
| arg | type | description |
|---|---|---|
| fromPeer | number | |
| op | any | |
| pid | any | |
| a | any | |
| b | any | |
| seq | any |
onState(fromPeer: number, pid: any, raw: any, events: any, ack: any) → void
| arg | type | description |
|---|---|---|
| fromPeer | number | |
| pid | any | |
| raw | any | |
| events | any | |
| ack | any |
onHello(fromPeer: number, pid: any, saved: any) → void
| arg | type | description |
|---|---|---|
| fromPeer | number | |
| pid | any | |
| saved | any |
onAll(fromPeer: number, all: any) → void
| arg | type | description |
|---|---|---|
| fromPeer | number | |
| all | any |
bindNet( ) → void
flushQueue( ) → void
loaded(pid: string, saved: any) → void
| arg | type | description |
|---|---|---|
| pid | string | |
| saved | any |
loadLocal( ) → void
retry( ) → void
setup(opts: any?) → any
Configure the kit. Every field is optional: `curve` ("linear" | "quadratic" | "exponential" | "table" | spec table | list of costs), `maxLevel` (cap, 50), `ladder` (id or a ladder definition), `autoPromote` (true), `pointsPerLevel` (number, table or fn(level)), `startPoints`, `trees` (ids or definitions), `layout` (classic | radial | grid | linear | hex), `look` (anime | parchment | holo | minimal | pixel), `growth` (stat per level), `base` (stats at level 1), `namespace` (save slot name), `persist` (true), `maxGrant` (largest single grant), `banners` (true). Calling it again swaps settings live; every record is re-derived from its XP and unlocks.
| arg | type | description |
|---|---|---|
| opts | any? |
config( ) → any return config
The live configuration (curve, ladder, trees, layout, lookId, ...).
begin( ) → void
Start a play session: binds the network, loads the local player's save and tells the host. Called by the Progression component; safe to call more than once.
finish( ) → void
End the play session: saves the local player's record now.
pending( ) → number return
Requests this client sent that the host has not answered yet (each one is sent again every REQUEST_TIMEOUT seconds until it is).
ready(pid: string?) → boolean
Whether the local player's save has loaded (requests made before it are queued, never lost).
| arg | type | description |
|---|---|---|
| pid | string? |
ensure( ) → void
addXp(pid: string?, n: number, source: string?) → void
Give a player XP (`source` is any word: "kill", "quest"...). Returns ok, reason ("sent" on a client: the host decides).
| arg | type | description |
|---|---|---|
| pid | string? | |
| n | number | |
| source | string? |
level(pid: string?) → number return rec
| arg | type | description |
|---|---|---|
| pid | string? |
xp(pid: string?) → number return rec
Total XP earned (what the level is derived from).
| arg | type | description |
|---|---|---|
| pid | string? |
progress(pid: string?) → any
{ level, into, need, pct, total, cap, maxed } for a bar.
| arg | type | description |
|---|---|---|
| pid | string? |
levelCap( ) → number return config
xpForLevel(level: number) → number
XP from `level` to the next under the current curve.
| arg | type | description |
|---|---|---|
| level | number |
addRenown(pid: string?, n: number, source: string?) → void
Add renown (rank points). Negative takes some away; a rank already held is kept.
| arg | type | description |
|---|---|---|
| pid | string? | |
| n | number | |
| source | string? |
renown(pid: string?) → number return rec
| arg | type | description |
|---|---|---|
| pid | string? |
completeQuest(pid: string?, questId: string?, renown: number?) → void
Count a completed quest (a quest id counts once) and optionally grant renown with it.
| arg | type | description |
|---|---|---|
| pid | string? | |
| questId | string? | |
| renown | number? |
quests(pid: string?) → number return rec
| arg | type | description |
|---|---|---|
| pid | string? |
rank(pid: string?) → any
The player's rank in the current ladder: { id, name, short, color, accent, renown, level, quests, perks, title, index }.
| arg | type | description |
|---|---|---|
| pid | string? |
nextRank(pid: string?) → void
The next rank (nil at the top) and what is still missing for it.
| arg | type | description |
|---|---|---|
| pid | string? |
canPromote(pid: string?) → void
Can the player be promoted now? Returns ok, missing list.
| arg | type | description |
|---|---|---|
| pid | string? |
promote(pid: string?, force: boolean?) → void
Promote one rank (when eligible, or always with `force`: a game's own exam or a GM).
| arg | type | description |
|---|---|---|
| pid | string? | |
| force | boolean? |
unlock(pid: string?, nodeId: string) → void
Take one rank of a skill node. Returns ok, reason (unknown, maxed, points, level, requires, exclusive).
| arg | type | description |
|---|---|---|
| pid | string? | |
| nodeId | string |
canUnlock(pid: string?, nodeId: string) → void
Would `unlock` succeed now? ok, reason, cost.
| arg | type | description |
|---|---|---|
| pid | string? | |
| nodeId | string |
has(pid: string?, nodeId: string) → boolean return
Has the player at least one rank of the node?
| arg | type | description |
|---|---|---|
| pid | string? | |
| nodeId | string |
nodeRank(pid: string?, nodeId: string) → number return rec
| arg | type | description |
|---|---|---|
| pid | string? | |
| nodeId | string |
points(pid: string?) → number return rec
Unspent skill points.
| arg | type | description |
|---|---|---|
| pid | string? |
grantPoints(pid: string?, n: number) → void
Grant (or with a negative number take back) bonus skill points beyond the per-level ones.
| arg | type | description |
|---|---|---|
| pid | string? | |
| n | number |
respec(pid: string?, treeId: string?) → void
Refund every node (or one tree's). Returns ok, reason.
| arg | type | description |
|---|---|---|
| pid | string? | |
| treeId | string? |
abilities(pid: string?) → void
Abilities unlocked by nodes: { [abilityName] = nodeId }.
| arg | type | description |
|---|---|---|
| pid | string? |
commands(pid: string?) → void
| arg | type | description |
|---|---|---|
| pid | string? |
hasAbility(pid: string?, name: string) → boolean return Prog
| arg | type | description |
|---|---|---|
| pid | string? | |
| name | string |
statBonus(pid: string?, stat: string) → number
Bonus to a stat from skill nodes and the current rank's perks.
| arg | type | description |
|---|---|---|
| pid | string? | |
| stat | string |
stats(pid: string?) → void
Every stat for a player: base + growth per level + statBonus, then each `useStats` function may change it.
| arg | type | description |
|---|---|---|
| pid | string? |
stat(pid: string?, stat: string) → number return Prog
| arg | type | description |
|---|---|---|
| pid | string? | |
| stat | string |
useStats(fn: (string, { [string]: number }) → void
Plug a game's own stats in: `fn(pid, stats)` changes the table in place (gear bonuses, buffs). Returns a handle for `Prog.off`.
| arg | type | description |
|---|---|---|
| fn | (string, { [string]: number } |
on(event: string, fn: (any) → void
Listen to an event: xp, level, renown, quest, rank, unlock, respec, change, ready, denied, saved, open, close. `fn(info)`; info.pid names the player. Returns a handle.
| arg | type | description |
|---|---|---|
| event | string | |
| fn | (any |
off(handle: number) → void
Stop a listener or a useStats function by its handle.
| arg | type | description |
|---|---|---|
| handle | number |
onLevel(fn: (any) → void
| arg | type | description |
|---|---|---|
| fn | (any |
onRank(fn: (any) → void
| arg | type | description |
|---|---|---|
| fn | (any |
onUnlock(fn: (any) → void
| arg | type | description |
|---|---|---|
| fn | (any |
onXp(fn: (any) → void
| arg | type | description |
|---|---|---|
| fn | (any |
view(pid: string?) → any
Everything a screen needs for one player, in one table.
| arg | type | description |
|---|---|---|
| pid | string? |
players( ) → void
Every player with a record (ids).
record(pid: string?) → any return State
A copy of a player's raw record (what is saved).
| arg | type | description |
|---|---|---|
| pid | string? |
reset(pid: string?) → void
Start a player over (level 1, lowest rank, no unlocks). Saved like any change.
| arg | type | description |
|---|---|---|
| pid | string? |
save( ) → void
Save the local player's record now. Returns ok, error.
ladders( ) → void
trees( ) → void
layouts( ) → void
looks( ) → void
curves( ) → void
defineLadder(def: any) → any return Ladders
| arg | type | description |
|---|---|---|
| def | any |
defineTree(def: any) → any return Trees
| arg | type | description |
|---|---|---|
| def | any |
defineLook(def: any) → any return Looks
| arg | type | description |
|---|---|---|
| def | any |
ladder(id: string?) → any return if id then Ladders
| arg | type | description |
|---|---|---|
| id | string? |
tree(id: string) → any return Trees
| arg | type | description |
|---|---|---|
| id | string |
node(id: string) → any return Trees
| arg | type | description |
|---|---|---|
| id | string |
swap(key: string, value: any) → void
| arg | type | description |
|---|---|---|
| key | string | |
| value | any |
setLadder(id: string) → void
Swap the rank ladder (one setting): letters, lettersSS, metals, stars, belts, military or a custom id.
| arg | type | description |
|---|---|---|
| id | string |
setCurve(spec: any) → void
Swap the XP curve (levels re-derived from XP).
| arg | type | description |
|---|---|---|
| spec | any |
setLayout(id: string) → void
Swap the skill tree layout: classic, radial, grid, linear, hex.
| arg | type | description |
|---|---|---|
| id | string |
setLook(id: string) → void
Swap the look: anime, parchment, holo, minimal, pixel.
| arg | type | description |
|---|---|---|
| id | string |
open(treeId: string?) → void
Open the progression screen for the local player (optionally on a tree).
| arg | type | description |
|---|---|---|
| treeId | string? |
close( ) → void
toggle( ) → void
isOpen( ) → boolean return uiState
ui( ) → any return uiState end
The screen's cursor state (tree, selected node). Used by the component.
_resetForTests(opts: any?) → void
Tests: start over with no players, no listeners and default settings (or `opts`).
| arg | type | description |
|---|---|---|
| opts | any? |
_useNet(net: any) → void
Tests: act as a peer. `net = { host, connected, peer, send(channel, ...), acceptState }`; nil restores the real network.
| arg | type | description |
|---|---|---|
| net | any |
_deliver(channel: string, fromPeer: number, ...: any) → void
Tests: deliver a message as if `fromPeer` sent it.
| arg | type | description |
|---|---|---|
| channel | string | |
| fromPeer | number | |
| ... | any |
_setClock(t: number?) → void
Tests: set the clock requests are timed by (nil uses the real clock).
| arg | type | description |
|---|---|---|
| t | number? |
_sweep( ) → void
Tests: check unanswered requests now, as the timer does every second.
_setLocalId(pid: string?) → void
Tests: pretend to be this local player id.
| arg | type | description |
|---|---|---|
| pid | string? |
_load( ) → void
Tests: load the local player's save now (Store.use a stand-in first).
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.