LandClaimPlugin

DEVELOPMENT BUILDS

Development builds are automatically generated from the latest commits and may include unfinished features, breaking changes, or experimental code. These builds are not recommended for production use.

If you choose to run a dev build:

• Expect bugs, crashes, or incomplete functionality.
• Configs and data formats may change without notice.
• No guarantee of backward compatibility.

Use them only for testing, early access, or contributing feedback.
Download latest dev builds: GitHub Releases

---

✨ Features

Core Claiming

• Claim Profiles — Manage your land using claim profiles. Depending on server configuration, players can own a single profile or utilize the Multi-Profile System to manage multiple independent bases and quickly switch between them via an interactive GUI.
• Chunk-Based Claims — 16×16 block protection zones, simple and intuitive.
• Auto-Claim — Automatically claim chunks as you walk.
• Connected Claims — Optionally require claims to be adjacent (with diagonal support).
• Held Territory Map (Minimap) — Live 128×128 pixel radar map in hand/off-hand or Item Frames showing chunk boundaries, claim colors, and real-time player orientation.
• Interactive Selectors — Programmatically select online players via their heads for Trust, Member, and Ally management.
• Unstuck Command — A safe /claim unstuck feature that teleports trapped players to the nearest safe wilderness block.

Permission System

• 4-Tier Priority Chain — Owner > Role > Trusted > Visitor — the first matching tier decides
• Custom Roles — Create and configure custom roles (e.g., Member, CoOwner) with granular flag-based permissions
• Trusted Players — Grant individual players specific permission overrides
• Visitor Settings — Configure what non-members can do in your claims
• 25+ Permission Flags — Doors, trapdoors, containers, workstations, animals, vehicles, redstone, and more

Social Systems

• Member System — Invite players to join your claim, assign them roles, and manage access
• Ally System — Form mutual alliances between claims with configurable inter-claim permissions
• Trust System — Grant individual players per-player permission overrides
• Ban System — Hard-deny a player from entering or interacting with your claim. Banned players are physically pushed back at chunk boundaries and (if online at the moment of the ban) teleported outside. Survives server restarts.
• Warp System — Set named warps within your claims with custom icons and per-player limits
• Public Warps — Publish any of your warps to the server-wide public list. Other players can browse and teleport via /claim publicwarps.

Protection

• Block Protection — Prevent unauthorized breaking and placing
• Entity Protection — Protect animals, armor stands, and item frames
• Explosion Protection — Block TNT, creeper, and other explosion damage
• Interaction Protection — Control door, container, and workstation access
• Item Protection — Prevent unauthorized pickup and drop
• Piston Protection — Block pistons from pushing/pulling across claim borders
• PvP Protection — Disable PvP inside claims
• Vehicle Protection — Prevent unauthorized vehicle use and destruction
• Command Blocking — Block specific commands inside other players' claims
• Wilderness Protection — Opt-in wildernessProtection.enabled flag flips the default: players can only build/break inside claims, never in unclaimed chunks. Designed for clan/town-style servers.

Customization

• Owner Alias — Set a custom display name to replace your Minecraft username in UI elements, map hooks, and titles
• Claim Colors — Pick a custom hex color for your claim used on maps and borders
• Visualization Modes — Toggle between Display Entity or Particle-based boundary rendering
• Entry/Exit Titles — Custom MiniMessage-formatted titles shown when players enter or leave your claim
• Rename Claims — Change your claim's display name at any time
• Full Message Customization — All plugin messages are configurable via Okaeri Configs

🔌 Supported Integrations

LandClaimPlugin seamlessly hooks into various popular server plugins to provide an interconnected experience out-of-the-box.

🗺️ Web Map Plugins

Visualize claims directly on your server's web map! Claims are drawn as colored polygons matching the claim's chosen color, complete with owner and size information.

• BlueMap
• Dynmap
• Squaremap
• Pl3xMap

⚔️ Combat Tagger Plugins

Prevent players from abusing claim commands (like teleporting or abandoning claims) while actively in combat. The plugin automatically detects when a player is combat-tagged.

• DeluxeCombat
• PvPManager
• EternalCombat

🛡️ WorldGuard

Respect WorldGuard regions when players attempt to claim land.

• Volumetric Intersection Check: 100% accurate 3D boundary checking to prevent players from claiming over your spawn or protected areas.
• Gap Enforcement: Configurable required distance between claims and WorldGuard regions.
• Custom Flag Support: Apply the custom allow-land-claims WorldGuard state flag to regions (e.g., Wilderness/Warzone) to explicitly allow players to claim land inside them, overriding the gap and intersection protections!

🎮 Bedrock / Geyser Support

Bedrock players get a tailored UI when Geyser 2.x is installed. No hard Geyser dependency — the plugin uses reflection to detect the form API and falls back to the Java-only chat prompts if Geyser is missing.

• CustomForm text input for anvil-based prompts (rename, color, role name)
• ModalForm confirmation for destructive actions (abandon, unclaim all, ban)
• Visualization automatically switches to particle mode for Bedrock clients

Technical

