Mod Lifecycle
This page explains how LeviLamina finds the mods of a server or client, in which order it loads them, and when it
calls a mod's load, enable, disable and unload. The classes and fields named here are listed on the
Mod page.
The Four Steps
A mod goes through four steps. Each one calls a callback of the mod; a callback that returns false stops the step,
and LeviLamina logs why.
| Step | When it happens | Callback | After it |
|---|---|---|---|
| Load | At startup, for every mod that should run; at runtime with /ll load |
load() |
The mod is loaded and disabled |
| Enable | When the game has started; right after loading if the game is already running | enable() |
The mod is enabled |
| Disable | When the game stops; at runtime with /ll disable |
disable() |
The mod is disabled, still loaded |
| Unload | Only at runtime, with /ll unload or /ll reload |
unload() |
The mod is gone; its DLL is freed |
A mod is either Enabled or Disabled (Mod::State): a mod that has just been loaded is disabled until it is
enabled. When the game stops, mods are disabled, not unloaded.
With LL_REGISTER_MOD(Class, instance) (see Registering the Mod Entry),
load() is required and enable(), disable() and unload() are used when the class defines them. A native mod
without an unload() cannot be unloaded at runtime: LeviLamina refuses with "The mod does not register an unload function".
Finding the Mods
At startup LeviLamina looks at every folder in the mods root: plugins/ on the server and mods/ on the client (see
Directory Structure).
- A folder without a
manifest.json, or with an empty one, is skipped. - The manifest's
namemust be the name of its folder; otherwise the mod is not loaded ("Mod name … do not match folder …"). - Manifests of the type
preload-nativeare skipped: PreLoader loads those before the game starts, and they are not LeviLamina mods (see Mod Types).
Choosing and Ordering
From the manifests, LeviLamina makes a plan before it loads anything:
- Which mods. It starts from every mod that is not
passive, and adds what they need: theirdependencies, and theoptionalDependenciesthat are installed in a matching version. Apassivemod is loaded only when another mod that is loaded depends on it. - Which of them cannot run. A mod is left out when a dependency is missing or has a version outside the range
it asks for; when its
platformis not this one (serverorclient;universalor noplatformruns on both); when it lists inconflictsanother mod of the plan, in a matching version; when one of its dependencies is left out; or when it is in a dependency cycle. The log says why, for example "… will not be loaded because it conflicts with …". - In which order. Dependencies and optional dependencies come before the mods that use them; a mod with
loadBeforecomes before the mods it names. Mods that have no order between them are loaded by name.
Then the mods are loaded one after the other in that order. A mod whose dependency failed to load is skipped too.
Load
On the server, LeviLamina loads the mods while the game's main starts, before the game itself runs; on the client,
when PreLoader loads LeviLamina into the game. The game, its world and its players do not exist yet.
A mod's type decides who loads it. LeviLamina loads native mods itself; another type is loaded by the mod manager
that was registered for it (for example by a script engine). For a native mod, LeviLamina:
- adds the mod's folder to the
PATH, so that the DLLs it ships next to its own are found; - loads the DLL named by the manifest's
entry. When Windows cannot load it because a DLL or a function it imports is missing, LeviLamina logs which ones; - checks that the DLL uses LeviLamina's memory allocation operators (
ll/api/memory/MemoryOperators.h); a DLL that does not is not loaded; - calls the mod's
load().
Static objects of the DLL are created while the DLL loads, before load(): this is when the hooks declared with an
LL_AUTO_ macro are installed (see Events and Hooks).
Enable
On the server, the mods are enabled once the server thread has started; on the client, when the game has finished
initializing. They are enabled in the order they were loaded, and LeviLamina logs "Enabling … v…" for each one.
A mod is enabled only when all its dependencies are enabled.
enable() is where a mod starts to take part in the game: it registers its listeners, commands and so on. A mod
loaded while the game is already running (with /ll load) is enabled right after its load().
Disable and Unload
When the server stops, or the client's window closes, LeviLamina disables the mods in the reverse of the order they were loaded, so a mod is disabled before the mods it depends on.
A mod can also be disabled or unloaded while the game runs. Then LeviLamina cleans up after it:
- Disabled while the game runs: the event listeners of the mod are removed and its commands are disabled.
- Unloaded: the mod is disabled first; then its
unload()runs, its listeners and the events it provided are removed from the event bus, and its DLL is freed.
A mod cannot be disabled or unloaded while a mod that depends on it is still enabled or loaded: LeviLamina answers
"… still depends on …". loadBefore does not create such a link (see
Dependency Semantics).
Managing Mods at Runtime
LeviLamina's command /ll runs these steps on a mod while the game runs:
| Command | What it does |
|---|---|
/ll load <mod> [cascade] |
Loads a mod that is in the mods root but not loaded, and enables it |
/ll unload <mod> [cascade] |
Disables and unloads a mod |
/ll reload <mod> [cascade] |
Unloads a mod and loads it again |
/ll reactivate <mod> [cascade] |
Disables a mod and enables it again |
/ll enable <mod> [cascade] |
Enables a disabled mod |
/ll disable <mod> [cascade] |
Disables a mod |
/ll show <mod> [cascade] |
Shows the manifest of a mod: name, author, description, type, version, entry, extra info |
/ll list |
Lists the loaded mods |
/ll load needs the mod's dependencies to be loaded already. With cascade, the mods linked to it follow: load
also loads the mods of the mods root that depend on it; unload, reload and disable take the mods that depend on
it along; enable enables its dependencies first; and show prints its dependencies and dependents as trees.
On the server the command is /levilamina, /ll for short, and needs the permission level Admin by default; in the
client it is /clilevilamina, /clill for short, and anyone may use it. It is set in LeviLamina's own configuration,
LeviLamina/config/Config.json in the mods root, under modules.command.modManageCommand (enabled, and permission, used on the server).
Related
- Mod —
Mod,Manifest,LL_REGISTER_MODand the mod's folders - Events and Hooks — what happens to listeners and hooks when a mod is enabled, disabled or unloaded
- Your first LeviLamina mod — a mod from the template, step by step