Extractioncraft Developer API

Extractioncraft exposes a query class and Bukkit events under com.magmaguy.extractioncraft.api so other plugins can track and react to matches. All events are standard synchronous Bukkit events.

Queries

Method	Returns
ExtractionCraftAPI.getMatch(Player player)	The ExtractionMatch the player is in, as a player or spectator, or null
ExtractionCraftAPI.getMatches()	A copy of every match that has been created and not yet destroyed

ExtractionMatch extends the match class of the MagmaCore copy bundled in the Extractioncraft jar, relocated to com.magmaguy.extractioncraft.magmacore.match.Match. Its public methods include getPhase(), getMatchPlayers(), getActivePlayers(), admit(players), admitSpectator(player), leave(player, reason), start() and end(outcome). Extractioncraft has no join or spectate command, so admit and admitSpectator are how another plugin brings more players or spectators into a match. Players can only be admitted while the match is waiting, up to its maxPlayers; spectators need the content package to set spectatable: true.

Events

Event	Cancellable	Exposed data	Fires
ExtractionMatchJoinEvent	Yes	ExtractionMatch match, Player player	Before a player or spectator is admitted, once per player
ExtractionMatchStartEvent	Yes	ExtractionMatch match	When /exc start passes the minimum-player check, before the countdown
ExtractionMatchLeaveEvent	No	ExtractionMatch match, Player player, ExtractionLeaveReason reason	While a participant is leaving
ExtractionMatchEndEvent	No	ExtractionMatch match, ExtractionMatchOutcome outcome	When the match ends

Cancelling ExtractionMatchJoinEvent keeps out the player and every player being admitted with them. When it refuses the creator of a freshly generated match, the match and its world are destroyed and the creator is told The generated match could not be started.

Cancelling ExtractionMatchStartEvent keeps the match waiting. Players can run /exc start again.

ExtractionMatchLeaveEvent fires after Extractioncraft has soulbound or cleared the player's inventory for the leave reason, while the player is still a participant and still in the match world. They are teleported out afterwards.

ExtractionMatchEndEvent fires before the players still inside are removed. They then leave with MATCH_ENDED. A server shutdown or plugin reload destroys matches without ending them, so no end event fires; players leave with SHUTDOWN instead.

Leave Reasons

ExtractionLeaveReason	Meaning	Items once the match is live
QUIT	Left on their own, for example with /exc quit	Lost with the default config
DISCONNECT	Disconnected from the server	Lost with the default config
DIED	Took lethal damage	Lost with the default config
EXTRACTED	Extracted at an extraction point	Kept and soulbound
MATCH_ENDED	Still inside when the match ended, including when the timer ran out	Lost with the default config
SHUTDOWN	The server or plugin shut down during the match	Kept and soulbound

Leaving before the match goes live never touches the inventory. See death and item loss.

Match Outcomes

ExtractionMatchOutcome	When Extractioncraft uses it
DEFEAT	The 15-minute timer ran out, or the last active player left the match, including by extracting
NEUTRAL	The player count dropped below minPlayers during the countdown
VICTORY	Never set by Extractioncraft itself; only a plugin calling end(...) can produce it

Usage Example

import com.magmaguy.extractioncraft.api.ExtractionLeaveReason;
import com.magmaguy.extractioncraft.api.ExtractionMatchLeaveEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyExtractionListener implements Listener {
    @EventHandler
    public void onLeave(ExtractionMatchLeaveEvent event) {
        if (event.getReason() == ExtractionLeaveReason.EXTRACTED) {
            // Reward the player for a successful extraction
        }
    }
}