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 and replace the file atomically. A purchase whose save fails rolls back both the cost and the upgrade. Earned Soul Echoes remain in memory after a failed save, but can be lost on restart until a later save succeeds. A failed load preserves the existing in-memory state and blocks saves and purchases until a successful reload. Check the server log for persistence errors.

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. The flush identifies them by material alone, so all lapis lazuli in that inventory is consumed and counted, including ordinary lapis brought into the match. Keep the minigame inventory separate from survival inventories.

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.

Purchases are also allowed during a match. Weapon and passive slot limits read the current progression record and can change during that run. Starting HP, luck, speed, lives, bans, and rerolls are copied when the player is initialized, so buying those tracks does not replenish or change those starting values in an existing run.

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 filter an equipment type from later draws, subject to the exhausted-pool fallback below.
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 later reward draws and its first fallback. If every type in the fallback pool is banned, a final fallback restores the unfiltered pool, so an absolute never-return guarantee does not hold for an exhausted pool. 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, on a Soul Shard Cache pickup, 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.