nota

Release soon — BTCMobs is still in active development. The API described here is stable but the plugin is not yet publicly released. Package coordinates and versions may still evolve before 1.0.

BTCMobs API Reference

The BTCMobs API is a thread-safe, Folia-native interface for extending the mob engine. All API types live under com.borntocraft.btcmobs.api (module btcMobs-api).

aviso

The API package was renamed from renaud.btc.api to com.borntocraft.btcmobs.api, and the engine types formerly prefixed Mythic* are now Btc* (e.g. MythicPlugin → BtcPlugin, MythicMob → BtcMob). Only the MythicMobs compatibility/import types keep the Mythic prefix. Update any integration that referenced the old package.

Accessing the API

Core managers are registered as Bukkit services:

import com.borntocraft.btcmobs.api.mobs.MobManager;
import com.borntocraft.btcmobs.api.core.mobs.ActiveMob;

MobManager mobs = Bukkit.getServicesManager().load(MobManager.class);

// Is this entity a BTCMob?
Optional<ActiveMob> active = mobs.getActiveMob(entity.getUniqueId());
active.ifPresent(mob -> {
    String typeId  = mob.getBtcMob().getInternalName(); // resolved via getBtcMob(name) too
    double level   = mob.getLevel();
    LivingEntity e = mob.getEntity();
});

MobManager

Method	Description
getActiveMob(UUID)	The ActiveMob backing an entity, if managed by BTCMobs.
getBtcMob(String name)	A registered mob type by name.
getMobTypes() / getMobNames()	All registered mob types.
getActiveMobs() / getActiveMobsInCombat()	Live mob instances.
spawnMob(BtcMob, Location)	Spawns a mob type at a location.

ActiveMob

getEntity(): LivingEntity · getBtcMob() (type) · getLevel() · getUniqueId() · getThreatTable()

---

Skill System Extension

SkillManager (the BtcSkillManager) lets you register components usable directly in .yml skill scripts:

// Mechanic
skillManager.registerMechanic("mylauncher", (context, params) -> {
    double power = Double.parseDouble(params.getOrDefault("power", "1.0"));
    context.getMetadata().getCaster().setVelocity(
        context.getMetadata().getCaster().getVelocity().multiply(power));
});

// Condition
skillManager.registerCondition("isboss", (context, params) ->
    context.getMetadata().getCaster().getHealth() > 1000.0);

// Targeter
skillManager.registerTargeter("nearestally", (metadata, params) -> myTargets);

The engine ships with 367 mechanics, 146 conditions, and 85 targeters already wired — see the Mechanics, Conditions and Targeters references.

---

Events

All lifecycle events live in com.borntocraft.btcmobs.api.events and extend BtcMobEvent(activeMob).

Event	Key data	Cancellable
BtcMobSpawnEvent	activeMob, spawnReason, announcement	✅
BtcMobDeathEvent	activeMob, killer, drops, droppedExperience, deathMessage	—
BtcMobDamageEvent	activeMob, damager, damage (mutable), cause, feedbackMessage	✅
BtcMobDespawnEvent	activeMob, reason	—
BtcMobSkillEvent	activeMob, skill, metadata, trigger	✅
BossDamageCompletedEvent	boss id, per-player damage map, max health	—

BtcMobDamageEvent is fired on every hit a BTCMob takes (after configured damage modifiers) — ideal for damage-number plugins (BetterDamage) and HUDs.

@EventHandler
public void onBtcDamage(BtcMobDamageEvent e) {
    if (e.getDamage() > 100) e.setFeedbackMessage(Component.text("CRIT!"));
}

---

Diagnostics — /btc audit

Run /btc audit in-game to dump the live registry: registered mechanics, conditions, targeters, scripted skills, plus mob-type and active-mob counts. Useful for verifying that a pack loaded everything and for parity checks.

---

Integrations

Native/soft hooks: BetterModel / ModelEngine, PacketEvents, PlaceholderAPI, BetterDamage, WorldGuard, GriefPrevention, McMMO, Vault, Typewriter, MMOCore. See Integrations and the third-party integration guide shipped with the plugin.

---

For the full external-plugin integration guide (used by the kr.toxicity display cluster), see the BTCMOBS_API_INTEGRATION shipped in the plugin docs.