ChatChannels

# ChatChannels
**ChatChannels** is an advanced, both‑side chat channels system for **Minecraft 1.20.1 (Forge)**. It adds configurable global/local/trade/staff channels, private messages, rate limiting, logging, and integration with popular permission systems.
---
## ✨ Features
- **Multiple chat channels out of the box**   - `global` – server‑wide chat   - `local` – proximity chat with configurable radius   - `trade` – trading / market channel   - `staff` – staff‑only channel (permission‑gated)   - `pm` – private messages channel (used internally) - **Fully configurable channels**   - Custom `id`, display `name`, `type`, `prefix`, color, radius and default channel   - Per‑channel **permission node** (optional) – restrict who can see/use each channel - **Permission system integration**   - **LuckPerms** support (via official API)   - **FTB Ranks** support (`ranks.snbt` permissions)   - Fallback to **vanilla op level 4** if no permission plugin is available - **Per‑player chat state**   - Remember last used channel per player   - Mute specific channels   - Ignore specific players - **Rate limiting / anti‑spam**   - Configurable messages‑per‑time window per player - **Logging**   - All channel messages can be logged for moderation (server‑side) - **Server config options**   - Local chat radius   - Rate limit (messages / seconds)   - Optional **“joined/left channel”** system messages
---
## 🔌 Installation / Sides
ChatChannels is a **server‑focused mod**, but it must be installed on **both the server and all connecting clients**.
- **Singleplayer / Open to LAN**   - Install the mod on the client. The integrated server will automatically run with the same mod.
- **Dedicated servers**   - Put the mod JAR into the `mods` folder on the **server**.   - Also include the same JAR in the **client modpack** for all players who join the server.
The mod is built as a standard Forge mod with `side = BOTH`: it contains server‑side logic (channels, permissions, configs, logging) and client‑side code for handling network packets and displaying chat channels.
---
## 🧩 Requirements & Compatibility
- **Minecraft:** 1.20.1   - **Loader:** Forge 47.x (built and tested against **Forge 47.4.0**)   - **Java:** 17
**Works on:**
- **Dedicated servers** – core logic runs server‑side - **Clients:** the mod is intended to be installed on both **server and client** for best experience (channel UI, packets, etc.)
**Optional integrations (not required, but supported):**
- **LuckPerms** – for permission checks like `chat.channels.global` - **FTB Ranks** – for permission nodes and rank‑based name formatting:   - Permission nodes in `ranks.snbt` such as:     - `chat.channels.global`     - `chat.channels.local`     - `chat.channels.trade`     - `chat.channels.staff`   - Rank name formats via `ftbranks.name_format` (used as privilege tags)
If neither LuckPerms nor FTB Ranks are present, the mod falls back to vanilla operator level checks (`hasPermissions(4)`).
---
## ⚙️ Configuration Overview
The mod generates its configs on first run. There are **three main config files**:
### 1. `config/chatchannels.json`
Defines all chat channels and global rate limiting.
**Fields per channel:**
- `id` – internal channel ID (e.g. `"global"`, `"local"`, `"trade"`, `"staff"`, `"pm"`) - `name` – display name shown in the UI (e.g. `"Global"`, `"Local"`) - `type` – how the channel behaves:   - `GLOBAL`, `LOCAL`, `TRADE`, `STAFF`, `TEAM`, `PRIVATE`, `CUSTOM` - `prefix` – short prefix before messages, e.g. `"[G]"`, `"[Local]"`, `"[Trade]"` - `color` – hex color string, e.g. `"#FFFFFF"`, `"#FFD700"` - `radius` – for `LOCAL` channels: radius in blocks; `0` = global‑like broadcast - `default` – `true` if this should be the default channel for new players - `permission` – **permission node required** to use the channel   - Example defaults:     - `chat.channels.global`     - `chat.channels.local`     - `chat.channels.trade`     - `chat.channels.staff`   - If set to an empty string `""`, **no permission is required** for that channel.
**Rate limit section:**
```json "rate_limit": {   "messages": 5,   "per_seconds": 3 } ```
- `messages` – how many messages a player may send - `per_seconds` – time window in seconds   If the limit is exceeded, the player receives a system message like "You are sending messages too fast."
---
### 2. `serverconfig/chatchannels-server.toml`
Server‑side gameplay settings:
- `localChat.radius`     Default radius (in blocks) for the default `LOCAL` channel.
- `rateLimit.messages`     Same as in `chatchannels.json`, but exposed as Forge server config.
- `rateLimit.seconds`     Time window for rate limiting.
- `channels.showSwitchMessages`     - `true` (default) – show server messages when a player joins or leaves a channel:     - `Joined channel <id>`     - `Left channel <id>`   - `false` – do not send these system messages.
These messages are sent when the player uses the channel command / UI that triggers **JOIN/LEAVE** actions.
---
### 3. `config/chatchannels_privileges.json`
Controls **colors for privilege tags** (rank labels) shown before player names in chat.
- `defaultColor` – hex color for unknown/unspecified tags (e.g. `"#FFD700"`) - `tags` – map from **privilege tag string** to a hex color:   - The tag is derived from:     1. LuckPerms prefix (if available), OR       2. `ftbranks.name_format` (if available), OR       3. `"OP"` for server operators
**Default example:**
```json {   "defaultColor": "#FFD700",   "tags": {     "Игрок": "#AAAAAA",     "VIP": "#55FFFF",     "Модератор": "#55FF55",     "Админ": "#FF5555",     "OP": "#FF5555"   } } ```
You can customize this file to match your server’s rank names and colors.
---
## 🔑 Permissions
By default, the following permission nodes are used:
- `chat.channels.global` – talk in the global channel - `chat.channels.local` – talk in the local channel - `chat.channels.trade` – talk in the trade channel - `chat.channels.staff` – access the staff channel (for moderators/admins)
These nodes can be controlled via:
- **LuckPerms** (assign them to users/groups), or - **FTB Ranks** (`ranks.snbt`), for example:
```snbt default: {   ...   chat.channels.global: true   chat.channels.local: true   chat.channels.trade: true }
vip: {   ...   chat.channels.global: true   chat.channels.local: true   chat.channels.trade: true } ```
If you want a channel to be available to everyone without permissions, simply set its `permission` field in `chatchannels.json` to an empty string `""`.
---
## 📝 Notes
- All config files are **generated automatically** on first server start. - Safe to customize and reload between server restarts. - The mod does **not** add commands for channel creation yet — custom channels are defined purely through `chatchannels.json`.