# 💬🎙️ BellChat — Multi-Channel Chat, Ranks & Moderation

### *The complete chat system — channels, rank prefixes, moderation, tablist, and more.*

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

---

## 💬 What is BellChat?

> **Your chat, your rules — channels, ranks, moderation, all in one.**

BellChat is a **feature-rich multi-channel chat system** with rank-based formatting, a custom tablist, powerful moderation tools, and smart AFK detection. It integrates seamlessly with **BellLP** for instant prefix and color updates when groups change, and reacts to VIP lifecycle events for real-time visual upgrades.

From cozy SMPs to bustling networks — BellChat gives your server a polished, professional chat experience.

---

## ✨ Features

### 📢 Multi-Channel Chat
- 🌍 **Global channel** — server-wide communication, the default
- 📍 **Local channel** — distance-based chat for nearby players
- 🛡️ **Admin channel** — staff-only communication
- 🛒 **Trade channel** — dedicated space for trading
- ❓ **Help channel** — player questions and support
- ➕ **Custom channels** — create unlimited channels with custom rules

### 🎨 Rank-Based Formatting
- 👑 **LuckPerms integration** — automatic prefix and color from rank
- 🏷️ **Custom format per group** — fully configurable chat format strings
- 🔄 **BellLP sync** — prefix and tablist update instantly on group change
- 🎯 **VIP instant update** — visual changes apply the moment VIP is granted

### 📊 Custom Tablist
- 🏆 **Rank display** — group name and color in the tab menu
- ❤️ **Health indicator** — see player health at a glance
- 📶 **Ping display** — connection quality visible
- 🔄 **Real-time sync** — tablist refreshes on rank/VIP changes

### ✉️ Private Messaging
- 💌 `/msg` — send private messages to any player
- 🔁 `/r` — quick reply to the last message
- 🕵️ **Spy mode** — admins can monitor private conversations
- 🔔 **Sound notifications** — optional ping on new messages

### 💤 AFK System
- 🕐 **Auto-detect** — players marked AFK after inactivity
- 💬 **Custom reasons** — `/afk Building in creative!`
- 👢 **Auto-kick option** — configurable kick after extended AFK
- 📊 **Tablist indicator** — AFK status shown in player list

### 🔨 Chat Moderation
- 🔇 **Mute system** — permanent and temporary mutes with reasons
- 🐌 **Slowmode** — configurable cooldown between messages per channel
- 🚫 **Word filter** — block profanity and unwanted words
- 🤖 **Anti-spam** — duplicate message and flood detection
- 📢 **Broadcast system** — styled server-wide announcements

### 🌍 Integration & Extras
- 🔌 **PlaceholderAPI** — use BellChat placeholders in other plugins
- 🌐 **Multi-language** — English and Polish built-in
- 📁 **Hot-reload** — change any config, reload without restart

---

## 📦 Dependencies

| Plugin | Required? | Purpose |
|--------|-----------|---------|
| *None* | — | BellChat works standalone! |
| LuckPerms | ⚙️ Optional | Rank-based chat formatting |
| PlaceholderAPI | ⚙️ Optional | Cross-plugin placeholder support |
| BellLP | ⚙️ Optional | Instant prefix/color sync on group changes |

---

## 💻 Commands

### 💬 Player Commands

| Command | Description |
|---------|-------------|
| `/chat [channel]` | Switch to a chat channel |
| `/msg <player> <message>` | Send a private message |
| `/r <message>` | Reply to last private message |
| `/afk [reason]` | Toggle AFK status with optional reason |

### 🔨 Admin / Moderation

| Command | Description |
|---------|-------------|
| `/bellchat mute <player> [duration]` | Mute a player (optionally timed) |
| `/bellchat unmute <player>` | Unmute a player |
| `/bellchat slowmode <seconds>` | Set slowmode cooldown (0 to disable) |
| `/bellchat broadcast <message>` | Send a formatted server broadcast |
| `/bellchat reload` | Reload all configuration files |

---

## 🔑 Permissions

