Dependencies

Before you start writing a plugin, it is worth getting to know which modules Numen is made of and how they depend on each other, so that you can find the one you actually need to depend on. The implementation details of each module are covered in Deep Dive; this page only covers how they relate.

Numen API and Plugins

ai, agent, lua, ui and api together make up the Numen API, with the mod ID numen_api. The code of the first four modules is laid out flat inside its jar.

The Numen API on its own is already a complete agent. So what happens if only the Numen API is installed?

The agent can still chat, run Lua programs and even run commands, but it can do almost nothing to the world, because we have not provided any Lua APIs.

Numen is the first plugin of the Numen API, with the mod ID numen; in the repository it is the core module. To register its own Lua APIs, skills and Lua modules, it uses exactly the same entry point as every other plugin, NumenPlugins.register, with no special treatment. The pathfinding it needs is also its own dependency, rather than being put into the Numen API.

So Numen, the built-in plugins and your plugin are peers: they are all plugins of the Numen API.

The only difference is how they are released: Numen and the built-in plugins are bundled and released together, while your plugin is installed separately.

The Numen that players install is a single jar that bundles Numen, the built-in plugins and the Numen API, with the Numen API nested inside it as a jar-in-jar.

Which One to Depend On

There are three artifacts developers can depend on. Choose based on what you want to do.

Artifact	What it contains	When to use it
Slim API numen-api-<loader>-<mc>:<version>:api	The public part of the Numen API	Writing plugins. This is enough in the vast majority of cases
Full Numen API numen-api-<loader>-<mc>:<version>	All of the Numen API's code	The public API is not enough and you need Mixins to modify the internals of the Numen API
Numen numen-<loader>-<mc>:<version>	Numen and the built-in plugins, automatically bringing in the full Numen API	You need Mixins to modify Numen's built-in Lua APIs, tasks or built-in plugins

ai, agent, lua and ui are also published separately. Depending on any of the artifacts above brings them in automatically, so you do not need to declare them yourself.

Known issue in 0.1.4

This page describes the structure from 0.1.5 onwards. In 0.1.4, pathfinding (pathing) was still laid out flat in the Numen API, and the agent's body NumenPlayer depended on it; but pathfinding was not published to maven on its own, while the Numen API's dependency metadata still referenced it. So if you depend on 0.1.4 as written above, Gradle will report that it cannot find numen-pathing-<mc>.

On 0.1.4, use the following instead: depend on the full Numen API and exclude that reference. The full Numen API already contains the pathfinding classes, so methods that call call.her() will still compile.

dependencies {
    compileOnly("com.dwinovo.numen:numen-api-neoforge-1.21.1:0.1.4") {
        exclude group: 'com.dwinovo.numen', module: 'numen-pathing-1.21.1'
    }
}

From 0.1.5 onwards, pathfinding belongs to Numen and the Numen API no longer references it, so just depend on the slim API as shown in the table above.

Everything outside the slim API is internal implementation and may change in any version. If you depend on internals, pin Numen's version range to the versions you have tested. Better yet, when you find something missing from the public API, open an issue on GitHub: we would much rather add it to the public API so that every plugin can use it.

Just like Numen, your plugin declares its dependency on the mod ID numen_api; you only need to depend on numen when you use Mixins to modify Numen itself. See Plugins for how to write this.