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

# Spawners

> A spot in a world that keeps a population of one mob alive around itself.

A spawner is a point in a world that keeps a population of one mob alive around itself. It wakes when a player comes near, spawns up to a cap, refills what dies, and can pull back anything that wanders too far.

Spawners live in `Mobs/`, beside the mobs they spawn — not in a folder of their own.

## Two ways to declare one

**Nested under the mob**, when the spawner belongs to that mob:

```yaml theme={null}
zombie_knight:
  base: zombie
  health: 40
  spawners:
    crypt_door:
      at: world, 128, 40, -310
      spawn: { amount: 2, max: 6 }
      timer: { every: 30s }
```

**In a top-level `spawners:` block**, whose sections are groups and can nest as deep as you like:

```yaml theme={null}
spawners:
  crypt:
    defaults:
      activation: { range: 32 }
      timer: { every: 20s }
    entrance:
      mob: zombie_knight
      at: world, 128, 40, -310
    throne:
      mob: lich
      at: world, 140, 32, -350
      spawn: { max: 1 }
      timer: false
```

The **id is the path it sits at** (`crypt.entrance`), and the **group is the section it is in** — so ids are unique for free and `/nme spawner disable crypt` means something. `defaults:` is inherited by everything below it, and a spawner that names a setting itself always wins.

<Note>
  `spawners` is a reserved top-level key in `Mobs/` files. A mob cannot be called `spawners`.
</Note>

## Position

Every spawner needs one. Write it however you like — all of these are the same spot:

```yaml theme={null}
  at: world, 128, 40, -310      # one string, commas or spaces
  at: { world: world, x: 128, y: 40, z: -310 }
  world: world                  # ...or as four plain keys,
  x: 128                        #    which is also how MythicMobs spells it
  y: 40
  z: -310
```

`location:` and `pos:` are accepted as synonyms for `at:`.

| Key        | Also                 | Default | What it does                                    |
| :--------- | :------------------- | :------ | :---------------------------------------------- |
| `radius`   | `radiusxz`, `spread` | `0`     | Horizontal scatter around the point, up to 256. |
| `radius-y` | `radiusy`            | `0`     | Vertical scatter, up to 256.                    |

## Settings

Every key is read case-insensitively with `-` and `_` interchangeable, so a MythicMobs spawner loads as-is — the MythicMobs name is listed under "also".

### `spawn:`

| Key               | Also              | Default | What it does                                                      |
| :---------------- | :---------------- | :------ | :---------------------------------------------------------------- |
| `amount`          | `mobsperspawn`    | `1`     | Mobs per cycle, 1–64.                                             |
| `max`             | `maxmobs`         | `1`     | Population cap, 1–1000.                                           |
| `level`           | `moblevel`        | `1`     | The [level](mob-levels) mobs are tagged with.                     |
| `chance`          | —                 | `1.0`   | Probability a due cycle actually fires, 0–1.                      |
| `random-rotation` | `randomrotation`  | `false` | Spawn facing a random direction.                                  |
| `world-scaling`   | `useworldscaling` | `false` | Derive the level from distance to world spawn instead of `level`. |

### `timer:`

| Key       | Also       | Default | What it does                                                        |
| :-------- | :--------- | :------ | :------------------------------------------------------------------ |
| `enabled` | `usetimer` | `true`  | `timer: false` is the short way to say "only fires when triggered". |
| `every`   | `cooldown` | `10s`   | Time between cycles.                                                |
| `warmup`  | —          | `0`     | Delay after waking before the first cycle.                          |

Durations here take a **bare number as seconds** (`every: 30` is 30 seconds), matching MythicMobs, and also accept `30s`, `2m`, `400t`.

### `activation:`

| Key       | Also                                   | Default | What it does                                          |
| :-------- | :------------------------------------- | :------ | :---------------------------------------------------- |
| `players` | `check-for-players`, `checkforplayers` | `true`  | Whether a player has to be near for it to run at all. |
| `range`   | `activationrange`                      | `40`    | How near.                                             |

Going back to sleep **re-arms the warmup**, so returning to a dungeon makes you wait again.

