> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borntocraftstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> BTCMobs Developer API — package com.borntocraft.btcmobs.api

<Note>
  **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.
</Note>

# 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`).

<Warning>
  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.
</Warning>

## Accessing the API

Core managers are registered as Bukkit services:

```java theme={null}
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:

```java theme={null}
// 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](../Skills/Mechanics), [Conditions](../Skills/Conditions) and
[Targeters](../Skills/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.

```java theme={null}
@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](../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.md` shipped in the plugin docs.*