progression-economy

name: progression-economy description: >- Systems architecture blueprint for game progression and economy: stat curves, XP families, skill trees, soft caps, stat aggregation, wallets, faucets/sinks, energy gates, battle passes, seasons, server-authoritative transactions, idempotency, and int64 currencies. Use when designing leveling, XP curves, talents, prestige, currencies, economy balance, stamina, reward grants, or when balances drift, grants duplicate, inflation appears, or curve edits break saves.

Progression & Economy

Build the progression/economy layer — systems architecture plus the live-ops economy discipline (not monetization ethics or gacha-pull psychology, which live in loot-drop-system). Primary references: Genshin Impact (datamined configs + the Grasscutter server reimplementation as architectural evidence), EVE Online and WoW (the virtual-economy management craft), plus the broad RPG/MMO/idle canon for curve and skill-tree patterns. Counterpoint: BotW (the no-server, materials-as-progression model with a datamined hidden world level).

The architecture rule

Progression is tables, the wallet is a ledger, and the server (or the save) is the only authority.

PROGRESSION   stat(level) = base × curve[level]; curves are SHARED data;
              breakpoints/ascension as table rows; multi-track, cross-gated;
              the written aggregation contract
WALLET        typed currencies + a one-way conversion graph; a ledger, not a
              number; faucets vs sinks balanced to control money supply
ENERGY        a currency with temporal auto-grant; lazy recompute from server
              time, never a tick loop
TRANSACTIONS  client requests intent → server validates → commits spend+grant
              ATOMICALLY → notifies; idempotency keys; int64 minor units

Reference map

What the datamines prove

• The curve-table pattern is real shipped code: Grasscutter loads AvatarExcelConfigData (base stats + curve references) and computes base × curveInfos[curveId][level] exactly. Curves are immutable post-release (balance ships as new content, never as retroactive edits).
• Server-authoritative is total: the leaked official server generates artifacts server-side; every handler follows validate→mutate→notify; the resin protocol sends nextAddTimestamp (timestamp regen, proven).
• BotW's counterpoint: no XP — orbs/seeds/materials as progression, plus a datamined hidden world level (kill counters → points via LevelSensor.byml). Only raw counters are saved; derived values recalculate — minimize persisted derivable state.

Build order (4 shippable tiers)

Tier 1 — Tables and the contract
- [ ] Curve + breakpoint tables as data; explicit per-level value tables
- [ ] The stat aggregation contract WRITTEN + unit tests of record
- [ ] Multi-track state model with cross-gates as data
- [ ] int64 currencies in minor units; wallet = balance + append-only journal
Tier 2 — Transactions and the economy
- [ ] Atomic spend+grant (one transaction; solo: one save write)
- [ ] Idempotency keys (client-generated before first attempt, reused on retry)
- [ ] Server-side validation against the tables (client sends intents only)
- [ ] Faucet/sink map drawn; caps + overflow (mailbox with expiry)
Tier 3 — Energy and seasons
- [ ] Energy as timestamp-regen currency (server UTC clock, lazy recompute)
- [ ] Battle pass: season defs, reward tables, typed missions, weekly caps,
      retroactive entitlement, idempotent + replayable rollover
Tier 4 — Live operations
- [ ] Data/code version handshake at login (table hash)
- [ ] Receipt validation server-side; boot-time entitlement reconciliation
- [ ] Economy telemetry (progression rates, material stocks, faucet/sink flow)
      + pre-launch flow simulation
- [ ] Anti-cheat: rate limits + anomaly detection over the journal

Key numbers (starting points — sourced anchors)

Full sourced tables (with flagged "do-not-invent" gaps) in each reference file.

Engine mapping (summary)

Full detail in transactions.md and the reference files.