### `leash:`

| Key            | Also                 | Default   | What it does                                                          |
| :------------- | :------------------- | :-------- | :-------------------------------------------------------------------- |
| `range`        | `leashrange`         | `0` (off) | Blocks a mob may stray before it is teleported home.                  |
| `heal`         | `healonleash`        | `false`   | Heal it fully when it returns.                                        |
| `reset-threat` | `resetthreatonleash` | `false`   | Make it forget its target — see [Factions & Threat](factions-threat). |

`leash: 32` is shorthand for `leash: { range: 32 }`.

### Top-level

| Key          | Default                    | What it does                                                       |
| :----------- | :------------------------- | :----------------------------------------------------------------- |
| `mob`        | the mob it is nested under | Which mob to spawn. Required for a spawner in a `spawners:` block. |
| `group`      | the section it sits in     | Override the group name.                                           |
| `enabled`    | `true`                     | Whether it starts switched on.                                     |
| `breakable`  | `false`                    | Mining its block switches it off.                                  |
| `flames`     | `false`                    | Show the vanilla spawner flame particles.                          |
| `conditions` | none                       | See below.                                                         |

## Conditions

A list of place-shaped tests, **all** of which must pass before a cycle spawns anything:

```yaml theme={null}
  conditions:
  - night
  - light <= 7
  - biome == desert, badlands
  - y > 40
  - !raining
```

A line is `key`, `!key`, or `key <op> value` with `==` `!=` `>=` `<=` `>` `<` (spaces optional, `=` accepted for `==`). String comparisons are case-insensitive, ignore a `minecraft:` namespace, and take a comma list meaning "any of these".

| Flags                            | Numbers                                           | Names                             |
| :------------------------------- | :------------------------------------------------ | :-------------------------------- |
| `day`, `night`                   | `y` / `height`, `light`, `blocklight`, `skylight` | `biome`                           |
| `raining`, `thundering`, `clear` | `time`, `moonphase`, `random` / `chance`          | `world`                           |
| `spawnable`, `ground`            | `players`, `mobs`, `distancefromspawn`            | `block`, `blockbelow` / `onblock` |

<Warning>
  A condition that fails to parse **disables its spawner** rather than being skipped. A gate that silently disappears spawns mobs exactly where you said not to. [`/nme debug`](debug) names the line and the reason.
</Warning>

## Behaviour worth knowing

* **At the cap the timer simply waits.** No cooldown is burned, so the spawner refills promptly once something dies rather than idling for another full cycle.
* **A restart does not double the population.** On its first cycle after load a spawner finds the mobs it made last time and counts them, so a restarted dungeon is not filled a second time.
* **Runtime state is not config.** Cooldowns, warmups and live counts live in memory; only "an admin switched this off" persists, in `spawner-state.yml`.

## Server-wide switches

```yaml theme={null}
spawner:
  enabled: true        # turn every spawner off at once
  check-interval: 20   # ticks between passes; 20 = once a second
  world-scaling:
    blocks-per-level: 250
    max-level: 20
```

## Driving them

From commands: [`/nme spawner`](spawner-commands) — list, info, create, remove, enable, disable, reset, trigger, tp.

From an effect, which is what makes a spawner part of an encounter rather than scenery:

```yaml theme={null}
- spawner{id=crypt.throne;action=trigger} +onDeath @self
```

From code: [`NMEntitiesAPI.spawners()`](addon-spawners).

## Coming from MythicMobs

Drop a MythicMobs spawner file into `Mobs/` and it converts on load, field by field. Every MythicMobs spawner field is supported: `MobsPerSpawn`, `MaxMobs`, `MobLevel`, `Chance`, `RandomRotation`, `UseWorldScaling`, `UseTimer`, `Cooldown`, `Warmup`, `CheckForPlayers`, `ActivationRange`, `LeashRange`, `HealOnLeash`, `ResetThreatOnLeash`, `Radius`, `RadiusY`, `ShowFlames`, `Breakable` and `Conditions`.

`CooldownTimer`, `WarmupTimer` and `ActiveMobs` are deliberately **not** config here — they are runtime state.