# ZealousChat
*A modern, MiniMessage-powered chat formatter for PaperMC servers*
ZealousChat replaces Vanilla chat with a fully–configurable system built on the Paper's high performance **AsyncChatEvent** and **MiniMessage** components. It ships with rank/world specific formats, private messaging, inventory placeholders and a granular permission model – all while remaining light-weight and production ready.
---
## Features
- **MiniMessage everywhere** – gradients, hex colours, hover/click events
- **Rank, world & permission based formats** with priority system
- **Private messaging** (`/msg`, `/reply`) with social-spy & cooldowns
- **Chat / Message toggles** per-player (with staff bypass)
- **Inventory placeholders** `[inv]`, `[ender]`, `[armor]`, `[hand]`, `[pos]`, `[health]`
- **URL auto-linking** & **@mentions** (configurable)
- **Command framework** powered by Lamp with live `/zchat test` preview
- **PlaceholderAPI bridge** (optional soft-depend)
- **Hot-reloadable** HOCON configuration (`/zchat reload`)
- **Customizable Messages** for all messages used within the plugin.
## Commands
### Plugin Core
- `/zealouschat` (`/chatplugin`, `/chatformat`, `/zchat`) — Base command for ZealousChat
- Permission: `chatplugin.admin`
- This command is not an actual command, but rather the base for all sub-commands.
### Configuration Commands
- `/zealouschat reload` — Reload plugin configuration
- Permission: `chatplugin.admin.reload`
- `/zealouschat info` — Display current plugin settings and feature flags
- Permission: `chatplugin.admin.info`
- `/zealouschat test ` — Preview chat formatting
- Permission: `chatplugin.admin.test`
- Parameters:
- ``: Text to format and display
### Format Management
- `/zealouschat format set default ` — Set default chat format
- Permission: `chatplugin.admin.format`
- Parameters:
- ``: MiniMessage format string
- `/zealouschat format set group ` — Define group-specific format
- Permission: `chatplugin.admin.format`
- Parameters:
- ``: Permission group name
- ``: MiniMessage format string
- `/zealouschat format set world ` — Define world-specific format
- Permission: `chatplugin.admin.format`
- Parameters:
- ``: World name
- ``: MiniMessage format string
- `/zealouschat format list` — List all current chat formats
- Permission: `chatplugin.admin.format`
### Feature Toggles
- `/zealouschat toggle colors` — Enable/disable color codes in chat
- Permission: `chatplugin.admin.toggle`
- `/zealouschat toggle formatting` — Enable/disable text formatting
- Permission: `chatplugin.admin.toggle`
- `/zealouschat toggle mentions` — Enable/disable player @mentions
- Permission: `chatplugin.admin.toggle`
- `/zealouschat toggle cooldown` — Enable/disable chat cooldown
- Permission: `chatplugin.admin.toggle`
### Private Messaging
- `/msg ` — Send a private message (aliases: `/message`, `/tell`, `/whisper`, `/w`)
- Permission: `chatplugin.message`
- Parameters:
- ``: Recipient player name
- ``: Message text
- `/reply ` — Reply to the last private message sender (aliases: `/r`, `/respond`)
- Permission: `chatplugin.message`
- Parameters:
- ``: Reply text
### Chat & Social Spy Toggles
- `/zealouschat toggle chat` — Toggle your public chat on/off
- Permission: `chatplugin.toggle.chat`
- `/zealouschat toggle messages` — Toggle your private messages on/off
- Permission: `chatplugin.toggle.messages`
- `/zealouschat toggle socialspy` — Enable/disable social spy for private messages
- Permission: `chatplugin.socialspy`
- `/zealouschat toggle status` — View your current chat & private message status
- Permission: `chatplugin.status`
### Administrator Controls
- `/zealouschat admin clear ` — Clear various chat-related data
- Permission: `chatplugin.admin`
- Parameters:
- ``: One of: `toggles` (resets all chat toggles), `socialspy` (resets all social spy states), `cooldowns` (clears message cooldowns), or `all` (clears all data)
- `/zealouschat admin toggle chat ` — Force toggle public chat for a player
- Permission: `chatplugin.admin`
- Parameters:
- ``: Target player name
- ``: Enable or disable chat
- `/zealouschat admin toggle messages ` — Force toggle private messages for a player
- Permission: `chatplugin.admin`
- Parameters:
- ``: Target player name
- ``: Enable or disable private messages
- `/zealouschat admin toggle all ` — Force toggle both chat & private messages
- Permission: `chatplugin.admin`
- Parameters:
- ``: Target player name
- ``: Enable or disable both
- `/zealouschat admin socialspy ` — Force toggle social spy for a player
- Permission: `chatplugin.admin`
- Parameters:
- ``: Target player name
- ``: Enable or disable social spy
- `/zealouschat admin stats` — Display server-wide chat and private message toggle statistics
- Permission: `chatplugin.admin`
## Quick Start
1. Drop the built jar into `plugins/` and restart.
2. Edit `plugins/ZealousChat/config.conf` – changes can be reloaded with `/zealouschat reload`.
3. Grant players a format permission such as `chatplugin.format.vip` or allow colours with `chatplugin.color`.
## Placeholders
All Chat, PM and config strings support MiniMessage plus any PlaceholderAPI tags when the plugin is present.
## Supported Versions / Dependencies
- PaperMC / Spigot **1.20.4+** (may work on older versions, mostly untested)
- Java 21+
- (Optional) PlaceholderAPI for external placeholders
## Permissions
---
### Need help?
• Discord: [*Join Here*](https://discord.gg/A6NG8DaAb7)