BellLP

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

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


---

## 🌟 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);
}
```

Register your handler and BellLP will keep your plugin in the loop whenever groups change across the ecosystem.

---

## 📥 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!

---

<p align="center">
  <b>BellLP</b> — One config to rule them all.<br>
  Made with ❤️ for the Minecraft community.
</p>