MegaBlock Survivors Developer API
MegaBlock Survivors exposes a query class and Bukkit events under com.magmaguy.megaBlockSurvivors.api so other plugins can track and react to runs. All events are standard synchronous Bukkit events. Add MegaBlockSurvivors to your plugin's depend or softdepend list.
Queries
| Method | Returns |
|---|---|
MegaBlockSurvivorsAPI.getMatch(Player player) | The SurvivorMatchInstance the player is playing or still setting up, or null |
MegaBlockSurvivorsAPI.getMatches() | A copy of every run on the server, including runs still being set up |
SurvivorMatchInstance extends the match class of the MagmaCore copy bundled in the MegaBlock Survivors jar, relocated to com.magmaguy.megablocksurvivors.magmacore.match.Match. Its own getters include getSurvivorPlayer(), getGameMode(), getDifficulty(), getCurrentWorld() and isCheating(). The player picks the game mode and difficulty during setup, so a run still in setup reports the defaults, CHALLENGE and MEDIUM, until they choose.
Events
| Event | Cancellable | Exposed data | Fires |
|---|---|---|---|
SurvivorMatchJoinEvent | Yes | SurvivorMatchInstance match, Player player | After the player picks a starting weapon, before they are admitted to the run |
SurvivorMatchStartEvent | Yes | SurvivorMatchInstance match | Right after the player is admitted, before the 3-second countdown |
SurvivorMatchLeaveEvent | No | SurvivorMatchInstance match, Player player, SurvivorLeaveReason reason | While an admitted player is leaving the run |
SurvivorMatchEndEvent | No | SurvivorMatchInstance match, SurvivorMatchOutcome outcome | Once per run, after its worlds are unloaded for deletion |
Cancelling SurvivorMatchJoinEvent cancels the run and deletes its world. The player gets the match.prepare_failed message.
Cancelling SurvivorMatchStartEvent also cancels the run, without a message.
SurvivorMatchLeaveEvent fires while the player is still a participant, before they are moved out and before the Soul Echo flush and inventory clear. A player who cancels during setup was never admitted, so no leave event fires for them.
SurvivorMatchEndEvent fires for every run, including runs cancelled during setup, runs ended with /mbs quit, and runs ended by /mbs reload or a plugin disable.
Leave Reasons
SurvivorLeaveReason | Meaning |
|---|---|
QUIT | Left before the run started, for example because the entry teleport failed |
DISCONNECT | Disconnected from the server. The run then ends as a defeat |
DIED | Used by the shared match core's own lethal-damage handling. MegaBlock Survivors cancels vanilla damage during a run and handles deaths itself, so a death in a run reports MATCH_ENDED |
MATCH_ENDED | The run ended: victory, defeat, /mbs quit, /mbs reload, or a plugin disable |
SHUTDOWN | Declared for shutdowns. A normal plugin disable or /mbs reload ends runs through MegaBlock Survivors first, so players leave with MATCH_ENDED |
Outcomes
SurvivorMatchOutcome | Meaning |
|---|---|
VICTORY | A Challenge run beat the final boss and reached the end of the 10-second victory delay |
DEFEAT | The player died with no extra lives left, or disconnected. A disconnect during the victory delay also reports DEFEAT, although the leaderboard entry was already recorded |
ABANDONED | /mbs quit, a setup that was cancelled or timed out, a vetoed join or start, /mbs reload, or a plugin disable |