Developer API

Overview

Each API is exposed as a singleton accessed via a static getInstance() method. Events follow the Fabric event system (client & server 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.

Client Mod API

The client API is available only on the Fabric client mod. Import it from me.marquinho.protectedareaclient.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 mod API is available only on the Fabric server mod. Import it from me.marquinho.protectedareaserver.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
Collection<ServerPlayerEntity> players = api.getPlayersInArea("shop");
System.out.println("Players in shop: " + players.size());

// 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()));

// 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.