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

Soul Echoes drop in-match as a LAPIS_LAZULI carrier item labelled Soul Echo. They stack in the player's inventory during the run and are flushed into the persistent balance at match teardown.

Source	Amount
Any regular (non-boss) mob kill	1, on a 1% per-kill roll
Portal scorpion -- Normal	10-15, guaranteed
Portal scorpion -- Elite	15-24, guaranteed
Portal scorpion -- Nightmare	25-35, guaranteed
Final boss (Challenge mode)	round(100 * 1.5^tributes) -- 100 with no tributes, 150 / 225 / ~338 with 1 / 2 / 3 Boss Tributes
Soul Shard Cache POI	50, banked immediately into the persistent balance (bypasses the match-end flush)

Ghost-army mobs are reward-disabled and drop nothing.

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 any reward screen -- level-up, chest, or hourglass. The screen stashes its own pool type before offering the buttons, so a reroll on a chest screen re-draws passives and a reroll on an hourglass screen re-draws the full pool.

• 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, including the empty-pool fallback. 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.

Remaining counts appear on the reward screen's header line (Pick your reward! | X bans X rerolls). Ban is a per-slot button -- one "Ban <name>" control under each of the three options -- while Reroll is a single screen-level button. Each control is hidden entirely once its token count hits zero, and with no tokens at all the header falls back to a plain "Pick your reward!".

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.