BTCMobs API Reference

The BTCMobs API provides a robust, thread-safe interface for extending the custom mob engine. It is designed for high performance on both Paper and Folia.

Getting the API

// Retrieve the API service provider
val api = Bukkit.getServicesManager().load(BTCMobsApi::class.java)
    ?: throw IllegalStateException("BTCMobs not found")

Available Sub-systems

The BTCMobsApi interface exposes several specialized managers:

• mobManager: Management of active mobs and mob types.
• skillManager: Registration of custom mechanics, targeters, and conditions.
• damageTracker: Access to real-time boss damage statistics.
• aiGoalRegistry: Custom AI pathfinding and target selectors.

---

🐲 Mob Management

Accessing Active Mobs

// Get all currently spawned BTCMobs
val allMobs: Collection<ActiveMob> = api.mobManager.getActiveMobs()

// Find a specific mob by UUID
val mob: Optional<ActiveMob> = api.mobManager.getActiveMob(uuid)

// Check if an entity is managed by BTCMobs
if (api.mobManager.isActiveMob(entity.uniqueId)) {
    val btcMob = api.mobManager.getActiveMob(entity.uniqueId).get()
    println("Mob Type: ${btcMob.mobType.internalName}")
}

Spawning Mobs

val mythicMob = api.mobManager.getMythicMob("ElderGuardian").get()
val activeMob = api.mobManager.spawnMob(mythicMob, location)

---

⚡ Skill System Extension

BTCMobs allows you to register your own components that can be used directly in .yml skill files.

Custom Mechanics

api.skillManager.registerMechanic("mylauncher") { metadata, config ->
    val power = config.getDouble("power", 1.0)
    metadata.caster.velocity = metadata.caster.velocity.multiply(power)
}

Custom Targeters

api.skillManager.registerTargeter("nearestAlly") { metadata, config ->
    val radius = config.getDouble("radius", 5.0)
    // Return a list of SkillTarget (Entity or Location)
    api.mobManager.getActiveMobs()
        .filter { it.location.distance(metadata.caster.location) < radius }
        .map { it.entity.asSkillTarget() }
}

Custom Conditions

api.skillManager.registerCondition("isBoss") { metadata, config ->
    metadata.caster.health > 1000.0
}

---

🩸 Damage Tracking

Ideal for World Bosses and reward systems.

val info = api.damageTracker.getTrackedDamage(bossUuid)
info?.let {
    println("Total Damage: ${it.totalDamage}")
    it.topContributors(3).forEach { contrib ->
        println("${contrib.playerName}: ${contrib.totalDamage} (${contrib.percentage}%)")
    }
}

---

📡 Event System

BTCMobs integrates with the Bukkit event system:

Event	Description
BtcMobSpawnEvent	Triggered after a mob is fully initialized.
BtcMobDeathEvent	Triggered when a mob is killed (contains loot info).
BtcMobDamageEvent	Cancellable event for custom damage logic.
SkillExecuteEvent	Triggered before a skill starts its execution sequence.

---

For more information on the internal implementation, check the Core Docs.