# 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:

![](https://repo.nightexpressdev.com/api/badge/latest/releases/su/nightexpress/excellentclaims/api?color=40c14a&name=ExcellentClaims-api&prefix=v)

+++Maven
**Repository:**
```xml
<repository>
  <id>nightexpress-releases</id>
  <url>https://repo.nightexpressdev.com/releases</url>
</repository>
```

**Dependency:**
```xml
<dependency>
  <groupId>su.nightexpress.excellentclaims</groupId>
  <artifactId>api</artifactId>
  <version>{VERSION}</version>
  <scope>provided</scope>
</dependency>
```

+++Gradle
**Repository:**
```gradle
maven { url = 'https://repo.nightexpressdev.com/releases' }
```

**Dependency:**
```gradle
compileOnly("su.nightexpress.excellentclaims:api:{VERSION}")
```
+++

!!!tip
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**

---

## :icon-phs-wrench: 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.

```java
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:**

```java
// 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:**

```java
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:**

```java
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:**

```java
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:**

```java
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:**

```java
EnvironmentTester tester = evaluators.environment();

// Prevent lava from flowing into protected areas
if (!tester.canFlow(lavaBlock, targetAirBlock)) {
    event.setCancelled(true);
}

```