UltimateLandClaim

** UltimateLandClaim

The Ultimate Dual-Mode Land Protection Plugin

Version	Minecraft	Java	API
1.0.0	1.21.1+	21+	Paper

🎯 Executive Summary
UltimateLandClaim is a sophisticated, dual-mode land protection plugin for Minecraft Paper servers running version 1.21.1+. It uniquely combines the best features of popular claiming systems (Towny, Factions, GriefPrevention) into a single, mode-switchable plugin with universal data storage.

Why Choose UltimateLandClaim?

Feature	UltimateLandClaim	Other Plugins
Dual Modes	✅ CHUNK + FREE	❌ Single mode only
Mode Switching	✅ Without data loss	❌ Requires migration
Modern API	✅ Paper 1.21.1	⚠️ Often outdated
Visuals	✅ Adventure API & RGB	❌ Legacy chat
WorldGuard	✅ Built-in Integration	⚠️ Limited or none
Trust Levels	✅ 4 Hierarchical Levels	⚠️ 1-3 levels

---

🔑 Key Features

🏗️ Dual-Mode Claiming System

• CHUNK Mode: Instant 16x16 chunk claiming (Like Towny/Factions).
• FREE Mode: Two-click custom rectangle selection (Like GriefPrevention).
• Hot-Swappable: Change modes via config reload without losing any data.
• Universal Storage: Uses a universal BoundingBox system.

🛡️ Advanced Protection

• Block Protection: Prevents unauthorized breaking/placing.
• Container Security: Chests, furnaces, and hoppers are locked.
• Interaction Control: Protects buttons, levers, doors, and gates.
• PvP Management: Toggle combat inside claims.
• Explosion Protection: Prevent Creeper/TNT damage.

💰 Playtime-Based Economy

• Claim Blocks: Players earn blocks by playing on the server.
• Accrual: Configurable earnings per minute.
• Starting Balance: Set a default amount for new players.
• Refunds: 100% refund of claim blocks when a claim is deleted.

🎨 Visual Feedback

• Particle Boundaries: Hold a stick to see claim borders.
• Real-time Updates: Particles follow player movement.
• Optimized: Distance-based rendering to prevent lag.

---

🗺️ Claim Modes Explained

You can switch between these modes in config.yml.

📦 CHUNK Mode (Grid-Based)
Best for: Faction servers, town systems, organized communities.

• How it works: Right-click once with a Golden Shovel.
• Result: The entire 16x16 chunk is claimed instantly.
• Cost: Fixed cost (Default: 256 claim blocks).
• Alignment: Perfectly aligns with Minecraft chunk borders.

🎯 FREE Mode (Freeform Selection)
Best for: Survival servers, creative plots, custom regions.

• How it works: Click two corners with a Golden Shovel.
• Result: A custom rectangle is created between the points.
• Cost: Dynamic cost based on area (Width × Length).
• Precision: Block-level accuracy for custom builds.

---

👥 Trust System

The trust system is hierarchical. Each level includes all permissions from the levels below it.

1. MANAGER (Level 4) - Full Control
   • Can trust/untrust other players.
   • Includes all BUILD permissions.
2. BUILD (Level 3) - Construction
   • Can break and place blocks.
   • Includes all CONTAINER permissions.
3. CONTAINER (Level 2) - Storage Access
   • Can open chests, barrels, and furnaces.
   • Includes all ACCESS permissions.
4. ACCESS (Level 1) - Basic Interaction
   • Can use buttons, levers, and doors.

Example:
/claim trust Steve BUILD - Steve can build, open chests, and use doors, but cannot add other members.

---

📝 Commands Reference

🏗️ Claiming Commands

Command	Description	Permission
/claim	Show claiming instructions	ultimatelandclaim.claim
/claim auto	Toggle auto-claim (Chunk mode only)	ultimatelandclaim.claim
/claim delete	Delete the claim you are standing in	ultimatelandclaim.claim
/unstuck	Teleport out of a claim if trapped	ultimatelandclaim.unstuck

👥 Trust Commands

Command	Usage
Grant Trust	/claim trust <player> <level>
Remove Trust	/claim untrust <player>

📊 Info & Admin

Command	Description	Permission
/claim info	View owner and trusted players	ultimatelandclaim.claim
/claim list	Check your claim block balance	ultimatelandclaim.claim
/uls reload	Reload configuration	ultimatelandclaim.admin

---

🔐 Permissions

Permission	Description	Default
ultimatelandclaim.claim	Create/Manage claims	True (All)
ultimatelandclaim.unstuck	Use /unstuck	True (All)
ultimatelandclaim.admin	Admin commands	OP
ultimatelandclaim.bypass	Bypass all protections	OP
ultimatelandclaim.*	Wildcard for everything	OP

---

⚙️ Configuration

Standard Configuration

 Choose your mode: CHUNK or FREE
claim-mode: CHUNK

economy:
  starting-claim-blocks: 100
  claim-blocks-per-minute: 1
  max-claim-blocks: 10000

protection:
  allow-pvp: false
  allow-explosions: false
  prevent-mob-damage: true

WorldGuard Integration
This plugin can automatically detect WorldGuard regions and prevent players from claiming over them.

worldguard:
  enabled: true
  prevent-claiming-in-regions: true

---

📥 Installation

1. Download UltimateLandClaim-1.0.0.jar.
2. Place it in your server's /plugins/ folder.
3. Restart the server.
4. Edit config.yml to select CHUNK or FREE mode.
5. Run /uls reload.

Requirements:

• Server: Paper 1.21.1+ (Spigot is not supported due to modern API usage).
• Java: Java 21 or higher.

---

❓ FAQ

Q: Can I switch modes after players have made claims?

A: Yes! Switching modes does NOT delete claims. Claims made in "Free" mode will stay as they are even if you switch to "Chunk" mode, and vice versa.

Q: How do players get a Golden Shovel?

A: You can use any Golden Shovel (crafted or given). The plugin detects the item type.

Q: Does this work with MySQL?

A: Not in v1.0. Data is stored in local YAML files (claims.yml). MySQL support is planned for future updates.

Q: Is WorldGuard required?

A: No, it is optional. If installed, ULC will simply hook into it for extra protection.

---

Made with ❤️ for the Minecraft Community**