Common API

Common API at a glance

Need	Preferred API	Details
Query the claim at a location	DominionAPI#getDominion(Location)	Queries and permissions
Query a player’s current claim	DominionAPI#getPlayerCurrentDominion(Player)	Queries and permissions
Check whether a player can perform an action	checkPrivilegeFlag / checkPrivilegeFlagSilence	Queries and permissions
Check an environment rule	checkEnvironmentFlag(Location, EnvFlag)	Queries and permissions
Modify a claim, member, or group	The corresponding Provider	Data writes
Listen for claim entry and exit	PlayerMoveInDominionEvent, and others	Event integrations
Register a configurable new rule	Flags.register... + Flags.applyChanges()	Flags module

Call sequence

Typical addon logic can follow this sequence:

1. Cache the DominionAPI singleton in onEnable();
2. query the target DTO by location or UUID;
3. end the flow immediately when the query returns nothing; do not use a special ID to pretend that an object exists;
4. use the position-based permission check when a player action needs authorization;
5. use a provider for data changes and process the completion value asynchronously;
6. listen for events when you need to respond to state changes instead of periodically scanning every claim.

Related pages

• Queries and permissions: the most common read operations and permission checks;
• Data writes: providers, operation identities, and asynchronous results;
• Event integrations: cancellation, modification, and operation-completion callbacks.