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

# Addon API

> Extend LodeEntities from your own plugin: setup, the entry point, and the API surfaces.

LodeEntities ships a **public addon API**. If you can write a Bukkit plugin, you can extend it the way addon ecosystems grow around the big plugins: register your own effect **mechanics**, **targeters**, **triggers**, **conditions** and **placeholders**, listen to LodeEntities **events**, and drive **mobs, NPCs, spawners and effects** from code.

Java and Kotlin both work. Most examples in this section are Java.

## Setting up an addon

**1. Add the LodeEntities jar as a compile-only dependency**

There is no separate API artifact yet, so you compile against the plugin jar itself.

```kotlin build.gradle.kts theme={null}
dependencies {
    compileOnly(files("libs/LodeEntities.jar"))
}
```

**2. Declare the dependency in plugin.yml**

This makes your plugin enable after LodeEntities.

```yaml plugin.yml theme={null}
depend: [LodeEntities]
```

**3. Register everything in onEnable**

Registrations survive `/le reload`, so you never need to re-register.

## The entry point

Everything is reachable from one class: `org.nexomaker.api.LodeEntitiesAPI`.

| Accessor | What it gives you |
| - | - |
| `LodeEntitiesAPI.effects()` | The effect language: register [mechanics, targeters, triggers, conditions and placeholders](https://entities.lodemc.net/extending-effects.md); parse and run skills |
| `LodeEntitiesAPI.mobs()` | Registered [mobs](https://entities.lodemc.net/addon-mobs.md): lookup, spawn, fire triggers, factions and threat, contribute bundled mobs |
| `LodeEntitiesAPI.spawners()` | [Spawners](https://entities.lodemc.net/addon-spawners.md) from `Mobs/`: lookup, live counts, enable, reset, trigger, levels |
| `LodeEntitiesAPI.naturalSpawns()` | [Natural spawn rules](https://entities.lodemc.net/addon-natural-spawns.md) (`type: spawn` in `Mobs/`): lookup, explain, contribute bundled rules |
| `LodeEntitiesAPI.npcs()` | [`type: npc` mobs](addon-npcs-dialogs): lookup, and telling an NPC from a plain mob |
| `LodeEntitiesAPI.dialogs()` | Branching [conversations](https://entities.lodemc.net/addon-npcs-dialogs.md#dialogs): lookup, start and stop for any player |
| `LodeEntitiesAPI.pets()` | Players' [pets](https://entities.lodemc.net/addon-pets.md): collections, give, summon, dismiss, experience, the menu |

## What that makes possible

The five extension points cover the whole skill language: new mechanics, targeters, triggers, conditions and placeholders. Add `mobs().contribute(...)` and `naturalSpawns().contribute(...)` on top, and an addon can ship a complete content pack (mobs, spawn rules and new vocabulary) without shipping a single YAML file. A server owner can still override any of it by declaring the same id in their own config.

> **[Extending the effect language](https://entities.lodemc.net/extending-effects.md)**
>
> Teach the effect language new words that server owners use exactly like built-ins.

> **[Models & animation](https://entities.lodemc.net/addon-models.md)**
>
> Attach a model to any entity, play animations, restyle bones and hook per-bone hitboxes, through the engine's API in the same jar.

## Stability

* Everything under `org.nexomaker.api` is the supported addon surface. The types it hands out (`MechanicArgs`, `EffectContext`, `MobDefinition` and the rest) are stable to compile against.
* `org.nexomaker.engine.api` is the model engine's own API: [models, animations, bones and hitboxes](https://entities.lodemc.net/addon-models.md). You can call it from the same jar, but it moves at the engine's pace.
* Anything else is internal and may change without notice.
* Never expect a Kotlin type in a signature: the API hands out Java-friendly types (a `Map` rather than a Kotlin `Pair`), because the Kotlin runtime is relocated inside the jar.


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