Developer API

Overview

Each API is exposed as a singleton accessed via a static getInstance() method. Events follow the Fabric event system (Fabric mod) or the Bukkit event system (Paper plugin). All three APIs are read/write — you can both query the current state and mutate areas at runtime. Since 1.0.8 the client and server mods are a single Fabric mod, so its two APIs ship in the same JAR.

Migrating to 1.0.8

Version 1.0.8 merged the former ProtectedAreaServer and ProtectedAreaClient mods into a single Fabric mod. No method signature changed — every call keeps the same name, parameters and return type. Only the package names and the mod id moved, so migrating is a find-and-replace plus a recompile.

Update your dependency declaration as well:

"depends": {
  "protectedarea": ">=1.0.8"
}

If you previously depended on both mods, they are now a single entry.

Client Mod API

The client API is available only on the client side of the Fabric mod. Import it from me.marquinho.protectedarea.client.api.

ProtectedAreaClientAPI

Get the singleton instance:

ProtectedAreaClientAPI api = ProtectedAreaClientAPI.getInstance();

Query methods

Example

// Check if the local player is in a specific area
ProtectedAreaClientAPI api = ProtectedAreaClientAPI.getInstance();

if (api.isPlayerInside("spawn")) {
    // player is inside the "spawn" area
}

// Get all areas at a given position
Collection<ProtectedArea> areas = api.getAreasAt(100, 64, 200, "world", "minecraft:overworld");
for (ProtectedArea area : areas) {
    System.out.println("Area at position: " + area.getId());
}

Client Events

Events are defined in ProtectedAreaEvents and follow the standard Fabric event pattern. Register listeners during mod initialization.

Example

// In your ClientModInitializer
ProtectedAreaEvents.PLAYER_ENTERED_AREA.register(area -> {
    MinecraftClient.getInstance().player.sendMessage(
        Text.literal("You entered: " + area.getId()), true
    );
});

ProtectedAreaEvents.PLAYER_CROSSED_FLAT.register((area, toPositiveSide) -> {
    String side = toPositiveSide ? "positive" : "negative";
    System.out.println("Crossed flat area " + area.getId() + " to " + side + " side");
});

ProtectedAreaEvents.AREA_ADDED.register(area -> {
    System.out.println("Area received from server: " + area.getId());
});

ProtectedAreaEvents.AREAS_CLEARED.register(() -> {
    System.out.println("All areas cleared (disconnected or server reset)");
});

Server Mod API

The server API is available only on the server side of the Fabric mod. Import it from me.marquinho.protectedarea.api.

ProtectedAreaServerAPI

Get the singleton instance:

ProtectedAreaServerAPI api = ProtectedAreaServerAPI.getInstance();

Query methods

Action methods

Example

ProtectedAreaServerAPI api = ProtectedAreaServerAPI.getInstance();

// Create a cube area programmatically
api.createArea("shop", 100, 60, 200, 120, 80, 220, "minecraft:overworld");

// Apply rules
api.addRule("shop", AreaRule.NO_PVP);
api.addRule("shop", AreaRule.NO_DROP);

// Give a specific player an exception to NO_DROP
api.addException("shop", "Steve", AreaRule.NO_DROP);

// Assign a skybox
api.setSkybox("shop", "marketplace");

// Set a player limit of 10 and block entry when full
api.setLimit("shop", 10);
api.setLimitBlocked("shop", true);

// Check players inside
int count = api.getPlayersInArea("shop");
System.out.println("Players in shop: " + count);

List<ServerPlayerEntity> players = api.getPlayersListInArea("shop");
for (ServerPlayerEntity p : players) {
    System.out.println("  - " + p.getName().getString());
}

// Remove all areas in a folder at once
int removed = api.removeAreasByFolder("events/");
System.out.println("Removed " + removed + " areas from events/");

Server Events

Events are defined in ProtectedAreaServerEvents. Register listeners in your ModInitializer.

Example

// In your ModInitializer
ProtectedAreaServerEvents.PLAYER_ENTERED_AREA.register((player, area) -> {
    player.sendMessage(Text.literal("Welcome to " + area.getId() + "!"), false);
});

