Skip to main content
forge-progression tracks how a character advances: experience, levels off a configurable curve, unspent attribute points, and unlocks (refcounted flags other systems use to gate content like recipes or abilities).

​
Concepts

  • XP & levels. GainXP adds experience; crossing a threshold levels up and awards points. The curve is floor(Base * (L-1)^Factor).
  • Unlocks. A source-scoped, refcounted set. forge-crafting knowledge and ability learning ride on unlocks, so the same id can be granted by several sources and only revoked when the last releases it.

​
Exports

ExportSignatureReturns
GetProgressionGetProgression(character_id)Result with { level, xp_total, xp_next, unspent_pts }
GetLevelGetLevel(character_id)Result{ data = { level } }
GainXPGainXP(character_id, amount)Result (may trigger a level-up)
SpendPointsSpendPoints(character_id, n)Result
GrantUnlockGrantUnlock(character_id, unlock_id, source)Result (refcounted by source)
RevokeUnlockRevokeUnlock(character_id, unlock_id, source)Result
HasUnlockHasUnlock(character_id, unlock_id)Result
GetUnlocksGetUnlocks(character_id)Result{ data = { unlocks } }
exports["forge-progression"]:GainXP(cid, 150)
exports["forge-progression"]:GrantUnlock(cid, "ability:fireball", "quest:first_lesson")

​
Events

EventPayloadWhen
forge-progression:server:loaded{ character_id }progression loaded/warmed for a character
forge-progression:server:leveledUp{ character_id, level }a level threshold was crossed

​
Configuration

XpCurve = { Base = 100, Factor = 1.5, MaxLevel = 50 },
PointsPerLevel = 1,
forge-progression ships no content (the curve and points are tunables, not data). Unlocks and the things they gate are defined by the systems that use them.