Skip to content

API.md

Latest commit

 

History

History
129 lines (88 loc) · 5.19 KB

API.md

File metadata and controls

129 lines (88 loc) · 5.19 KB
Raw

⚙️ WorldGuardNeo — Public API

Programmatic access to regions, events, and custom flag registration.

English · Русский

🏠 Home · 🔨 Building · 🔑 Permissions · 🚩 Flags · ⚙️ API · 🧩 KubeJS · 📋 Changelog

Contents

  1. Getting the API
  2. Queries — WorldGuardNeoAPI
  3. Events
  4. Registering custom flags

Getting the API

WorldGuardNeo exposes a static facade at dev.thefather007.worldguardneo.api.WorldGuardNeoAPI. Make WorldGuardNeo a soft/optional dependency of your mod and guard your hooks behind a presence check:

if (ModList.get().isLoaded("worldguardneo")
        && WorldGuardNeoAPI.isAvailable()) {
    // safe to call the API
}

Queries — WorldGuardNeoAPI

All methods are static, null-safe, and intended for use on the server thread.

Finding regions

Optional<ProtectedRegion> r = WorldGuardNeoAPI.getRegionAt(level, pos);
List<ProtectedRegion> rs    = WorldGuardNeoAPI.getRegionsAt(level, pos);
Optional<ProtectedRegion> byId = WorldGuardNeoAPI.getRegion(level, "spawn");
Collection<ProtectedRegion> all = WorldGuardNeoAPI.getRegions(level);
List<ProtectedRegion> mine  = WorldGuardNeoAPI.getOwnedRegions(level, player.getUUID());

Permission checks

boolean canBuild        = WorldGuardNeoAPI.canBuild(player, pos);
boolean canPlace        = WorldGuardNeoAPI.canPlace(player, pos);
boolean canInteract     = WorldGuardNeoAPI.canInteract(player, pos);
boolean canAccessChests = WorldGuardNeoAPI.canAccessChests(player, pos);
boolean canPvP          = WorldGuardNeoAPI.canPvP(player, pos);
boolean isAdmin         = WorldGuardNeoAPI.hasBypass(player);

These mirror the mod's own event handlers exactly, including the implicit membership protection: inside a claimed region with no explicit flags, strangers get false while owners/members get true — the same verdict the break/place/interact handlers enforce.

Arbitrary flags

boolean allowed = WorldGuardNeoAPI.queryFlag(level, Flags.PVP, player.getUUID(), pos);
Optional<String>  msg  = WorldGuardNeoAPI.queryValue(level, Flags.GREETING, null, pos);
Optional<Integer> heal = WorldGuardNeoAPI.queryValue(level, Flags.HEAL_AMOUNT, null, pos);

Owner / member

boolean isOwner  = WorldGuardNeoAPI.isOwner(r, uuid);
boolean isMember = WorldGuardNeoAPI.isMember(r, uuid);  // includes owners

Events

All events are posted on the NeoForge game event bus (NeoForge.EVENT_BUS). Subscribe with @SubscribeEvent.

RegionEnterEvent

Fired when a player crosses into a region. Carries the player, the region, and the level. Not cancelable (movement has already happened) — use it for notifications, effects, logging.

@SubscribeEvent
public void onRegionEnter(RegionEnterEvent event) {
    ServerPlayer player = event.getPlayer();
    ProtectedRegion region = event.getRegion();
    // ...
}

RegionLeaveEvent

The mirror of RegionEnterEvent, fired when a player leaves a region.

RegionFlagDeniedEvent

Fired when a region flag denies an action — covering block break, block place, interact, container (chest-access), and PvP denials (purely environmental denials with no entity actor — fire/fluid spread, dispensers — do not fire it). Lets you audit denials or override them: the event implements ICancellableEvent, so calling setCanceled(true) permits the action despite the region denial. Carries the region, the flag involved, the acting entity (getActor(), nullable), and a short reason string (e.g. "block-break", "block-place", "interact", "container", "pvp"). It does not carry a position.

RegionModifyEvent

Fired when a region is created, redefined, or deleted. Carries the level, region, a ModifyType (CREATED / UPDATED / DELETED), and the actor (may be null for programmatic changes).

@SubscribeEvent
public void onRegionModify(RegionModifyEvent event) {
    if (event.getType() == RegionModifyEvent.ModifyType.CREATED) {
        // a new region was claimed
    }
}

Registering custom flags

Other mods can register their own flags during setup. Register early (before regions load) so flags resolve from storage. Use the same flag types WorldGuardNeo uses (StateFlag, StringFlag, IntegerFlag, DoubleFlag, BooleanFlag, SetFlag) and add a matching flag.<name>.desc lang entry so the flag shows a description in-game.

Flag names must match [a-z][a-z0-9-]* (lowercase, digits, dashes — no dots), so prefix with your mod name dash-style to avoid collisions:

// during common setup; second StateFlag argument is the default (true = allow when unset)
StateFlag MY_FLAG = new StateFlag("mymod-no-magic", true);
WorldGuardNeoAPI.registerFlag(MY_FLAG);

Once registered, the flag is settable via /rg flag <id> my-custom-flag <value> and queryable through queryFlag / queryValue exactly like a built-in flag.

License

Released under the GNU General Public License v3.0 or later. See LICENSE for the full text.