# 🔑🔗 BellLP — The Central Hub of Your Plugin Ecosystem

### *Define your groups once. Watch them sync everywhere.*

![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)

---

## 🌟 What is BellLP?

> **Define your groups once. Watch them sync everywhere.**

BellLP is the **central group management and synchronization hub** for the entire Bell plugin ecosystem. It bridges your **LuckPerms** groups with gameplay mechanics across every connected plugin — from land limits and chat prefixes to market listings and warp quotas.

No more editing five configs when you add a new rank. No more permission mismatches. **One source of truth for all your groups.**

---

## ✨ Features

### 🏗️ Core Group Management
- 📋 **Central group registry** — define name, prefix, color, weight, and limits in one place
- 🔄 **Automatic LuckPerms sync** — permissions, weight, and inheritance pushed to LP instantly
- 📊 **Per-group properties** — max-lands, max-warps, market-limit, custom prefix, and more
- ⚖️ **Weight-based hierarchy** — groups automatically inherit from lower-weight groups

### 🔗 Ecosystem Integration
- 🏘️ **BellLandsPro** — land claim limits synced per group automatically
- 💬 **BellChat** — prefixes and colors updated in real time across chat and tablist
- 🛒 **BellTrade & BellMarket** — marketplace listing limits enforced per rank
- 🚪 **BellGate** — VIP lifecycle events (grant/revoke) propagated across all plugins

### 👑 VIP System
- 🎫 **VIP lifecycle hooks** — `onVipGranted` / `onVipRevoked` broadcast to all ecosystem handlers
- ⏰ **Instant propagation** — every connected plugin reacts immediately to VIP status changes
- 🔌 **GroupSyncHandler API** — third-party plugins can subscribe to group change events

### 🖥️ Admin Interface
- 🎨 **Full admin GUI** — intuitive click-through: group list → group editor → group members → player view
- ⚡ **Real-time updates** — GUI always reflects current state, no restart required
- 👤 **Player lookup** — instantly see which groups any player belongs to

### 🌍 Quality of Life
- 🌐 **Multi-language** — English and Polish built-in, hot-swappable at runtime
- 🔐 **Managed permissions** — `bell.*` plus configurable extras like `vipdeathchest.use`
- 📁 **Clean YAML config** — well-commented, human-readable, reload-friendly

---

## 📦 Dependencies

| Plugin | Required? | Purpose |
|--------|-----------|---------|
| **LuckPerms** | ✅ Required | Permission and group backend |
| BellGate | ⚙️ Optional | VIP lifecycle integration |
| BellChat | ⚙️ Optional | Prefix/color sync to chat & tablist |
| BellLands | ⚙️ Optional | Basic land limit awareness |
| BellLandsPro | ⚙️ Optional | Full land limit sync |
| BellTrade | ⚙️ Optional | Trade listing limits |
| BellMarket | ⚙️ Optional | Market listing limits |

---

## 💻 Commands

| Command | Description |
|---------|-------------|
| `/belllp admin` | Open the admin GUI |
| `/belllp player <name>` | View a player's groups |
| `/belllp sync` | Force a full ecosystem sync |
| `/belllp create <group>` | Create a new group |
| `/belllp delete <group>` | Delete an existing group |
| `/belllp add <player> <group>` | Add a player to a group |
| `/belllp remove <player> <group>` | Remove a player from a group |
| `/belllp members <group>` | List all members of a group |
| `/belllp reload` | Reload configuration files |
| `/belllp lang` | Toggle between EN/PL |

---

## 🔑 Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `belllp.admin` | Access admin GUI and all management commands | OP |
| `belllp.command` | Base command access (`/belllp`) | All |

---

## ⚙️ Configuration Highlights

```yaml
# groups.yml — Define all your groups in one place
groups:
vip:
prefix: "&6[VIP] "
color: "gold"
weight: 100
max-lands: 5
max-warps: 10
market-limit: 20
permissions:
- bell.vip
- vipdeathchest.use

mvp:
prefix: "&b[MVP] "
color: "aqua"
weight: 200
max-lands: 10
max-warps: 25
market-limit: 50
inherits: vip
```

```yaml
# config.yml — Core settings
sync:
auto-sync-on-join: true
sync-interval-minutes: 30
push-to-luckperms: true
push-to-ecosystem: true

language: EN # EN or PL, change at runtime with /belllp lang
```

---

## 🔮 Roadmap & Pro Stubs

Future **BellLPPro** features currently in development:

- 📈 **Track management** — promotion/demotion tracks with conditions
- 🎯 **Context overrides** — per-world or per-server group properties
- 📊 **BellCenter dashboard** — web panel for ecosystem overview
- 🧩 **Extended API** — more hooks for third-party integration

---

## 🔌 Developer API

BellLP exposes a `GroupSyncHandler` interface that any plugin can implement to react to group changes:

```java
public interface GroupSyncHandler {
void onGroupChanged(Player player, String group, ChangeType type);
void onVipGranted(Player player, String group);
void onVipRevoked(Player player, String group);
}
```

---

## 📥 Installation

1. Drop `BellLP.jar` into your `/plugins` folder
2. Ensure **LuckPerms** is installed and running
3. Start or restart your server
4. Edit `plugins/BellLP/groups.yml` to define your groups
5. Run `/belllp sync` to push everything to LuckPerms and connected plugins
6. Done! Groups are now managed centrally 🎉

---

## 🤝 Support & Links

- 💬 **Discord:** [Join our community](#) — fastest way to get help
- 📖 **Wiki:** [Full documentation](#)
- 🐛 **Issues:** [Report bugs](#)
- ⭐ **Rate this plugin** if it helps your server — it means a lot!

---

BellLP — One config to rule them all. 
Made with ❤️ for the Minecraft community.