Type to search the current language.

View all results
DominionAPI Developer Guide
Docs/dominion-api/DominionAPI Developer Guide

DominionAPI Developer Guide

A usage guide, API module reference, and collection of common examples for Dominion addon developers.

What this guide covers

This guide is for Paper, Spigot, and Folia plugin developers who use DominionAPI. It helps you build Dominion addons and other integrations without reading the Dominion database or depending on Dominion’s internal cache and NMS implementation.

This documentation follows the current public source of the Dominion/api module. The API build documented here is 4.9.3. When the release version changes, also check the JavaDoc for current signatures and behavior.

GoalPage
Connect to the API for the first time and complete a queryQuick start
Understand how the API is divided by responsibilityAPI modules
Find the most common query, permission, write, and event interfacesCommon API
Copy and adapt working implementationsCommon examples

The API’s boundaries

You can think of DominionAPI as three layers:

  1. Query layer: use DominionAPI to read claims, players, members, groups, and flag data;
  2. Operation layer: use DominionProvider, GroupProvider, MemberProvider, and other providers to change data;
  3. Integration layer: listen to Dominion events to respond to claim entry/exit, data changes, and custom flag registration.

Treat DTOs as read-only views of the current cached state. Some DTOs expose set... methods, but addons should not call them to modify persisted data directly. Writes should go through providers so Dominion can perform permission, boundary, economy, database, and event processing.

Keep these points in mind

  • Only obtain the DominionAPI.getInstance() and provider singletons after Dominion is enabled; initialization in onEnable() is the usual approach.
  • Add the API as a compileOnly dependency; the Dominion plugin on the server provides it at runtime.
  • Provider operations return CompletableFuture. Do not block the main thread or a Folia region thread with get(), join(), or similar calls.
  • The operator parameter on a provider determines the operation identity. Passing a player performs the corresponding permission checks; passing the console can bypass player permissions but still performs data validity checks.
  • Missing claims, players, members, and groups usually result in null. Batch queries return lists, while failed asynchronous writes usually result in null or false.
  • Registering, displaying, and persisting a custom flag does not implement its in-game behavior. The addon still needs to listen to Bukkit/Paper events and perform permission checks.

Official references