Quick Start

Prerequisites

• Dominion is installed and enabled on the server;
• the development environment uses Java 17 or later;
• the compile-time DominionAPI version is compatible with the target Dominion version;
• the plugin runs in a server environment that provides the Bukkit, Paper, or Folia API.

DominionAPI has been available since Dominion 2.9.0-beta. The examples below use the latest Maven Central release as x.x.x; the page replaces this version automatically when it opens.

If the version cannot be fetched, the placeholder remains. Click the version, or open the Maven Central artifact page directly to view the latest release.

1. Add the compile-time dependency

Add the API as a compile-time dependency only. Do not package DominionAPI or the Dominion implementation JAR inside your addon, or duplicate classes and version conflicts may occur.

Maven

<dependency>
    <groupId>cn.lunadeer</groupId>
    <artifactId>DominionAPI</artifactId>
    <version>x.x.x</version>
    <scope>provided</scope>
</dependency>

Gradle Groovy

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'cn.lunadeer:DominionAPI:x.x.x'
}

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    compileOnly("cn.lunadeer:DominionAPI:x.x.x")
}

If your target server still uses an older Dominion release, replace the dependency version with the compatible version and re-check the version-sensitive API notes in this guide.

2. Declare the plugin dependency

If the addon cannot work without Dominion, declare a hard dependency in plugin.yml:

name: MyDominionAddon
version: 1.0.0
main: com.example.mydominionaddon.MyDominionAddon
api-version: '1.20'
depend:
  - Dominion

If Dominion is an optional integration, use softdepend and check whether the plugin is enabled in onEnable(). Without Dominion, disable only the integration instead of preventing the addon’s other features from starting.

Do not depend on DominionAPI.getInstance() during onLoad(). Dominion may not have finished initializing at that point.

3. Get the API singleton

The following addon queries the claim at a player’s location when the player joins:

package com.example.mydominionaddon;

import cn.lunadeer.dominion.api.DominionAPI;
import cn.lunadeer.dominion.api.dtos.DominionDTO;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyDominionAddon extends JavaPlugin implements Listener {
    private DominionAPI dominionAPI;

    @Override
    public void onEnable() {
        if (!getServer().getPluginManager().isPluginEnabled("Dominion")) {
            getLogger().severe("Dominion is not enabled; disabling addon.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        dominionAPI = DominionAPI.getInstance();
        if (dominionAPI == null) {
            getLogger().severe("DominionAPI is unavailable; disabling addon.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        DominionDTO dominion = dominionAPI.getDominion(event.getPlayer().getLocation());
        if (dominion == null) {
            getLogger().info(event.getPlayer().getName() + " is not inside a dominion.");
            return;
        }
        getLogger().info(event.getPlayer().getName() + " is in " + dominion.getName());
    }
}

getDominion(Location) is a direct spatial query. If you need Dominion to maintain the player’s “current claim” state and fire entry/exit events, use getPlayerCurrentDominion(Player) instead. See the main API for details.

4. Verify the integration

Check the following on a test server:

1. The console shows that the addon enables after Dominion;
2. DominionAPI.getInstance() is not null;
3. a player completes one query inside a claim and one outside a claim;
4. the server does not package duplicate DominionAPI classes;
5. both Paper and Folia target environments have been tested in practice.

Next steps

• Read API modules to understand the packages and responsibilities of each class;
• read Common API to find calls by task;
• use Common examples as a starting point for query, permission, and event integrations.