PolyGuard

Advanced polymorphic region protection engine. Define custom build protection, subregion plot hierarchies, interactive GUI flag management, and zero-lag spatial indexing.

Overview

PolyGuard solves the age-old problem of protecting circular, polygonal, or irregularly shaped builds. Instead of giant, rigid boxes that accidentally lock down surrounding terrain, PolyGuard allows precise region claiming with polymorphic protection flags, subregion plot inheritance, and instant zero-lag lookups.

Utilizing custom O(1) ChunkSpatialIndex mathematics and multi-threaded asynchronous saving, PolyGuard checks player actions instantly without blocking the main server thread, guaranteeing zero TPS lag even on heavily populated servers with thousands of regions.

Key Features

Polymorphic Flag System: Master flags like build and interact serve as fallback protection for specific block, container, and entity actions. Over 70+ flags covered.
GUI Flag Search: Built-in search tool (`/pg menu`) allows admins to type keywords in chat and instantly view matching flags with live click-toggles.
Subregion & Plot Inheritance: Link child plots to parent regions (`/pg setparent`). Plots automatically inherit parent region flags unless specifically overridden.
Interactive Chat Prompts: Click any String or Integer flag in the GUI to type values directly in chat, or type clear to reset to default.
Expanded Region Triggers: Execute console commands, sounds, custom titles, formatted messages, ambient potion effects, or teleports on region entry and exit.
Async Disk Persistence: Thread-safe background saving queues prevent main-thread tick spikes during frequent region and flag modifications.
Visual Terrain Borders: Terrain-hugging neon borders showcase claim boundaries to players in real-time.

Commands

Below is the complete list of PolyGuard commands (Permission node: polyguard.admin).

Command	Description
/pg create <id>	Create a new region from your PolyGuard wand or WorldEdit selection.
/pg delete <id>	Delete an existing protected region.
/pg wand	Obtain the PolyGuard selection wand tool.
/pg list [page]	List all registered regions in the current world with page navigation.
/pg menu [region]	Open the interactive GUI menu for category flag management and flag search.
/pg flags <region> [page]	View and click-toggle region flags directly in chat with interactive buttons.
/pg flag <region> <flag> <value...>	Set a specific flag value (supports multi-word strings; use `clear` to unset).
/pg setparent <child> [parent]	Link a subregion/plot to a parent region for flag inheritance (or omit parent to unlink).
/pg addmember <region> <player>	Add a player as a member of the specified region.
/pg removemember <region> <player>	Remove a player from the region members list.
/pg addowner <region> <player>	Add a player as an owner of the region.
/pg removeowner <region> <player>	Remove a player from the region owners list.
/pg highlight <region>	Highlight region boundaries with terrain-hugging visual particles.
/pg global [world]	Open the flag configuration GUI for the world's `__global__` region.
/pg copyglobal <fromWorld> <toWorld>	Copy global region flag settings from one world to another.

Triggers & Action Formats

PolyGuard allows executing custom actions when players enter (entry-actions) or leave (exit-actions) a region. Triggers can be configured via command or chat prompts.

command [console] <cmd> - Execute a command (e.g. command [console] give %player% diamond 1)

sound <sound_name> [vol] [pitch] - Play sound (e.g. sound entity.player.levelup 1.0 1.0)

title <title> | [subtitle] - Display title (e.g. title Welcome! | Enjoy your stay)

message <text> - Send MiniMessage formatted text (e.g. message <green>You entered Spawn!)

effect <potion> [amplifier] [seconds] - Grant potion effect (e.g. effect speed 1 10)

teleport <world> <x> <y> <z> - Teleport player (e.g. teleport world 100 64 200)

Advanced Integration & Performance Architecture

Welcome to the advanced guide for PolyGuard v1.1.0. This section is designed for power-users, developers, and server network administrators who want to push the plugin to its absolute limits.

1. Deep Dive into the Codebase

PolyGuard is built using an asynchronous event-driven architecture with zero-lag spatial indexing. Heavy data operations, NBT serialization, and file I/O are offloaded off the main server thread using background runTaskAsynchronously tasks and atomic lock state queues.

2. Subregion Inheritance Resolution

Child regions linked via /pg setparent dynamically pass unhandled flag lookups up to their parent region. Priority ordering ensures that child region flags override parent defaults while preventing cyclic inheritance loops.

3. Developer API & Event Hooks

You can include PolyGuard in your project dependencies to hook into region checks and custom protection events:

<dependency>
    <groupId>dev.polyguard</groupId>
    <artifactId>polyguard</artifactId>
    <version>1.1.0</version>
    <scope>provided</scope>
</dependency>

4. Extensive FAQ

Q: Does this plugin cause lag on large servers?
A: No! PolyGuard uses custom O(1) ChunkSpatialIndex algorithms and non-blocking async persistence to ensure zero tick spikes even with thousands of claims.
Q: How do I change default global region flags?
A: Use /pg global to open the global region GUI or edit regions/world_name.yml under the __global__ key.
Q: Is this compatible with Geyser and Bedrock players?
A: Yes, all custom inventories, chat prompts, and visual particle displays are fully compatible with Geyser/Floodgate Bedrock clients.

Check out these too...

PivotPoly

Scale, rotate, and manipulate complex block structures easily.

EventWarden

Host server-wide events with automated queuing, loadouts, and resets.

PaperStats

Track and visualize in-depth player statistics, playtimes, and metrics.