# 🏰🌍 BellLands — Chunk-Based Land Claiming & Protection

### *Claim your land, protect your builds, and travel with ease — all in one plugin.*

![Version](https://img.shields.io/badge/version-1.26.1.2-blue)
![API](https://img.shields.io/badge/Spigot | Paper-1.21+-green)
![Java](https://img.shields.io/badge/Java-21-orange)

---

## 📖 Overview

**BellLands** is a powerful chunk-based land claiming and protection system. Players can claim land, set granular protection flags, manage trusted players, create warps, and teleport to friends — all through clean commands and an intuitive GUI.

With Pl3xMap integration for web map visualization and zero required dependencies, BellLands is lightweight yet feature-complete. Perfect for survival servers, SMP, and any community where players need to protect what they've built.

---

## ✨ Features

🗺️ **Chunk-Based Land Claiming**
- Claim land in 16×16 chunk units
- Visual boundary indicators
- Configurable claim limits per player
- Intuitive nearby land map display

🛡️ **Granular Protection Flags**
- 🔨 Build — Block placement control
- ⛏️ Break — Block destruction control
- 🖱️ Interact — Container, door, and button access
- ⚔️ PvP — Toggle player combat
- 👾 Mob Spawn — Control hostile/passive mob spawning
- 💥 Explosions — TNT and creeper protection
- 🔥 Fire Spread — Prevent fire from destroying builds

👥 **Trust System**
- Add trusted players to your land
- Trusted players can build, break, and interact
- Easy add/remove management
- Per-land trust lists

📍 **Warp System**
- Set named warps within your lands
- Teleport to any of your warps instantly
- List and manage all your warps
- Share warp locations with friends

✈️ **TPA (Teleport Request) System**
- Send teleport requests to any player
- Accept or deny incoming requests
- Configurable timeout and cooldowns

📊 **Land Information Display**
- View owner, flags, and trusted players for any land
- At-a-glance status in the land info panel
- Admin info override for moderation

🗄️ **Persistent Storage**
- SQLite database for reliable data storage
- Efficient caching for performance
- Automatic data migration between versions

🗺️ **Pl3xMap Integration**
- Visualize all claimed lands on your web map
- Color-coded by owner
- Click for land details
- Real-time updates

🌍 **Multi-Language**
- Built-in English and Polish translations
- Fully customizable message files

---

## 📋 Dependencies

| Plugin | Type | Notes |
|--------|------|-------|
| *None* | — | BellLands has zero required dependencies! |
| LuckPerms | 📌 Optional | Permission management |
| Pl3xMap | 📌 Optional | Web map land visualization |

---

## 💻 Commands

### Land Management
| Command | Description |
|---------|-------------|
| `/land claim` | Claim the chunk you're standing in |
| `/land unclaim` | Unclaim the current chunk |
| `/land trust <player>` | Trust a player in your land |
| `/land untrust <player>` | Remove a player's trust |
| `/land flags` | Open the flag management GUI |
| `/land info` | Show information about the current land |
| `/land list` | List all your claimed lands |
| `/land map` | Display a map of nearby lands |

### Warp System
| Command | Description |
|---------|-------------|
| `/warp set <name>` | Set a warp at your current location |
| `/warp <name>` | Teleport to a warp |
| `/warp delete <name>` | Delete a warp |
| `/warp list` | List all your warps |

### Teleportation
| Command | Description |
|---------|-------------|
| `/tpa <player>` | Send a teleport request |
| `/tpaccept` | Accept an incoming teleport request |
| `/tpdeny` | Deny an incoming teleport request |

### Administration
| Command | Description |
|---------|-------------|
| `/belllands admin` | Admin management panel |
| `/belllands reload` | Reload plugin configuration |

---

## 🔐 Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `belllands.claim` | Claim and unclaim land | `true` |
| `belllands.trust` | Manage trusted players | `true` |
| `belllands.warp` | Use the warp system | `true` |
| `belllands.tpa` | Send and receive teleport requests | `true` |
| `belllands.admin` | Admin management commands | `op` |
| `belllands.bypass` | Bypass all land protection | `op` |
| `belllands.map` | View the nearby land map | `true` |

---

## ⚙️ Configuration Highlights

```yaml
# config.yml — Key settings

claiming:
max-claims-per-player: 10
claim-cost: 500
unclaim-refund: 250
visual-boundaries: true

protection:
default-flags:
build: false
break: false
interact: false
pvp: false
mob-spawn: true
explosions: false
fire-spread: false

warps:
max-warps-per-player: 5
warp-cost: 100
warp-delay: 3s

tpa:
timeout: 60s
cooldown: 30s

storage:
type: sqlite
file: data.db

pl3xmap:
enabled: true
layer-name: "Land Claims"
stroke-color: "#3388ff"
fill-color: "#3388ff33"

language: en
```

---

## 🚀 BellLandsPro — Premium Addon

Unlock advanced land management with **BellLandsPro**:

https://bellforge.pl/en/pluginy/belllands-pro/

| Feature | Description |
|---------|-------------|
| 👥 **Per-Group Limits** | Land and warp limits synced from BellLP via GroupSyncHandler |
| ⭐ **VIP Lifecycle Integration** | Instant limit recalculation when VIP status is granted or revoked |
| 🔄 **Override Reconciliation** | Seamless limit adjustments for both online and offline players |
| 📉 **Eviction/Downsizing Logic** | Graceful handling when limits decrease — notifications and managed unclaiming |
| ⚡ **Enhanced Caching** | Optimized performance with advanced caching for large servers |

> *BellLandsPro is a separate premium addon. Drop it alongside BellLands — it detects and extends the base plugin automatically.*

---

## 📸 Screenshots

*Coming soon — claim visualization, flag GUI, web map integration, and warp management.*

---

## 🔧 Installation

1. Download **BellLands** and place it in your `plugins/` folder
2. Restart your server — no dependencies required!
3. Customize settings in `plugins/BellLands/config.yml`
4. (Optional) Install **Pl3xMap** for web map visualization
5. `/belllands reload` — start claiming!

---

## 🆘 Support

- **Issues & Bugs:** [GitHub Issues](#)
- **Discord:** [https://discord.gg/6q7bnSYaR](#)
- **Wiki:** [Documentation](#)

---

## 📜 Changelog

See [CHANGELOG.md](#) for full version history.

---

BellLands — Your land. Your rules. Your world. 
Made with ❤️ for the Minecraft community.