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

# Free Version & Licensing

> What the free version allows, adding a license key, and licensing a whole network through a Velocity proxy.

LodeEntities runs without a license. The free version is a real tier, not a trial: nothing expires and nothing is switched off. It stops loading past three limits, and [pets](https://entities.lodemc.net/pets.md) are licensed-only.

| Limit | Free version | Licensed |
| :- | :- | :- |
| Entities (mobs in `Mobs/`) | **12** | unlimited |
| NPCs (`type: npc` mobs) | **3** | unlimited |
| Effect lines | **40** | unlimited |
| [Pets](https://entities.lodemc.net/pets.md) | **not available** | ✅ |

* **Effect lines are counted wherever they are written**: a mob's `effects:`, the skills inside a mob, and every top-level skill all draw on the same 40. Mobs load first and take their share; top-level skills get what is left.
* **NPCs have their own budget.** A `type: npc` mob counts against the 3 NPCs, never against the 12 entities.
* **Nothing is cut in half.** Entries load in the order they are declared, and anything that doesn't fit is skipped whole, so you never get a mob with half its effects.
* **Pets are premium.** On the free version every `pet:` block is dropped with a notice (`Pets are a premium feature.`) and the mob loads as an ordinary wild mob, so a free server never loses a mob over it. `/le pets give` refuses with the same reason. Add a license and they load on the next reload.

Everything skipped is named on the console at load and reload, to whoever ran `/le reload`, and to staff as they join:

```text theme={null}
LodeEntities is running the FREE version: up to 12 entities, 3 NPCs and 40 effect lines.
Free version limit reached: 12 entities. 3 not loaded - buy a license to load them.
  not loaded: mob13
  not loaded: mob14
```

The two starter mobs count like any other; delete them if you need the room. [`/le about`](version-check) says which edition a server is running at any time.

## Adding a license

**Bought on BuiltByBit? There is nothing to do.** The jar you download already carries your license key. On its first start the plugin writes that key to `plugins/LodeEntities/mclicense.txt` and runs licensed. You never need to look the key up or type it in.

The key is written to the file so it outlives the jar: if you later swap in a jar that has no key in it (one copied from another server, say), the server keeps its license. A key that is already in `mclicense.txt` is never overwritten, so one you entered yourself always wins over the one in a newer download.

If the key that came with the jar doesn't validate, the console says so outright instead of leaving you to wonder:

```text theme={null}
The license key bundled with this download did not validate - running on the free version.
```

**Got your key some other way?** Put it in `plugins/LodeEntities/mclicense.txt` (the file is created on first run) and restart. Validation is handled by [MC License](https://mclicense.org).

**Or enter it in game**, when you can't reach the file (a hosting panel without file access, or a key that arrived while the server was running):

```text theme={null}
/le activate <your-key>
```

**Permission:** `lodeentities.activate`

It saves the key where the file would have, so the next boot needs nothing more, then reloads so everything the free version held back loads straight away. A key that doesn't validate changes nothing: it isn't left on disk, and the console says why it was refused. Once a server is licensed the command is refused.

> [!WARNING]
>
> The key is typed as a command, so it lands in the server log and in the console history of whoever ran it. On a server with other staff, editing the file is the more private route.

A server that can't reach the internet, or whose key is missing or expired, runs the free version. LodeEntities never refuses to start over licensing.

## Networks behind a Velocity proxy

A license covers a set number of **running servers**. Each running server takes a slot, and so does each restart; a server that crashes keeps its slot until the license service times it out. On a network, that would mean a slot for every hub, game server and instance started on demand.

**On a network, the proxy holds the license instead**, and the whole network uses one slot per proxy, however many servers run behind it.

**1. Install on the proxy**

Put the **same LodeEntities jar** in the proxy's `plugins/` folder (Velocity 3.5 or 4.x).

**2. Start the proxy**

A jar downloaded from BuiltByBit carries your key, and the proxy writes it to `plugins/lodeentities/mclicense.txt` on its first start, so there is nothing to enter. Otherwise, put your key in that file and restart the proxy. If it has no key at all, it says so on its console and network licensing stays off.

**3. Point every backend at the proxy**

In each backend's `config.yml`:

```yaml theme={null}
network-license:
  proxy: "127.0.0.1:25580"
```

Backends must use Velocity **modern forwarding**: `proxies.velocity.enabled: true` in `config/paper-global.yml`, with the same `secret` as the proxy's `forwarding.secret`. That shared secret is how the proxy knows a server belongs to its network; a server without it is refused.

A backend licensed this way logs:

```text theme={null}
Licensed by the network license on the proxy at 127.0.0.1:25580 - this server uses no license slot of its own.
```

### The relay's address and port

They are in `plugins/lodeentities/network-license.properties` on the proxy:

| Option | Default | What it does |
| :- | :- | :- |
| `bind` | `127.0.0.1` | Address the relay listens on. Enough while every backend runs on the proxy's machine. Use `0.0.0.0` or the machine's LAN address once backends run elsewhere. |
| `port` | `25580` | Port the relay listens on. Must differ from the proxy's own port. |

### When a backend can't get a license from the proxy

It says why on its console, then checks its own `mclicense.txt` the way a standalone server does.

* **The proxy isn't up yet**, which is common when a whole network starts at once: the backend starts on the free version and asks again every 30 seconds for 10 minutes. Once the proxy answers, the backend reloads with everything loaded.
* **The proxy refused it** (wrong secret, or the proxy's own license failed): there's no retry. Fix the config and restart the backend.

On the proxy, **`/lenetwork`** (permission `lodeentities.network`; the console is always allowed) shows whether the network license is valid and which backends it has licensed since it started.

**Servers outside the proxy still need their own slot**, such as a test server at home or a build server players never reach through the proxy. Give them the key in their own `mclicense.txt` and leave `network-license.proxy` empty.


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