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

# Levels

> Where a mob's level comes from, and what reads it.

Every mob NMEntities spawns carries a **level**. It defaults to `1` and is recorded on the entity, so it survives restarts and unloaded chunks.

<Warning>
  Levels are recorded and readable, but **nothing scales stats by them yet**. Per-level health and damage formulas are their own feature. Configs written against levels keep working, and an addon can do its own scaling from the value today.
</Warning>

## Where a level comes from

| Source                                | How                                                                 |
| :------------------------------------ | :------------------------------------------------------------------ |
| [Spawners](spawners)                  | `spawn.level` (also `level`, `moblevel`) on the spawner.            |
| [Natural spawn rules](natural-spawns) | `level` on the rule.                                                |
| Anything else                         | `1` — `/nme spawn`, the menu, eggs, the `summon` mechanic, the API. |

## Scaling by distance

A spawner with `world-scaling: true` sets the level from how far out it is instead of a fixed number — the further from world spawn, the higher the level.

```yaml theme={null}
  spawn:
    world-scaling: true
```

Tuned server-wide in `config.yml`:

```yaml theme={null}
spawner:
  world-scaling:
    blocks-per-level: 250   # blocks from world spawn worth one extra level
    max-level: 20           # ceiling, however far out the spawner is
```

A spawner 1,400 blocks out with the defaults spawns level 6 mobs.

## Reading a level

In any effect text — messages, titles, `setname`, `command`:

```yaml theme={null}
- actionbar{message=&7Level <caster.level> <caster.name>} +onSpawn @playersRadius[16]
- message{m=&cYou were killed by a level <caster.level>!} +onAttack @target
```

| Placeholder      | Resolves to                                   |
| :--------------- | :-------------------------------------------- |
| `<caster.level>` | the mob's own level                           |
| `<target.level>` | the level of the entity the line is acting on |

Both read `1` for anything that was not spawned with a level.

From code, `NMEntitiesAPI.spawners().levelOf(entity)` returns the same value — see [Spawners](addon-spawners#levels) in the API section.