UXPLIMA Documentation / Adding Dependency

Adding Dependency

The uxmEssentials developer API is published as an ordinary Maven artifact. You add one repository and one coordinate, and your IDE gives you the event classes, the front door, and the value types with full javadoc.

Copy Markdown

The coordinate

Gradle (Kotlin)

repositories {
    maven("https://raw.githubusercontent.com/UXPLIMA/uxmEssentials/maven")
}

dependencies {
    compileOnly("com.uxplima.uxmessentials:uxmessentials-bukkit-api:VERSION")
}

Gradle (Groovy)

repositories {
    maven { url 'https://raw.githubusercontent.com/UXPLIMA/uxmEssentials/maven' }
}

dependencies {
    compileOnly 'com.uxplima.uxmessentials:uxmessentials-bukkit-api:VERSION'
}

Maven

<repositories>
    <repository>
        <id>uxplima</id>
        <url>https://raw.githubusercontent.com/UXPLIMA/uxmEssentials/maven</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.uxplima.uxmessentials</groupId>
        <artifactId>uxmessentials-bukkit-api</artifactId>
        <version>VERSION</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Replace VERSION with the uxmEssentials version you are building against. /uxmess version prints what a server is running, and UxmEssentialsApi.version() gives you the same string at runtime.

Which versions are in the repository

The repository carries the API from the first release that shipped it onward. Older versions of uxmEssentials have no artifact and no API classes inside the plugin jar, so a coordinate that resolves is also a promise that the classes are there at runtime.

compileOnly (Maven: provided) is the right scope, and the only correct one. The classes live inside the uxmEssentials plugin jar on the server; shading them into your own jar would give you a second copy of every event class and Bukkit would then deliver events your listener never sees.

What the one coordinate gives you

uxmessentials-bukkit-api depends on uxmessentials-api, so a single line brings both:

Artifact	Contains	Depends on
`uxmessentials-bukkit-api`	The front door (`UxmEssentialsApi`), every Bukkit event, the menu surface	Paper, `uxmessentials-api`
`uxmessentials-api`	Pure value types with no Bukkit in them: `UxmLocation`, `UxmMoney`, `UxmTeleportKind` and the rest	nothing

The split exists so a proxy-side, web-side or test-side piece of your project can speak the same vocabulary without dragging a server API onto its classpath. If you are writing a Paper plugin, take uxmessentials-bukkit-api and ignore the split.

Sources jars are published alongside both, so your IDE shows the javadoc without a separate download.

Your paper-plugin.yml

Nothing is required. Declaring a dependency on uxmEssentials is a choice, not a rule:

name: MyAddon
main: com.example.MyAddon
version: '1.0.0'
api-version: '1.21'

UxmEssentialsApi.whenReady handles either load order for you, and Bukkit delivers events from a plugin that loaded later just the same. Add a soft dependency only if you have your own reason to influence load order:

dependencies:
  server:
    uxmEssentials:
      load: BEFORE
      required: false

Never make it required

required: true means your plugin refuses to load on a server without uxmEssentials. Since every entry point in this API is null-safe or callback-based, there is nothing to gain from it and a support ticket to lose.

A complete example

The sample consumer in the repository is a small, compiling plugin that uses the front door, one veto listener and two notification listeners. It is built in CI against the published artifacts on every commit, so what it shows is what currently works.

Next steps

Overview for the front door and the shape of the API
Events for everything you can listen to and everything you can cancel
Menu API to extend the GUI engine rather than only observe it

Was this page helpful?