ProtectedAreaServerEvents.PLAYER_LEFT_AREA.register((player, area) -> {
    player.sendMessage(Text.literal("You left " + area.getId()), false);
});

ProtectedAreaServerEvents.PLAYER_CROSSED_FLAT.register((player, area, toPositiveSide) -> {
    if (toPositiveSide) {
        player.sendMessage(Text.literal("Entered restricted zone"), false);
    }
});

ProtectedAreaServerEvents.RULE_BLOCKED.register((player, area, rule) -> {
    // Log every blocked action
    System.out.println(player.getName().getString() + " was blocked by " + rule + " in " + area.getId());
});

ProtectedAreaServerEvents.AREA_CREATED.register(area -> {
    System.out.println("New area created: " + area.getId());
});

Plugin API

The Paper plugin API mirrors the server mod API but uses standard Bukkit/Paper types. Import it from me.marquinho.protectedAreaPlugin.api.

ProtectedAreaPluginAPI

Get the singleton instance:

ProtectedAreaPluginAPI api = ProtectedAreaPluginAPI.getInstance();

Query methods

Action methods

The action methods are identical to the Server Mod API but accept org.bukkit.entity.Player instead of ServerPlayerEntity:

Example

// In your JavaPlugin
ProtectedAreaPluginAPI api = ProtectedAreaPluginAPI.getInstance();

// Create an area using Bukkit Location helpers
api.createArea("pvp-arena", -50, 60, -50, 50, 100, 50, "minecraft:overworld");
api.addRule("pvp-arena", AreaRule.NO_ENTRY);

// Grant VIP players an exception
api.addException("pvp-arena", "VIPPlayer", AreaRule.NO_ENTRY);

// Query at a Bukkit location
Location loc = player.getLocation();
Optional<ProtectedArea> area = api.getAreaAt(loc);
area.ifPresent(a -> player.sendMessage("You are in: " + a.getId()));

// Check how many players are in an area
int count = api.getPlayersInArea("pvp-arena");
System.out.println("Players in arena: " + count);

// Get the actual list of players
List<Player> players = api.getPlayersListInArea("pvp-arena");
for (Player p : players) {
    p.sendMessage("The arena is starting!");
}

// Remove all areas in a folder at once
int removed = api.removeAreasByFolder("events/");
System.out.println("Removed " + removed + " areas from events/");

Bukkit Events

The plugin fires standard Bukkit events. Listen to them with @EventHandler on a class that implements Listener.

Example

public class AreaListener implements Listener {

    @EventHandler
    public void onEnter(PlayerEnteredAreaEvent event) {
        event.getPlayer().sendMessage("Welcome to " + event.getArea().getId() + "!");
    }

    @EventHandler
    public void onLeave(PlayerLeftAreaEvent event) {
        event.getPlayer().sendMessage("You left " + event.getArea().getId());
    }

    @EventHandler
    public void onCrossFlat(PlayerCrossedFlatEvent event) {
        String side = event.isToPositiveSide() ? "positive" : "negative";
        event.getPlayer().sendMessage("Crossed into " + side + " side of " + event.getArea().getId());
    }

    @EventHandler
    public void onRuleBlocked(AreaRuleBlockedEvent event) {
        event.getPlayer().sendMessage(
            ChatColor.RED + "Action blocked by rule: " + event.getRule().name()
        );
    }

    @EventHandler
    public void onAdvancedRuleBlocked(AreaAdvancedRuleBlockedEvent event) {
        event.getPlayer().sendMessage(
            ChatColor.RED + "Advanced rule blocked: " + event.getRuleType() + " on " + event.getTargetId()
        );
    }
}

Register the listener in your plugin's onEnable:

@Override
public void onEnable() {
    getServer().getPluginManager().registerEvents(new AreaListener(), this);
}

Enums Reference

AreaRule

Used for basic rules and exceptions. Shared across all three APIs.

AdvancedRuleType

Used for fine-grained per-block or per-entity rules.