Developer API
ExcellentClaims provides a robust and easy-to-use API for developers looking to integrate their plugins with it.
Replace {VERSION} with the latest version shown on the badge below:
Repository:
<repository>
<id>nightexpress-releases</id>
<url>https://repo.nightexpressdev.com/releases</url>
</repository>Dependency:
<dependency>
<groupId>su.nightexpress.excellentclaims</groupId>
<artifactId>api</artifactId>
<version>{VERSION}</version>
<scope>provided</scope>
</dependency>Repository:
maven { url = 'https://repo.nightexpressdev.com/releases' }Dependency:
compileOnly("su.nightexpress.excellentclaims:api:{VERSION}")If you want to create an addon for it, change dependency artifact id from api to core.
Events
- LandChunkClaimedEvent - When chunk is claimed by a player.
- LandChunkClaimEvent - When player is about to claim a chunk. Cancellable
- LandClaimMergedEvent - When player merged two lands into one.
- LandClaimMergeEvent - When player is about to merge lands. Cancellable
- LandClaimSplittedEvent - When player split land.
- LandClaimSplitEvent - When player is about to split land. Cancellable
- LandChunkUnclaimedEvent - When chunk is unclaimed by a player.
- LandChunkUnclaimEvent - When player is about to unclaim a chunk. Cancellable
- RegionCreatedEvent - When region is created by a player.
- RegionCreateEvent - When player is about to create a region. Cancellable
- RegionRemovedEvent - When region removed by a player.
- RegionRemoveEvent - When player is about to remove a region. Cancellable
API Usage
It is recommended to inject the ClaimsAPI instance into your consumer classes rather than relying on global static access. The implementation can be retrieved via the Bukkit Services Manager.
public class ClaimServiceConsumer {
private final ClaimsAPI claimsAPI;
public ClaimServiceConsumer() {
RegisteredServiceProvider<ClaimsAPI> provider = Bukkit.getServicesManager().getRegistration(ClaimsAPI.class);
if (provider == null) {
throw new IllegalStateException("ExcellentClaims API is not loaded!");
}
this.claimsAPI = provider.getProvider();
}
public ClaimsAPI getClaimsAPI() {
return this.claimsAPI;
}
}ClaimsAPI
The core entry point for interacting with claims, modules, and rule systems.
Example Usage:
// Retrieving a claim at a specific location
Location location = player.getLocation();
Claim currentClaim = claimsAPI.getPrioritizedClaim(location);
// Access the global claim registry for more specialized retrieval methods
ClaimRegistry registry = claimsAPI.getClaimRegistry();
Set<Claim> claimsInChunk = registry.getInChunk(location.getChunk());
// Safely accessing the RulesAPI module
claimsAPI.rules().ifPresent(rulesAPI -> {
// Execute rules logic
});
RulesAPI
Handles the evaluation, menu rendering, and registry lookups for claim-specific rules.
Example Usage:
RulesAPI rulesAPI = claimsAPI.rules().orElseThrow();
// Testing if a player is allowed to open the rules menu for a claim
ActionResult result = rulesAPI.canOpenRules(player, claim);
if (result.isSuccess()) {
rulesAPI.openRulesMenu(player, claim, flagger, null, null);
}
RuleEvaluators
Provides specific tester interfaces to evaluate localized rules for different event contexts.
Example Usage:
RuleEvaluators evaluators = rulesAPI.getEvaluators();
PlayerTester playerTester = evaluators.player();
EntityTester entityTester = evaluators.entity();
PlayerTester
Validates specific interactions, combat, block modifications, and movement initiated by a Player.
Example Usage:
PlayerTester tester = evaluators.player();
// Check if a player can destroy a block before executing logic
if (!tester.canDestroy(player, targetBlock)) {
player.sendMessage("You cannot break blocks here.");
return;
}
EntityTester
Validates autonomous behaviors, spawning, and block interactions caused by non-player entities.
Example Usage:
EntityTester tester = evaluators.entity();
// Check if a Creeper or Enderman can modify the environment
if (!tester.canChange(entity, targetBlock)) {
event.setCancelled(true);
}
EnvironmentTester
Validates natural block updates, fluid mechanics, vegetative growth, and physics events.
Example Usage:
EnvironmentTester tester = evaluators.environment();
// Prevent lava from flowing into protected areas
if (!tester.canFlow(lavaBlock, targetAirBlock)) {
event.setCancelled(true);
}