# 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`.