• Cloud Command Framework — Async command execution with dedicated thread pools
• Modular Architecture — Separate command groups, listeners, and managers
• Eager Class Preloading — Eliminates first-execution lag spikes for GUI classes

---

🧩 Addons

The plugin's public API (LandClaimAPI) and event bus (ClaimCreateEvent,
ClaimDeleteEvent, PlayerEnterClaimEvent, PlayerLeaveClaimEvent) let
you build standalone addons in a sibling Maven project. Soft-depend on
LandClaimPlugin so the addon only loads when the parent is present.

Official Addons

Building Your Own

The API exposes:

• getClaimAt(...), getClaimsByOwner(UUID), getClaimByName(String), getClaimById(UUID)
• getAllClaimProfiles() — every loaded claim, for global iteration (tax, leaderboards, etc.)
• transferClaim(Player actor, UUID profileId, UUID newOwnerId) and unclaimAll(Player actor, UUID profileId) — programmatic ownership / claim management (the actor is either the new owner or has landclaim.admin)
• addBonusBlocks(UUID, int) and getBonusBlocks(UUID) — for paid-claim-block plugins
• isInCombat(Player) — hook for combat-taggers
• The full claim profile model — getOwnedChunks(), getRoles(), getTrustedPlayerFlags(), etc.

For addons that want to act on claim lifecycle, listen for
org.ayosynk.landClaimPlugin.api.event.* events.

---

📥 Installation

1. Download the latest release and drop LandClaimPlugin.jar into your plugins/ folder.
2. Restart your server.
3. Configure plugins/LandClaimPlugin/config.yml to your liking.

Requirements: Paper 26.2+ | Java 25+

---

💬 Commands

All commands use /claim (alias: /c) as the base.

General Commands

Menu Shortcuts

Jump directly to specific GUI panels without navigating through the main menu.

Management Commands

Members

Command	Description
/claim member invite <player>	Invite a player to join your claim
/claim member kick <player>	Remove a member from your claim
/claim member list	List all members and their roles
/claim accept <name>	Accept a pending member invitation
/claim deny <name>	Deny a pending member invitation

Trust

Command	Description
/claim trust invite <player>	Send a trust invitation to a player
/claim trust accept	Accept a pending trust invitation
/claim trust deny	Deny a pending trust invitation
/claim trust remove <player>	Remove a trusted player
/claim trust list	List all trusted players and their flags

Allies

Command	Description
/claim ally invite <name>	Send an alliance request to another claim
/claim ally accept <name>	Accept an alliance request
/claim ally deny <name>	Deny an alliance request
/claim ally remove <name>	Remove an existing alliance

Warps & Admin

Command	Description
`/claim setwarp [public	private]`
/claim delwarp <name>	Delete a warp
/claim warp <name> [warpName]	Teleport to your warp, or a public warp (/claim warp <name> or /claim warp <owner>:<name>)
/claim publicwarps	Open the server-wide public warps browser GUI
/claim warps	Open the active claim's warp management GUI
/claim admin check	View detailed claim info (owner UUID, profile name)
/claim admin unclaim	Force-unclaim the chunk you're standing in
/claim admin edit <player>	Open any player's claim management GUI
/claim admin add chunk <player> <amount>	Add bonus claim chunks to a player's limit
/claim admin setalias <claim> <alias>	Set or reset an owner's custom alias
/claim admin trust list <owner>	List players trusted by this owner
/claim admin trust who <player>	List claims where this player is trusted

---

🔐 Permissions

Permission	Description	Default
landclaim.*	All LandClaim permissions	false
landclaim.claim	Basic claiming ability	true
landclaim.minimap	Access to the held Territory Map	true
landclaim.auto	Use auto-claim mode	true
landclaim.admin	Admin commands & bypass all protection	op
landclaim.update.notify	Receive update notifications on join	op
landclaim.limit.<n>	Override the chunk claim limit (e.g., landclaim.limit.50)	false
landclaim.list	List claims	true
landclaim.warps.limit.<n>	Override the warps limit (e.g., landclaim.warps.limit.10)	false
landclaim.createrole.<n>	Override the max number of custom roles	false

---

📋 Disclosures & Transparency

In compliance with platform guidelines and Modrinth disclosure policies:

🤖 AI Assistance Disclosure

This project uses AI assistance (LLMs) for code drafting, refactoring, optimization, and documentation under the direct design, review, and testing of the maintainers. All game logic, security gates, and database transactions are human-architected and audited.

🌐 External Network Calls & Telemetry

LandClaimPlugin communicates with the following external endpoints:

• Modrinth API (https://api.modrinth.com): Queries the public Modrinth v2 API on startup to check for new versions. Sends only the standard User-Agent header (LandClaimPlugin/{version}). No player or server-identifying data is shared. Opt-out: set updateChecker.enabled: false in config.yml.
• bStats Analytics (https://bstats.org): Collects anonymous usage metrics (Java version, server software, online player count) via bStats. No personally identifiable information is collected. Opt-out: set enabled: false in plugins/bStats/config.yml.
• Redis & Remote MySQL (Optional): Connects only to user-configured endpoints for cross-server pub/sub synchronization or centralized database storage.

---

🔗 Quick Links