> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmentities.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.

NMEntities 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/NMEntities/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.
* **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} @target                  # shed threat
- threat{set=0} @target                        # wipe one entity's threat
- threatclear #onDeath @self                   # forget the fight entirely (phase change)
- setfaction{faction=undead} @target           # defect one entity, for as long as it lives
```

See the [Combat & Summons mechanics](mechanics-combat) for the full attribute reference.

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