| Permission | Description | Default |
|------------|-------------|---------|
| `bellchat.admin` | Admin commands (mute, broadcast, reload) | OP |
| `bellchat.color` | Use color codes (`&a`, `&b`, etc.) in chat | false |
| `bellchat.channel.<name>` | Access a specific channel (e.g., `bellchat.channel.admin`) | varies |
| `bellchat.spy` | Spy on private messages | OP |
| `bellchat.bypass.slowmode` | Bypass slowmode restrictions | OP |
| `bellchat.bypass.filter` | Bypass the word filter | OP |

---

## ⚙️ Configuration Highlights

```yaml
# chat.yml — Channel configuration
channels:
global:
prefix: "&7[&fG&7]"
format: "{prefix} {player}&7: &f{message}"
default: true

local:
prefix: "&7[&eL&7]"
format: "{prefix} {player}&7: &f{message}"
radius: 100

admin:
prefix: "&7[&cA&7]"
format: "{prefix} &c{player}&7: &f{message}"
permission: "bellchat.channel.admin"

trade:
prefix: "&7[&6T&7]"
format: "{prefix} {player}&7: &f{message}"
cooldown: 30
```

```yaml
# moderation.yml — Moderation settings
moderation:
word-filter:
enabled: true
action: BLOCK # BLOCK, CENSOR, or WARN
words:
- "badword1"
- "badword2"

anti-spam:
enabled: true
max-similar-messages: 3
cooldown-ms: 1000

slowmode:
default-seconds: 0 # 0 = disabled
```

```yaml
# tablist.yml — Tablist customization
tablist:
enabled: true
header: "&6✦ &e&lYour Server Name &6✦"
footer: "&7Online: &f{online}&7/&f{max} &8| &7TPS: &f{tps}"
format: "{prefix} {player}"
update-interval-ticks: 100
show-health: true
show-ping: true
```

---

## 🌟 BellChat Pro Addon

Take your chat to the next level with **BellChatPro** — the premium expansion:

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

### ✨ Pro Features

| Feature | Description |
|---------|-------------|
| 🎨 **Per-player chat colors** | Players choose their chat color & style via GUI |
| 🌈 **MiniMessage support** | Hex colors, gradients, rainbow text, and more |
| 💾 **SQLite chat logging** | Full chat history with search and filtering |
| 🔗 **Discord webhooks** | Forward moderation actions to Discord channels |
| ✏️ **Extended formatting** | Bold, italic, underline, strikethrough for VIPs |

### 🎨 MiniMessage Examples

```
<gradient:gold:yellow>This text has a golden gradient!</gradient>
<rainbow>Rainbow text for VIP players!</rainbow>
<color:#FF5733>Custom hex color!</color>
```

### 💾 Chat Logging

```
/bellchatpro log search <player> [keyword]
/bellchatpro log recent [count]
/bellchatpro log export <player>
```

All chat is stored in a lightweight SQLite database — searchable, exportable, and GDPR-friendly with player data cleanup commands.

---

## 🔗 Ecosystem Integration

BellChat is designed to work seamlessly with the Bell plugin ecosystem:

```
Group change in BellLP / VIP granted via BellGate
│
▼
┌─────────────────────────┐
│ BellChat receives event │
│ │
│ ► Chat prefix updated │
│ ► Tablist refreshed │
│ ► Color codes applied │
│ ► Pro features unlocked│
└─────────────────────────┘
│
▼
Player sees changes instantly — no relog needed!
```

---

## 📥 Installation

1. Drop `BellChat.jar` into your `/plugins` folder
2. Start or restart your server
3. Edit the generated configs in `plugins/BellChat/`
4. *(Optional)* Install LuckPerms for rank-based formatting
5. *(Optional)* Install BellLP for automatic group sync
6. *(Optional)* Drop `BellChatPro.jar` for premium features
7. Run `/bellchat reload` to apply changes
8. Your chat system is live! 🎉

---

## 🤝 Support & Links

- 💬 **Discord:** [https://discord.gg/6q7bnSYaR](#) — fastest way to get help
- 📖 **Wiki:** [Full documentation](#)
- 🐛 **Issues:** [Report bugs](#)
- ⭐ **Rate this plugin** if it helps your server — it means a lot!

---

BellChat — Chat done right. Channels, ranks, moderation, and more. 
Made with ❤️ for the Minecraft community.