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

# Factions & Threat

> Give mobs sides and a threat table: factions.yml, threat config, and the taunt mechanics.

Vanilla mobs fight whoever hit them last. That makes real boss fights impossible: no way to hold aggro, no way to pull it, and nothing stopping a mob from turning on its own side over stray splash damage.

LodeEntities mobs keep a **threat table** instead. They remember everyone who has hurt them and fight whoever is most threatening, and you can give any mob a **faction** so it knows friend from foe.

## Factions

Give any mob a side with one field:

```yaml theme={null}
skeleton_archer:
  base: skeleton
  faction: undead

village_guard:
  base: iron_golem
  faction: villagers
```

How the sides get along lives in an optional `plugins/LodeEntities/factions.yml`:

```yaml theme={null}
undead:
  enemy: [villagers, players]
  ally: [skeletons]
villagers:
  enemy: [undead]
```

Three relations:

| Relation | Meaning |
| - | - |
| `ally` | Never targeted, and never generates threat. Friendly fire is ignored completely. |
| *(neutral)* | Fights back if attacked, but won't start anything. The default between two different factions. |
| `enemy` | A valid target without being provoked. |

Two things to know:

* **Relations are one-way as written.** The example above is only mutual because both halves are spelled out, which is deliberate: you can build a hunter that stalks a creature that never hunts back.
* **Pets are always on their owner's side.** A [pet](https://entities.lodemc.net/pets.md) is an ally of its owner and of that owner's other pets, whatever `factions.yml` says.
* **Players are the reserved faction `players`**, so you can write relations against them without tagging anything. A mob with no `faction:` behaves exactly as before.

## Threat

Damage generates threat equal to the damage actually dealt, after armor. Mobs retarget on a timer to whoever tops their table, and threat fades over time so old grudges lapse.

Four knobs in `config.yml`:

```yaml theme={null}
threat:
  enabled: true
  retarget-interval: 20     # ticks between retarget passes
  decay-per-second: 0.02    # 0 = threat never decays
  forget-range: 32          # blocks past which a mob forgets you
```

Because retargeting runs on an interval, a taunt lands within about a second at the default rather than instantly. Lower `retarget-interval` for snappier switching.

## Driving threat from effects

The threat mechanics are what make scripted fights possible: tanks that hold aggro, phase changes that reset the fight, mind-control gimmicks.

```yaml theme={null}
- threat{amount=500} +onInteract @trigger      # a taunt: jump to the top of the table
- threat{amount=-200} @trigger                 # shed threat
- threat{set=0} @trigger                       # wipe one entity's threat
- threatclear +onDeath @self                   # forget the fight entirely (phase change)
- setfaction{faction=undead} @trigger          # defect one entity, for as long as it lives
- taunt{amount=500} +onInteract @trigger       # MythicMobs' taunt: raise threat and turn it on the caster
```

See [Combat & Health](https://entities.lodemc.net/mechanics-health.md) for the full option reference. Targeters can read the table too: `@threatTable`, `@threatTablePlayers`, `@randomThreatTarget`, and `sort=HIGHEST_THREAT` on any area targeter ([Targeters](https://entities.lodemc.net/targeters.md)). The `samefaction` and `faction` [conditions](https://entities.lodemc.net/conditions.md) test sides, and `<target.threat>` prints a value ([Placeholders](https://entities.lodemc.net/placeholders.md)).

Addons get the same through `LodeEntitiesAPI.mobs()`: `factionOf`, `setFaction`, `clearFaction`, `areAllies`, `relationBetween`, `threatOf`, `addThreat`, `threatTable`, `clearThreat`. See [Mobs & Factions](https://entities.lodemc.net/addon-mobs.md).

## What it looks like in practice

A zombie takes hits from three attackers: an ally for 5 damage, a stranger for 12, and another stranger for 2 (most recently). Its threat table ends up with the 12-damage stranger on top and the ally **absent entirely**, so it goes after the biggest threat, not the last hit and never its friend. That's the difference between vanilla chaos and a fight you can design.


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