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**