Developer API

How other plugins integrate with mcMMO - the static API classes, the full set of custom Bukkit events, Maven coordinates, and PlaceholderAPI hooks.

mcMMO exposes a developer API so other plugins can read and modify player skill data, react to mcMMO events, and change behavior at runtime. This page is for plugin developers; server owners looking to wire mcMMO into existing plugins want the Integrations page instead.

Everything here is verified against mcMMO 2.2.054 source. Method signatures and event names change between major versions - always check against the jar you compile against.

Adding mcMMO as a dependency

mcMMO is published to the CodeMC repository. Maven coordinates:

<repository>
    <id>codemc-repo</id>
    <url>https://repo.codemc.io/repository/maven-public/</url>
</repository>

<dependency>
    <groupId>com.gmail.nossr50.mcMMO</groupId>
    <artifactId>mcMMO</artifactId>
    <version>2.2.054</version>
    <scope>provided</scope>
</dependency>

Declare mcMMO in your plugin.yml so it loads first:

depend: [mcMMO]        # hard dependency - your plugin won't load without mcMMO
# or
softdepend: [mcMMO]    # optional - load after mcMMO if it's present

Static API classes

The public API lives in com.gmail.nossr50.api. Each class is a collection of static methods - you don't instantiate them.

Class	Purpose
`ExperienceAPI`	Read and grant XP, query levels and leaderboard ranks (online and offline).
`SkillAPI`	List skill names by category (all, child, combat, gathering, misc).
`PartyAPI`	Read party membership, add/remove members, get and set the leader.
`AbilityAPI`	Check whether a super ability is active and set/reset cooldowns.
`ChatAPI`	Query and toggle a player's party-chat / admin-chat mode.
`DatabaseAPI`	Check whether a player exists in the mcMMO database.

A few representative calls:

import com.gmail.nossr50.api.ExperienceAPI;
import com.gmail.nossr50.api.PartyAPI;
import com.gmail.nossr50.api.AbilityAPI;

// Grant 100 raw XP in Mining (respects multipliers when using addXP variants)
ExperienceAPI.addRawXP(player, "MINING", 100);

// Read a level
int mining = ExperienceAPI.getLevel(player, "MINING");

// Party checks
boolean teamed = PartyAPI.inSameParty(playerA, playerB);
String partyName = PartyAPI.getPartyName(player);

// Super ability state
boolean digging = AbilityAPI.gigaDrillBreakerEnabled(player);

Skill-type strings are case-insensitive skill names ("MINING", "SWORDS", "HERBALISM", …). Passing an invalid name throws - call ExperienceAPI.isValidSkillType(name) first if the value comes from user input.

Some ExperienceAPI methods also take an XP gain reason (XPGainReason) and an XP gain source so your XP grants fire the proper events and respect server settings. There are …Offline variants that accept a player name or UUID for editing players who aren't online.

Events

mcMMO fires custom Bukkit events you can listen to with a normal @EventHandler. Most are cancellable or expose setters so you can change XP amounts, drops, or outcomes before they apply. They live under com.gmail.nossr50.events.

Experience & levels

Event	Fires when
`McMMOPlayerXpGainEvent`	A player is about to gain skill XP (set the amount or cancel).
`McMMOPlayerPreXpGainEvent`	Before XP is calculated.
`McMMOPlayerLevelUpEvent`	A skill levels up.
`McMMOPlayerLevelDownEvent`	A skill loses a level.
`McMMOPlayerLevelChangeEvent`	Any level change (base class).

Skills & abilities

Event	Fires when
`McMMOPlayerAbilityActivateEvent`	A super ability is activated.
`McMMOPlayerAbilityDeactivateEvent`	A super ability ends.
`SubSkillEvent` / `SubSkillRandomCheckEvent` / `SubSkillBlockEvent`	A sub-skill triggers or rolls its chance.
`McMMOPlayerRepairCheckEvent` / `McMMOPlayerSalvageCheckEvent`	A repair or salvage is attempted.
`McMMOPlayerFishingTreasureEvent` / `McMMOPlayerShakeEvent` / `McMMOPlayerMagicHunterEvent`	Fishing results.
`McMMOPlayerTameEntityEvent` / `McMMOPlayerDisarmEvent`	Taming / Unarmed disarm.
`McMMOPlayerBrewEvent` / `McMMOPlayerCatalysisEvent`	Alchemy brewing.
`McMMOEntityDamageByRuptureEvent`	Rupture deals damage.

Parties

Event	Fires when
`McMMOPartyChangeEvent`	A player joins or leaves a party.
`McMMOPartyLevelUpEvent`	A party gains a level.
`McMMOPartyXpGainEvent`	A party gains XP.
`McMMOPartyTeleportEvent`	A party teleport happens.
`McMMOPartyAllianceChangeEvent`	A party alliance changes.

Chat, items, profiles & hardcore

Event	Fires when
`McMMOChatEvent` / `McMMOPartyChatEvent` / `McMMOAdminChatEvent`	mcMMO chat channels.
`McMMOItemSpawnEvent` / `McMMOModifyBlockDropItemEvent`	mcMMO spawns or modifies drops.
`McMMOPlayerProfileLoadEvent`	A player's profile finishes loading.
`McMMOPlayerDeathPenaltyEvent` / `McMMOPlayerStatLossEvent` / `McMMOPlayerVampirismEvent`	Hardcore-mode penalties.
`McMMOScoreboard*Event`	mcMMO scoreboard lifecycle.

@EventHandler
public void onXpGain(McMMOPlayerXpGainEvent event) {
    if (event.getSkill() == PrimarySkillType.MINING) {
        event.setRawXpGained(event.getRawXpGained() * 2); // double mining XP
    }
}

mcMMO also fires fake events (FakeBlockBreakEvent, FakePlayerFishEvent, etc.) to drive vanilla mechanics without side effects. Check event instanceof FakeEvent and ignore them in your listeners, or you'll double-process mcMMO's own actions.

PlaceholderAPI

mcMMO ships a built-in PlaceholderAPI expansion (identifier mcmmo) that registers automatically when PlaceholderAPI is installed. The full list of %mcmmo_…% placeholders is documented on the Integrations page.

Anonymous metrics (bStats)

mcMMO reports anonymous stats to bStats. This is mcMMO's own telemetry, not an API - see Integrations → bStats to opt out.

Developer API

On this page