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

# Config Reference

> Every option in config.yml, grouped, with its default.

`plugins/LodeEntities/config.yml`. Everything here is re-read by `/le reload` unless the option says otherwise.

## Licensing

| Option | Default | What it does |
| :- | :- | :- |
| `network-license.proxy` | `""` | `host:port` of the license relay on your Velocity proxy, so this server is licensed by the proxy instead of taking a slot of its own. Empty means this server checks its own key. See [Licensing](https://entities.lodemc.net/licensing.md#networks-behind-a-velocity-proxy). |

## Rendering

| Option | Default | What it does |
| :- | :- | :- |
| `sight-trace` | `true` | Only render a model when there is a clear line of sight to it. With this off, the two sight options below do nothing. |
| `max-sight` | `-1` | Blocks beyond which a model is never rendered. `0` or below = the server's view distance. |
| `min-sight` | `5` | Blocks within which a model is always rendered, skipping the line-of-sight check — so a model right next to you never flickers out. |
| `follow-mob-invisibility` | `true` | A model on an invisible mob becomes invisible too. |
| `lerp-frame-time` | `3` | Ticks between interpolation keyframes. Lower is smoother and more expensive. |
| `packet-bundling-size` | `16` | Packets bundled before sending. `0` or below disables bundling. |
| `use-purpur-afk` | `true` | Pause animations for AFK players, using Purpur's API. |

## Modules

| Option | Default | What it does |
| :- | :- | :- |
| `module.model` | `true` | General entity models. |
| `module.player-animation` | `true` | Player-specific animations and models (limbs). |

## Resource pack

| Option | Default | What it does |
| :- | :- | :- |
| `pack.generate-modern-model` | `true` | Models for Minecraft 1.21.4 and newer. |
| `pack.generate-legacy-model` | `true` | Models for 1.21.3 and older. |
| `pack.use-obfuscation` | `true` | Obfuscate model and texture names in the pack. |
| `pack-type` | `zip` | `zip` or `folder`. |
| `build-folder-location` | `LodeEntities/build` | Where the pack is written, relative to `plugins/`. With `pack-type: zip` the file is `build.zip`. |
| `namespace` | `lodeentities` | Asset namespace: `assets/lodeentities/...`. |
| `item` | `leather_horse_armor` | The base item used for custom model data. |
| `item-namespace` | `lode_models` | Namespace for custom model items. Configs created before 3.3.0 keep their existing value. |
| `merge-with-external-resources` | `true` | Merge the generated pack with other plugins' packs. See [Nexo & ItemsAdder](https://entities.lodemc.net/resource-pack-compat.md). |
| `enable-strict-loading` | `false` | Refuse to load a model with unsupported features, instead of loading it without them. |
| `indicator.progress_bar` | `true` | Progress bar while the pack generates. |

> [!WARNING]
>
> Do not change `namespace`, `item-namespace` or `build-folder-location` casually on a live server: they decide generated asset paths. Set them once.

## Threat and factions

| Option | Default | What it does |
| :- | :- | :- |
| `threat.enabled` | `true` | Off returns mobs to plain vanilla targeting. |
| `threat.retarget-interval` | `20` | Ticks between retarget passes. Lower reacts faster to a taunt; higher is cheaper. |
| `threat.decay-per-second` | `0.02` | Fraction of threat lost each second. `0` means it never fades. |
| `threat.forget-range` | `32` | Blocks past which a mob forgets someone entirely. |

See [Factions & Threat](https://entities.lodemc.net/factions-threat.md).

## Spawners

| Option | Default | What it does |
| :- | :- | :- |
| `spawner.enabled` | `true` | Turn every [spawner](https://entities.lodemc.net/spawners.md) off at once. |
| `spawner.check-interval` | `20` | Ticks between passes. `20` = once a second. |
| `spawner.world-scaling.blocks-per-level` | `250` | Blocks from world spawn worth one extra [level](https://entities.lodemc.net/mob-levels.md). |
| `spawner.world-scaling.max-level` | `20` | Ceiling for a scaled level. |

## Natural spawning

| Option | Default | What it does |
| :- | :- | :- |
| `natural-spawn.enabled` | `true` | Turn every [spawn rule](https://entities.lodemc.net/natural-spawns.md) off at once. |
| `natural-spawn.check-interval` | `100` | Ticks between passes. `100` = every five seconds. |
| `natural-spawn.min-distance` | `24` | Closer than this and mobs would appear in someone's face. |
| `natural-spawn.max-distance` | `96` | Further and nobody would notice it happened. |
| `natural-spawn.attempts-per-player` | `8` | Candidate points per player per pass — the whole cost of the system. |
| `natural-spawn.caps.max-per-chunk` | `4` | Default cap for rules that do not name one. |
| `natural-spawn.caps.max-nearby` | `0` | Default density cap. `0` = no ceiling. |
| `natural-spawn.caps.nearby-radius` | `32` | Radius `max-nearby` measures over. |
| `natural-spawn.caps.max-per-world` | `0` | Default world total. |
| `natural-spawn.caps.max-per-player` | `0` | Default per-player total. |

## NPCs

These only matter on a server with a lot of `look: true` [NPCs](https://entities.lodemc.net/npcs.md): turning heads is the only per-tick work an NPC has.

| Option | Default | What it does |
| :- | :- | :- |
| `npc.look-interval` | `1` | Ticks between head turns. `2` is usually indistinguishable and halves the work; above about `4` heads start to look steppy. |
| `npc.activation-range` | `48` | Blocks from an NPC a player must be within for it to tick at all. `0` ticks every NPC. Keep it above 8, the distance at which NPCs notice players. |

See [NPCs](https://entities.lodemc.net/npcs.md#tuning-npc-cost) for what to tune first.

## Pets

| Option | Default | What it does |
| :- | :- | :- |
| `pets.max-active` | `1` | Pets one player can have out at once. Summoning another puts the oldest away. |
| `pets.max-owned` | `0` | Pets one player can own in total. `0` is no limit. |
| `pets.owner-can-hurt` | `false` | Whether an owner's hits land on their own pets. |
| `pets.autosave` | `60` | Seconds between saves of pet collections that changed. Always saved on logout and shutdown too. |
| `pets.max-name-length` | `32` | Longest name an owner may give a pet, colour codes included. |

[Pets](https://entities.lodemc.net/pets.md) are a premium feature; see [Pet Settings](https://entities.lodemc.net/pet-settings.md).

## Menu overlay

`gui-overlay.*` has [its own page](https://entities.lodemc.net/menu-overlay.md).

## Player models

| Option | Default | What it does |
| :- | :- | :- |
| `cancel-player-model-inventory` | `false` | Block hotbar swaps while a player model or animation is active. |
| `player-hide-delay` | `3` | Ticks before the original player entity is hidden after a model is applied. Minimum 1. |
| `default-mount-controller` | `walk` | For mountable models: `walk`, `fly`, `none` (mountable, no steering) or `invalid` (not mountable). Anything else reads as `walk`. |

## Debug and misc

| Option | Default | What it does |
| :- | :- | :- |
| `debug.hitbox` | `false` | Messages for hitbox creation and interaction. |
| `debug.exception` | `false` | Full stack traces for handled exceptions. |
| `debug.pack` | `false` | Messages for pack generation. |
| `debug.tracker` | `false` | Messages for model tracker lifecycle. |
| For config *problems* rather than config options, see [`/le debug`](debug). | | |


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