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

# Mobs & Factions

> Spawn and inspect registered mobs from code, drive factions and threat, and ship bundled mob definitions.

`LodeEntitiesAPI.mobs()` is the registry of every mob LodeEntities knows about, plus the operations that act on live ones.

## Lookup and spawning

```java theme={null}
Entity boss = LodeEntitiesAPI.mobs().spawn("sir_toast", location);   // full spawn pipeline
String id    = LodeEntitiesAPI.mobs().mobId(someEntity);              // null if not a LodeEntities mob
boolean ours = LodeEntitiesAPI.mobs().isMob(someEntity);
LodeEntitiesAPI.mobs().fireTrigger(boss, "cast", player);             // fire any trigger by name

MobDefinition def = LodeEntitiesAPI.mobs().get("sir_toast");
Set<String> all = LodeEntitiesAPI.mobs().ids();
Collection<MobDefinition> defs = LodeEntitiesAPI.mobs().all();
```

`spawn` runs the same pipeline as `/le spawn`: model, stats and `+onSpawn` effects. `fireTrigger` accepts built-in trigger names and [any trigger your addon registered](https://entities.lodemc.net/extending-effects.md#custom-triggers).

### Finding a mob that vanished

```java theme={null}
Map<String, String> broken = LodeEntitiesAPI.mobs().disabled(); // id -> reason
```

`disabled()` returns the mobs that are configured but **not** registered, usually because their model was deleted or renamed. They are deliberately absent from `ids()`, `all()` and `get()` so a broken mob never reaches a menu or a spawn. This is how you find out why one disappeared.

## Factions and threat

Every mob may belong to a faction. Relations live in `factions.yml`, and allies never target each other or generate threat. Threat tables are per-mob, fed by damage, and decide retargeting. See [Factions & Threat](https://entities.lodemc.net/factions-threat.md) for the config side.

```java theme={null}
String side = LodeEntitiesAPI.mobs().factionOf(entity);   // "players" for players, null = no side
LodeEntitiesAPI.mobs().setFaction(entity, "undead");      // override for this entity's lifetime
LodeEntitiesAPI.mobs().clearFaction(entity);              // back to its configured side

boolean friendly = LodeEntitiesAPI.mobs().areAllies(mob, other);
FactionRelation rel = LodeEntitiesAPI.mobs().relationBetween(mob, other); // ALLY / NEUTRAL / ENEMY

LodeEntitiesAPI.mobs().addThreat(mob, player, 25.0);      // allies never generate threat
double held = LodeEntitiesAPI.mobs().threatOf(mob, player);
Map<Entity, Double> table = LodeEntitiesAPI.mobs().threatTable(mob); // most threatening first
LodeEntitiesAPI.mobs().clearThreat(mob);                  // forget the fight entirely
```

> [!NOTE]
>
> Relations are **one-way**. `relationBetween(a, b)` need not equal `relationBetween(b, a)`.

`threatTable` returns a `Map` rather than a list of pairs on purpose: Kotlin's `Pair` is relocated inside the shaded jar, so an addon could not name the type.

## Shipping bundled mobs

An addon can ship mob definitions from code. They merge into the registry and are **not** wiped when configs reload. From Kotlin, name only the fields you need:

```kotlin theme={null}
LodeEntitiesAPI.mobs().contribute(mapOf(
    "flame_knight" to MobDefinition(
        id = "flame_knight",
        model = "flame_knight_model",   // null for a vanilla, model-less mob
        base = EntityType.ZOMBIE,
        display = "&cFlame Knight",
        health = 80.0,
        damage = 10.0,
        persistent = true,
        faction = "undead",
    )))
```

`MobDefinition` fields, in order: `id`, `model`, `base`, `display`, `health`, `damage`, `armor`, `speed`, `scale`, `glowing`, `gravity`, `invulnerable`, `persistent`, `nameVisible`, `ai`, `silent`, `collidable`, `invisible`, `child`, `canPickUpItems`, `knockbackResistance`, `followRange`, `attackKnockback`, `faction`, `equipment`, `aging`, `type` (`MobType.MOB` or `MobType.NPC`), `dialog`, `look`, `effects`, `animationSpeed`, `egg`. Everything after `base` is optional, and `model` may be `null` too: a mob with no model is the plain `base` entity with your stats and effects on it. [Mob Stats](https://entities.lodemc.net/mob-fields.md) documents what each one means and the range it accepts.

> [!WARNING]
>
> Unlike [`SpawnRule`](addon-natural-spawns#constructor-shapes), `MobDefinition` is **not** `@JvmOverloads`. From Java you must pass every argument in order, `null` (or the empty default) for the ones you don't want, and the list grows as fields are added, so a Java addon has to be recompiled against each version. Kotlin's named arguments are the comfortable way to do this.

`equipment` is a `MobEquipment(Map<EquipmentSlot, ItemStack> pieces, Map<EquipmentSlot, Float> dropChances)` — drop chance defaults to `0`, not vanilla's \~8.5%, so a contributed boss doesn't seed the floor with free gear. `aging` is a `MobAging(String growsInto, long after)`: the id of the next stage and how many ticks alive before it grows.

A server owner can still override any contributed mob by defining the same id in a `Mobs/` file — your addon supplies sensible defaults, the owner has the last word.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.