zChat

!zChat by Xena Studios, a chat plugin for Paper and Folia. A chat-bubble icon and the zChat wordmark on a dark mission-control style banner with the tagline "Format your server's chat."

A lightweight, high-performance chat plugin for Paper (and Folia) networks. zChat handles the chat essentials almost every server wants — group-based message formatting, a word/pattern filter, a per-player cooldown, a global chat mute, chat clearing, and a per-player chat toggle — each individually toggleable, permissioned, and with fully customizable MiniMessage text.

Because it runs on every chat message, that path is built to be cheap: group formats are pre-parsed, filter patterns are pre-compiled, all runtime state is lock-free, and the message renderer runs once per message (not once per viewer). No always-on tick work, a tiny memory footprint, and clean, fail-safe startup/reload.

zChat is built to stay up: every code path fails safe. It never throws out of enable/reload, never blocks the main thread, and never disables itself on a bad config value. A malformed format template falls back to a plain rendering rather than dropping a message.

---

✨ Features

• Group chat formatting — each message is rendered with the highest-weight group the sender has permission for (zchat.group.<name>), falling back to an open default group. Formats are MiniMessage with <player>, <displayname> and <message> placeholders. Player text is inserted as a component (never re-parsed), so players can't inject markup — unless you grant the optional colour permission.
• Chat filter — block or censor configurable words / regex patterns (case-insensitive, pre-compiled). block cancels the message; censor masks each match with a configurable character. Bypass with zchat.bypass.filter.
• Chat cooldown — a per-player minimum delay between messages. Bypass with zchat.bypass.cooldown.
• /mutechat — toggle a global chat mute; only zchat.bypass.mute holders can talk while muted.
• /clearchat — flood the chat with blank lines to clear it for everyone; zchat.bypass.clearchat holders keep their view.
• /togglechat — let a player hide/show chat for themselves.
• /zchat reload / info — reload re-reads and re-validates config and re-applies all message/behaviour values live; info shows build/version + runtime status.
• Fully configurable — per-feature enabled, per-command aliases/permission, and MiniMessage text throughout, plus a shared messages.error.* block. Safe defaults on; bad values fall back with a warning.
• Folia-ready — the same jar runs on Paper, Purpur and Folia; all runtime state is thread-safe and every player mutation runs on the correct scheduler.

---

📦 Requirements

• Paper 1.20.6+ (or a fork like Purpur, or Folia). A jar built against 1.20.6 runs unchanged on all newer versions; the target only gates which APIs compile, with no runtime performance impact.
• Java 21 runtime.
• No hard dependencies — groups resolve by permission node, so any permissions plugin (LuckPerms, etc.) works, but none is required.

---

🚀 Install

1. Download the jar from this page and drop it in your server's plugins/ folder.
2. Start the server once — zChat writes a default config.yml.
3. Edit plugins/zChat/config.yml to taste, then run /zchat reload. Messages and behaviour values apply live; enabling/disabling a command and changing its aliases are restart-only (they apply when commands are registered at startup).
4. Grant permissions in your permission plugin as needed (see Commands & permissions), including the zchat.group.* nodes that select each rank's chat format.

---

⌨️ Commands & permissions

Command	Permission	Default	Description
/clearchat (+ cc)	zchat.command.clearchat	op	Clear the chat for everyone.
/mutechat (+ mc)	zchat.command.mutechat	op	Toggle the global chat mute.
/togglechat (+ tc)	zchat.command.togglechat	everyone	Hide/show chat for yourself.
/zchat reload / info (+ zc)	zchat.admin	op	Reload config / show status.

Bypass / group node	Default	Grants
zchat.bypass.mute	op	Speak while chat is muted.
zchat.bypass.cooldown	op	Ignore the chat cooldown.
zchat.bypass.filter	op	Ignore the chat filter.
zchat.bypass.clearchat	op	Keep your chat on /clearchat.
zchat.chat.color	(unset)	Use MiniMessage colours in your own messages.
zchat.group.vip / .staff / .admin	op	Apply that group's chat format.

All permissions are declared in paper-plugin.yml with these defaults so the plugin is safe out-of-the-box. Custom permissions set in config that aren't declared default to op-only; set them blank ("") for no restriction.

---

⚙️ Configuration

Full, commented defaults ship in config.yml; on upgrade new keys are merged in without wiping your settings, and invalid values fall back to their default with a console warning.

Chat formats (formatting.groups) — each group has a weight, a permission, and a MiniMessage format (<player>, <displayname>, <message>). The highest-weight group a player has permission for wins; an open default group is the fallback. Ships default, vip, staff, admin — edit, delete, or add your own.

Key	Default	Description
enabled	true	Master switch for group formatting.
color-permission	zchat.chat.color	Holders may use MiniMessage tags in their own messages (blank = never).
default-format	(set)	Fallback format when no group matches.
groups.<name>.weight	0	Higher weight wins when a player matches several groups.
groups.<name>.permission	(set)	Node that selects this format (blank = everyone).
groups.<name>.format	(set)	MiniMessage template.

Filter (filter) — mode: block (cancel + warn) or censor (mask matches with censor-char); add case-insensitive regex patterns. Cooldown (cooldown) — seconds minimum delay between a player's messages. Commands (clearchat / mutechat / togglechat) — each has enabled, aliases, permission and its own messages (e.g. clearchat.lines defaults to 100).

---

⚡ How it stays fast & lightweight

• A disciplined hot path. The chat listener reads only the immutable settings snapshot and lock-free runtime state — no getConfig(), no static-text MiniMessage parse, no regex compile per message. Gates run cheapest-first (mute → cooldown → filter → format → viewer hiding).
• Parse/compile once. Group formats are pre-validated and parsed per message only for their placeholders; filter patterns are compiled at load; the chat renderer is viewer-unaware (rendered once, not per recipient).
• No always-on work. zChat schedules no repeating tasks. The only listener is the chat pipeline itself; per-player state is dropped on quit so nothing leaks.
• Immutable settings snapshot. Config is parsed once into an immutable object and swapped atomically on /zchat reload; runtime state (mute/toggle/cooldowns) is preserved across the swap.
• Thread-correct + Folia-aware. All runtime state is concurrent; player mutations run on the correct scheduler. One jar, correct on Paper, Purpur and Folia.
• Fail-safe everywhere. onEnable/reload and every command registration are wrapped so a bad value or one broken command is logged and skipped, never taking the server down.