ClaimChunks

⬡ What is ClaimChunks?

ClaimChunks is a chunk-based land protection plugin for Spigot 1.21+ servers. It allows players to claim chunks with a single command and manage them through an interactive GUI menu with pagination, teleportation, visual map and trust system.

Designed to be lightweight, intuitive and highly configurable, with no required external dependencies.

⬡ Key Features

• Instant Claiming — Claim the chunk you're standing on with /claim. No tools, no hassle.
• Interactive GUI — Visual menu with pagination (28 claims per page), claim details, release confirmation and trust management.
• Chat Claim Map — 11×11 chunk map with color-coded types (yours, trusted, other, free) and interactive hover tooltips with info on mouseover.
• Particle Borders — Chunk border visualization with DUST particles using configurable RGB colors. Golden corners, color-coded borders based on relationship.
• Trust System — Trust players with /trust to grant them access to all your claims. Visual management from the GUI with real player heads.
• Full Protection — 10+ individually toggleable protection options: blocks, interaction, PvP, explosions, pistons, liquid flow, enderpearls, fire and more.
• Action Bar — Elegant action bar messages when entering/leaving claims, keeping the chat clean.
• Auto-Save — Async JSON persistence with automatic saving every 5 minutes.
• Multi-World Support — Works in Overworld, Nether and End (configurable). World blacklist available.

⬡ Commands

┌──────────────────────────────────────────────────────────┐
│  Command              │  Description                     │
├──────────────────────────────────────────────────────────┤
│  /claim               │  Claim the current chunk         │
│  /unclaim             │  Unclaim the current chunk       │
│  /claims              │  Open the claims GUI menu        │
│  /claimmap            │  Show visual map in chat         │
│  /claiminfo           │  Info about the current claim    │
│  /trust <player>      │  Trust a player in your claims   │
│  /untrust <player>    │  Remove trust from a player      │
│  /claimadmin          │  Administration panel            │
└──────────────────────────────────────────────────────────┘

Admin Subcommands:

• /claimadmin reload — Hot-reload configuration
• /claimadmin delete — Force-delete the claim at current chunk
• /claimadmin setlimit <n> — Change the claim limit per player
• /claimadmin info — System statistics
• /claimadmin lookup <player> — View a player's claims

⬡ Permissions

┌───────────────────────────────────────────────────────────────┐
│  Permission              │  Description          │  Default  │
├───────────────────────────────────────────────────────────────┤
│  claimchunks.claim       │  Use the claim system  │  true    │
│  claimchunks.admin       │  Admin commands        │  op      │
│  claimchunks.bypass      │  Bypass protections    │  op      │
│  claimchunks.unlimited   │  Unlimited claims      │  op      │
└───────────────────────────────────────────────────────────────┘

⬡ Protection System

Each option can be individually enabled/disabled in config.yml:

• ✦ Block breaking and placing
• ✦ Interaction with chests, doors, buttons, levers, flower pots, bells, cauldrons, beds, etc.
• ✦ PvP inside claims
• ✦ Explosions (TNT, Creepers, Withers, Fireballs)
• ✦ Pistons pushing/pulling across claim borders
• ✦ Lava and water flow into other claims
• ✦ Fire spread and block burning
• ✦ Enderpearl and Chorus Fruit into protected claims
• ✦ Entity damage (animals, villagers, armor stands)
• ✦ Item usage (buckets, flint & steel, spawn eggs)

⬡ Interactive GUI

• Main Menu — Overview of all your claims with world-based icons (grass, netherrack, end stone). Automatic pagination for 28+ claims.
• Claim Detail — Coordinates, world, time since claimed, list of trusted players with online/offline status.
• Quick Actions — Teleport to the chunk center, visualize borders with particles, unclaim with confirmation.
• Trust Menu — Real player heads of trusted players with click-to-remove.
• Safe Confirmation — A confirmation menu is shown before unclaiming to prevent accidents.

⬡ Particle Visualization

• ■ Green — Your claim
• ■ Red — Another player's claim
• ■ Blue — Claim where you're trusted
• ■ White — Unclaimed chunk
• ■ Gold — Chunk corners (tall columns)

All colors are fully customizable with RGB values (0-255) from the configuration.

⬡ Configuration

# Maximum chunks per player
max-claims-per-player: 10

# Cost to claim a chunk (0 = free)
claim-cost: 0

# Allow claims in Nether and End
allow-nether-claims: true
allow-end-claims: true

# Disabled worlds
disabled-worlds:
  - "world_example_disabled"

# DUST particle colors (RGB 0-255)
particles:
  own-claim:    { r: 0, g: 220, b: 80 }
  other-claim:  { r: 220, g: 40, b: 40 }
  trusted-claim: { r: 60, g: 140, b: 255 }
  corner:       { r: 255, g: 200, b: 0 }

show-particles-on-enter: true
particle-duration: 5
particle-interval: 5

# Protection (each option individually)
protection:
  block-break: true
  block-place: true
  block-interact: true
  pvp: true
  explosions: true
  liquid-flow: true
  pistons: true
  mob-spawning: false
  entity-damage: true
  item-use: true

# All messages are editable with support
# for & color codes and hex &#RRGGBB
messages:
  prefix: "&8[&a⬡ Claims&8] &7"
  # ... (all fully editable)

⬡ Requirements

• Server: Spigot or Paper 1.21+
• Java: 21 or higher
• Dependencies: None (fully standalone)

⬡ Installation

1. Download ClaimChunks-1.0.0.jar
2. Place it in your server's plugins/ folder
3. Restart or reload the server
4. Edit plugins/ClaimChunks/config.yml to your liking
5. Use /claimadmin reload to apply changes without restarting

⬡ Technical Details

• Persistence: JSON with Gson (bundled in Spigot, no extra dependencies)
• Thread-safe: ConcurrentHashMap for claim storage
• Performance: Chunk change detection using bit arithmetic (no chunk loading), distance calculated without sqrt, anti-spam message cooldowns
• Auto-save: Automatic async saving every 5 minutes
• Cleanup: In-memory data automatically cleaned up on disconnect