MegaBlock Survivors Meta-Progression

MegaBlock Survivors has a between-runs progression layer called Soul Echoes. Soul Echoes are collected during matches and spent at the Soul Echo Shrine to permanently improve the player's starting loadout across all future runs.

Persistent state lives in plugins/MegaBlockSurvivors/meta_progression.yml, keyed by player UUID. Saves are synchronous, so on-disk state always reflects the latest change when the call returns.

Earning Soul Echoes

The primary in-match source is the Soul Shard Cache POI reward. Each cache adds Soul Echoes directly to the player's meta-progression balance and shows a feedback line in chat. Any unflushed in-run balance is also added at match teardown.

Opening the Shrine

/mbs meta

Opens the Soul Echo Shrine dialog. The dialog shows:

• Current Soul Echo balance.
• Every upgrade track's current level, cap, current effective stat, next-level preview, and next-level cost.
• A purchase button per track (or a MAXED indicator).

/mbs meta upgrade <track>

Buys a single level on the named track and re-opens the dialog so multiple upgrades can be purchased back to back.

Upgrade Tracks

Track	Command key	Cap	Effect
Starting HP	hp	4	Lvl 0 = 10 HP (baseline), +2 HP per level. Maxed: 18 HP.
Starting Luck	luck	4	Lvl 0 = 0 luck, +2 luck per level. Maxed: 8.
Starting Speed	speed	4	Walk speed multiplier on BASE_WALK_SPEED. Lvl 0 = 1.00x, +0.05 per level. Maxed: 1.20x.
Weapon Slots	weaponslots	1	Lvl 0 = 1 slot, Lvl 1 = 2 slots.
Passive Slots	passiveslots	3	Lvl 0 = 2 slots, +1 per level. Maxed: 5 slots.
Extra Lives	extralives	2	Banked Second Wind revives. Lvl 1 = 1 life, Lvl 2 = 2 lives.
Ban Tokens	bantokens	3	Per-run tokens that permanently remove a reward option from the pool for the rest of the run.
Reroll Tokens	rerolltokens	3	Per-run tokens that re-draw the current reward trio.

Cost Curve

Most tracks use the default geometric curve:

cost(targetLevel) = round(10 * 2.5^(targetLevel - 1))

Target Level	Cost (Soul Echoes)
1	10
2	25
3	63
4	156

Extra Lives is hand-tuned and uses a fixed schedule instead: 100 for the first life, 200 for the second.

Ban / Reroll Mechanics

The Ban and Reroll tracks grant per-run tokens that the player can spend from the level-up reward screen:

• Ban -- consumes one ban token and adds the chosen equipment type to a run-long "banned" set. The pool builder filters banned types from every future reward draw in that run. Useful for removing a passive you have no interest in upgrading so its slot keeps offering something else.
• Reroll -- consumes one reroll token and re-draws the current trio of rewards from the (post-bans) pool. No permanent pool change.

Both buttons appear on the reward screen's header line alongside the remaining token counts (X bans X rerolls). If neither track is unlocked, a simpler "Pick your reward!" header is shown instead.

Token balances reset to the meta-progression-track-determined value at the start of every match -- they don't carry over.

Storage Format

meta_progression.yml layout:

players:
  <player-uuid>:
    soulEchoes: 0
    tracks:
      startingHp: 0
      startingLuck: 0
      startingSpeed: 0
      weaponSlots: 0
      passiveSlots: 0
      extraLives: 0
      banTokens: 0
      rerollTokens: 0

The cache is concurrent and is flushed to disk every time MetaProgressionManager.save() runs (on purchase, on match-end echo flush, and on plugin disable).

Resetting Progress

There is no in-game command to wipe meta-progression. To reset for a player (or for everyone), stop the server and edit / delete the relevant section in meta_progression.yml.