API - snazzyatoms/AegisGuard GitHub Wiki

🔧 Dependency Setup

🛠 (Maven/Gradle)

To build against AegisGuard, you must add the JitPack repository first.

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.snazzyatoms</groupId>
        <artifactId>AegisGuard</artifactId>
        <version>1.2.6.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

🟩 Gradle (Kotlin DSL)

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    
    compileOnly 'com.github.snazzyatoms:AegisGuard:1.2.6.1'
}

🛠️ Common Examples

1️⃣ Check if a Location is inside a Plot

Location loc = player.getLocation();
Plot plot = api.store().getPlotAt(loc);

if (plot != null) {
    player.sendMessage("You are standing in " + plot.getOwnerName() + "'s plot!");
} else {
    player.sendMessage("This land is wild/unclaimed.");
}

2️⃣ Check Player Permissions in a Plot Check if a player has rights to build, interact, or open containers in a specific location.

Plot plot = api.store().getPlotAt(block.getLocation());

if (plot != null) {
    // Check if player has BUILD permission in this plot
    // The plugin handles role checks (Owner, Member, Guest) automatically.
    if (plot.hasPermission(player.getUniqueId(), "BUILD", api)) {
        // Allowed
    } else {
        // Denied
    }
}

3️⃣ Create a Plot Programmatically

UUID ownerUUID = player.getUniqueId();
Location corner1 = new Location(world, 100, 64, 100);
Location corner2 = new Location(world, 120, 64, 120);

// Create the plot (automatically saves to DB/YML and handles indexing)
api.store().createPlot(ownerUUID, corner1, corner2);

4️⃣ Modify Plot Flags

Plot plot = api.store().getPlotAt(loc);

if (plot != null) {
    // Turn off PvP
    plot.setFlag("pvp", false);
    
    // Turn on Flight (New in v1.0.2)
    plot.setFlag("fly", true);
    
    // Save changes to disk/database
    api.store().setDirty(true);
}

5️⃣ Work with Zones (Sub-Claims) – v1.1.0+

// Check if a specific block location is inside a rented sub-zone
Zone zone = plot.getZoneAt(block.getLocation());

if (zone != null) {
    if (zone.isRented()) {
        player.sendMessage("This area is rented by: " + Bukkit.getOfflinePlayer(zone.getRenter()).getName());
    } else {
        player.sendMessage("This area is for rent! Price: $" + zone.getRentPrice());
    }
}

🔌 AegisGuard Event API

Developers can listen to these custom events to extend AegisGuard's functionality, cancel actions, or trigger custom rewards.

Package: com.aegisguard.api.events

1️⃣ PlotClaimEvent

Fired when a player attempts to claim a new plot using the Scepter or command.

Cancellable: ✅ Yes

Use Case: Prevent claiming in specific biomes, charge custom currencies, or enforce stricter limits.

Methods:

getPlayer(): The player attempting the claim.

getPlot(): The Plot object being created (contains bounds, world, etc.).

2️⃣ PlotDeleteEvent

Fired when a plot is unclaimed by a player or removed by an admin.

Cancellable: ❌ No (Monitor only)

Use Case: Log data, refund items, or clean up custom holograms associated with the plot.

Methods:

getPlot(): The Plot object being deleted.

Note: This event fires before the data is removed from the database.

3️⃣ PlotEnterEvent

Fired when a player crosses the border into a plot.

Cancellable: ✅ Yes

Use Case: Implement "Entry Fees," restricting access to specific ranks, or playing custom sounds.

Behavior: If cancelled, the player is bounced back to their previous location.

Methods:

getPlayer(): The player entering the plot.

getPlot(): The Plot they are entering.

4️⃣ PlotLeaveEvent

Fired when a player crosses the border out of a plot.

Cancellable: ❌ No

Use Case: Remove buffs, send "Goodbye" titles, or clear custom scoreboards.

Methods:

getPlayer(): The player leaving the plot.

getPlot(): The Plot they just left.

5️⃣ PlotLevelUpEvent

Fired when a player successfully upgrades their plot level via the /ag level menu.

Cancellable: ❌ No

Use Case: Broadcast a global message, give rare items as a reward, or unlock third-party plugin features.

Methods:

getPlayer(): The player performing the upgrade.

getPlot(): The plot being upgraded.

getNewLevel(): The integer level the plot has just reached (e.g., 5).

📝 Example Listener

Here is how to listen to these events in your own plugin:

import com.aegisguard.api.events.PlotEnterEvent;
import com.aegisguard.api.events.PlotLevelUpEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyAegisListener implements Listener {

    @EventHandler
    public void onPlotEnter(PlotEnterEvent event) {
        // Example: Restrict entry to players with a permission
        if (!event.getPlayer().hasPermission("my.custom.entry")) {
            event.setCancelled(true);
            event.getPlayer().sendMessage("You need a pass to enter!");
        }
    }

    @EventHandler
    public void onLevelUp(PlotLevelUpEvent event) {
        // Example: Broadcast huge achievement
        if (event.getNewLevel() == 50) {
            Bukkit.broadcastMessage("⭐ " + event.getPlayer().getName() + " just reached MAX LEVEL on their plot!");
        }
    }
}

📌 Tips for Developers

AegisGuard is the source of truth for all land/permission checks.

Use plot.hasPermission() rather than recreating logic.

Explore the API with:

AegisGuard api = AegisGuard.plugin;