🎯 UltimateChat - Complete Plugin Overview

📋 Plugin Description

**UltimateChat** is a comprehensive, enterprise-grade chat management plugin for Minecraft Paper servers (1.21+). Designed with **100% configurability** in mind, every feature can be toggled, customized, and translated without touching code. Built using modern Java 21, the Kyori Adventure library, and sophisticated database architecture, it provides everything from basic chat formatting to advanced social systems and Discord integration.

---

⭐ Core Philosophy

**100% Configurability**
- Every feature has an `enabled: true/false` toggle
- All messages stored in `messages.yml` for easy translation
- All keywords customizable (change `[item]` to `[show]`, etc.)
- All formats use MiniMessage for hex colors and gradients
- No hardcoded text or behavior

**Modular Architecture**
- 55 independent Java classes
- Clean separation of concerns (chat, social, moderation, database)
- Easy to extend and customize
- Professional code structure with interfaces and abstractions

**Performance First**
- Async database operations (HikariCP connection pooling)
- Cached message parsing
- Efficient event handling
- Optimized for servers with 100+ players

---

🎨 Feature Categories

**1. Advanced Chat Formatting**

**Visual Customization:**
- **MiniMessage Support**: Full hex colors (`FF5555`), gradients, rainbow text
- **Priority Tag System**: Weight-based tag sorting (Admin > Mod > VIP)
```yaml
admin:
permission: "ultimatechat.tag.admin"
display: "<gradient:ff0000:ff5555>[ADMIN]</gradient>"
weight: 100
```
- **Prefixes & Suffixes**: Permission-based role indicators
- **Click Actions**: Configurable click events (suggest command, open URL, run command)
- **Hover Text**: Custom tooltip when hovering over names
```yaml
hover-text:
text: |
<gray>Level: {level}</gray>
<gray>Ping: {ping}ms</gray>
```

**Placeholders:**
- Built-in: `{player}`, `{displayname}`, `{world}`, `{x}`, `{y}`, `{z}`, `{health}`, `{level}`, `{ping}`, etc.
- PlaceholderAPI integration (optional)
- Custom placeholders from config

---

**2. Interactive Chat Elements**

**Item Linking:**
```
Player: "Check out my sword! [item]"
→ Displays item with full NBT, enchantments, lore on hover
```
- Configurable keyword (default: `[item]`)
- Shows item name, durability, enchantments, lore
- Permission-based (`ultimatechat.chat.itemlink`)

**Inventory Display:**
```
Player: "Here's my inventory [inv]"
→ Shows summarized inventory on hover
```
- Top 10 items with quantities
- Configurable display format
- Also supports `[ender]` for enderchest

**Player Mentions:**
```
Player: "@Steve come here!"
→ Steve receives notification + sound + highlight
```
- Automatic @Player detection
- Sound notification (configurable type/volume/pitch)
- Optional title notification
- Click to message

**Custom Placeholders:**
```yaml
pos:
trigger: "[pos]"
replacement: "X: {x}, Y: {y}, Z: {z}"
hover: "<gray>World: {world}</gray>"
```

---

**3. Social Systems**

**Friend System**
**Features:**
- Send/accept/deny friend requests
- Friend list with online status indicators
- Friend chat (`/fc <message>`) - broadcast to all online friends
- Join/quit notifications
- Permission-based friend limits (10/25/50/100/unlimited)

**Commands:**
```
/friend add <player> - Send friend request
/friend accept <player> - Accept request
/friend deny <player> - Deny request
/friend remove <player> - Remove friend
/friend list - View all friends (green = online)
/friend requests - View pending requests
/fc <message> - Friend chat
```

**Database Storage:**
- Persistent across sessions
- MySQL or SQLite support
- Efficient indexed queries

**Party System**
**Features:**
- Create temporary party groups
- Invite players to party
- Party chat (session-based)
- Leader controls (kick, disband)
- Max party size configurable

**Commands:**
```
/party create - Create a party
/party invite <player> - Invite to party
/party accept - Accept invite
/party leave - Leave party
/party kick <player> - Kick member (leader only)
/party list - View members
```

**Ignore/Block System**
**Features:**
- Completely hide messages from ignored players
- Persistent ignore list
- Works across all channels

**Commands:**
```
/ignore <player> - Ignore a player
/ignore remove <player> - Unignore
/ignore list - View ignored players
```

---

**4. Multi-Channel System**

**Channel Types:**

**Global Channel:**
- Server-wide communication
- Default channel for all players
- Integrates with ignore list

**Local Channel:**
- Radius-based proximity chat (default: 100 blocks)
- Shows message range indicator
- Perfect for roleplay servers

**Staff Channels:**
- **Admin**: `ultimatechat.channel.admin`
- **Moderator**: `ultimatechat.channel.mod`
- **Builder**: `ultimatechat.channel.builder`
- Private communication for staff
- Logged to console
- Join/leave notifications

**Custom Group Channels:**
- Player-created persistent chat rooms
- Stored in database
- Invite-only or public
- Owner controls (rename, delete, kick)

**Commands:**
```
/channel global - Switch to global
/channel local - Switch to local (radius)
/channel admin - Switch to admin (staff)
/channel list - View available channels
/group create <name> - Create custom group
/group invite <group> <player>
/group leave <group>
```

**Configuration:**
```yaml
channels:
local:
radius: 100.0
format: "<gray>[Local]</gray> {player} » {message}"

staff:
admin:
format: "<red>[ADMIN]</red> {player} » {message}"
log-to-console: true
```

---

**5. Comprehensive Moderation**

**Anti-Spam Filter**
**Features:**
- Configurable cooldown (default: 2 seconds)
- Duplicate message detection
- Violation counter with actions (WARN/MUTE/KICK)
- Bypass permission: `ultimatechat.bypass.spam`

**Configuration:**
```yaml
anti-spam:
enabled: true
cooldown: 2
block-duplicates: true
max-violations: 3
action: WARN or MUTE, KICK
```

**Anti-Caps Filter**
**Features:**
- Percentage threshold (default: 70%)
- Auto-lowercase or block messages
- Minimum message length check

**Configuration:**
```yaml
anti-caps:
enabled: true
percent: 70
auto-lowercase: true
```

**Regex Chat Filter**
**Features:**
- Word blacklist (`filter.yml`)
- Advanced regex patterns
- Blocks IPs, URLs, Discord invites, emails
- Whitelist for false positives
- Normalization (removes l33t speak)

**Filter Examples:**
```yaml
blocked-words:
- "badword"
- "spam"

blocked-patterns:
- "\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b" IP addresses
- "discord\\.gg/[a-z0-9]+" Discord invites
```

**Shadow Mute System**
**Revolutionary Feature:**
- Muted players see their own messages (think it was sent)
- Other players don't receive the message
- More effective than traditional mutes
- Temporary or permanent
- Notify staff on chat attempts

**Usage:**
```
/shadowmute <player> [duration] [reason]
/unshadowmute <player>
```

**Benefits:**
- Toxic players don't realize they're muted
- No drama or ban evasion attempts
- Staff notifications for monitoring

**Command Spy**
**Features:**
- Log all player commands
- Exclude sensitive commands (login, password)
- Toggle per staff member
- Console logging
- Exclude staff from being spied on

**Commands:**
```
/commandspy - Toggle command spy
```

**View:**
```
[Spy] PlayerName » /tpa Steve
```

---

**6. Discord Integration**

**Two-Way Communication**

**Minecraft → Discord (Webhook):**
- Fast, lightweight
- Custom username and avatar per player
- Formatted messages
- Server events (join/quit/death)

**Discord → Minecraft (JDA Bot):**
- Full bot integration
- Read Discord messages
- Send to Minecraft chat
- Update bot status with player count
- Customizable channel

**Configuration:**
```yaml
discord:
enabled: true

webhook:
enabled: true
url: "https://discord.com/api/webhooks/..."
username: "Minecraft Server"
avatar-url: "https://crafatar.com/avatars/{uuid}"

bot:
enabled: true
token: "YOUR_BOT_TOKEN"
channel-id: "123456789"

format:
minecraft-to-discord: "**{player}**: {message}"
discord-to-minecraft: "<blue>[Discord]</blue> {username} » {message}"
```

**Features:**
- Automatic player count status updates
- Server event notifications
- Markdown ↔ MiniMessage conversion
- Rate limit handling
- Async processing

---

**7. Auto-Announcements**

**Features:**
- Timed broadcasts (configurable interval)
- Sequential or random order
- 15+ pre-configured announcements
- MiniMessage formatting
- Click and hover events
- Permission-based announcements
- Sound notifications
- Personal announcements (first join, returning player)

**Example Announcements:**
```yaml
- text: "<gold>Welcome to the server!</gold>"
hover: "Click for help"
click-action: "RUN_COMMAND"
click-value: "/help"

- text: "<blue>Join our Discord: discord.gg/server</blue>"
click-action: "OPEN_URL"
click-value: "https://discord.gg/server"
```

**Advanced Features:**
- Timed announcements (cron-based)
- Conditional announcements (player count, world)
- Announcement groups (different sets per world)

---

**8. Database System**

**Supported Databases:**
- **SQLite** (default, file-based, no setup required)
- **MySQL** (recommended for networks, better performance)

**HikariCP Connection Pooling:**
- Professional-grade connection management
- Configurable pool size
- Automatic reconnection
- Optimized for high load

**Stored Data:**
- Friend relationships (bidirectional)
- Ignored players
- Custom groups and members
- Player settings (key-value storage)

**Tables:**
```sql
uc_friends - Friend relationships
uc_ignored - Ignore list
uc_groups - Custom chat groups
uc_group_members - Group membership
uc_player_data - Generic player data
```

**Configuration:**
```yaml
database:
type: SQLITE or MYSQL

MySQL settings
host: localhost
port: 3306
database: ultimatechat
username: root
password: ""

pool:
maximum-pool-size: 10
minimum-idle: 2
```

---

🛠️ Technical Specifications

**Requirements**
- **Server:** Paper 1.21 - 1.21.1+ (No NMS, uses modern API)
- **Java:** 21 (LTS)
- **RAM:** Minimum 512 MB allocated
- **Optional:** PlaceholderAPI, Vault, LuckPerms

**Dependencies (Shaded)**
All dependencies are included in the final JAR with relocation to prevent conflicts:
- **HikariCP 5.1.0** - Database connection pooling
- **SQLite JDBC 3.46.0** - SQLite driver
- **MySQL Connector 8.4.0** - MySQL driver
- **JDA 5.0.0** - Discord bot API
- **SLF4J 2.0.13** - Logging framework

**Performance**
- **Async Operations:** Database queries, Discord webhooks
- **Cached Parsing:** Pre-parsed MiniMessage components
- **Efficient Filtering:** Compiled regex patterns
- **Event Priority:** HIGHEST for chat processing
- **Memory Usage:** ~50-100 MB typical runtime

```

---

📊 Permission System

**Hierarchical Structure**

**Admin Permissions:**
```
ultimatechat.admin - Full access
├── ultimatechat.admin.reload
├── ultimatechat.moderation.*
└── ultimatechat.bypass.*
```

**Chat Features:**
```
ultimatechat.chat.colors - Use color codes
ultimatechat.chat.formatting - Bold, italic, etc.
ultimatechat.chat.hex - Hex colors (FF5555)
ultimatechat.chat.gradients - Gradient text
ultimatechat.chat.mention - @Player mentions
ultimatechat.chat.itemlink - [item] keyword
```

**Social Features:**
```
ultimatechat.friend.use
ultimatechat.friend.limit.10 - Max 10 friends
ultimatechat.friend.limit.25
ultimatechat.friend.limit.50
ultimatechat.friend.limit.100
ultimatechat.friend.limit.unlimited

ultimatechat.party.use
ultimatechat.ignore.use
ultimatechat.group.use
ultimatechat.group.create
```

**Channels:**
```
ultimatechat.channel.use
ultimatechat.channel.global
ultimatechat.channel.local
ultimatechat.channel.admin
ultimatechat.channel.mod
ultimatechat.channel.builder
```

**Moderation:**
```
ultimatechat.moderation.notify - Receive notifications
ultimatechat.moderation.shadowmute - Shadow mute players
ultimatechat.moderation.commandspy - Command spy

ultimatechat.bypass.spam
ultimatechat.bypass.caps
ultimatechat.bypass.filter
```

**Tags:**
```
ultimatechat.tag.vip
ultimatechat.tag.mod
ultimatechat.tag.admin
```

---

🎮 Usage Examples

**Example 1: VIP Chat**
**Configuration:**
```yaml
priority-tags:
vip:
permission: "ultimatechat.tag.vip"
display: "<gradient:ffaa00:ffff00>[VIP]</gradient>"
weight: 50

chat-format:
format: "<tags> <white>{player}</white> » <message>"
```

**In-Game:**
```
[VIP] PlayerName » Check out my new sword! [item]
```
- Hover over `[VIP]` shows rank info
- Hover over `PlayerName` shows stats
- Hover over `[item]` shows full sword details with enchantments

**Example 2: Staff Communication**
**Scenario:** Admin wants to discuss moderation with moderators

```
/channel mod
Admin » We have a griefer in sector 7
Mod1 » On it, checking now
Mod2 » I see them, taking action
```
- Only staff with `ultimatechat.channel.mod` see this
- Logged to console for records
- Different color coding per channel

**Example 3: Friend Group**
**Players want private chat:**

```
/friend add Steve
/friend add Alex

Steve: "Hey guys, want to raid a dungeon?"
Alex: "Sure! Where?"
You: "Meet at spawn"

/fc Let's form a party!
→ All online friends receive the message
```

**Example 4: Local Roleplay**
**Radius-based immersive chat:**

```
/channel local

[Local] Knight » "Ho there, traveler!"
[Local] Merchant » "Good morrow! Care to trade?"

(Only players within 100 blocks see these messages)
```

**Example 5: Discord Integration**
**Seamless cross-platform:**

**Minecraft:**
```
Player: "Server is awesome today!"
→ Sent to Discord channel
```

**Discord:**
```
DiscordUser: "Can someone help me with a quest?"
→ [Discord] DiscordUser » Can someone help me with a quest?
(Shows in Minecraft)
```

---

🔧 Configuration Highlights

**Quick Setup**

**1. Basic Chat Format:**
```yaml
chat-format:
enabled: true
format: "<tags> {player} » {message}"
```

**2. Enable Features:**
```yaml
friends:
enabled: true

parties:
enabled: true

channels:
enabled: true
```

**3. Configure Moderation:**
```yaml
moderation:
anti-spam:
enabled: true
cooldown: 2

anti-caps:
enabled: true
percent: 70
auto-lowercase: true

filter:
enabled: true
```

**4. Discord Setup:**
```yaml
discord:
enabled: true
webhook:
enabled: true
url: "YOUR_WEBHOOK_URL"
bot:
enabled: true
token: "YOUR_BOT_TOKEN"
channel-id: "CHANNEL_ID"
```

**Advanced Customization**

**Custom Channel:**
```yaml
channels:
roleplay:
enabled: true
display-name: "Roleplay"
permission: "server.roleplay"
format: "<green>[RP]</green> {player} » {message}"
color: "55FF55"
```

**Custom Tag:**
```yaml
priority-tags:
sponsor:
permission: "server.sponsor"
display: "<rainbow>[SPONSOR]</rainbow>"
weight: 75
```

**Custom Placeholder:**
```yaml
custom-placeholders:
definitions:
coords:
trigger: "[coords]"
replacement: "Location: {x}, {y}, {z}"
hover: "<gray>World: {world}</gray>"
```

---

📈 Use Cases

**1. Survival Servers**
- Friends system for community building
- Local chat for proximity-based communication
- Anti-grief through chat logging and command spy
- Discord integration for 24/7 communication

**2. Roleplay Servers**
- Local channel for immersive proximity chat
- Custom channels for different zones/factions
- Staff channels for admin coordination
- Rich formatting for character names

**3. Minigame Servers**
- Party system for team coordination
- Quick announcements for events
- Global chat for server-wide communication
- Friend system to play with buddies

**4. Network Servers**
- MySQL database for cross-server data
- Discord integration for network chat
- Centralized moderation tools
- Staff channels across servers

**5. Creative Servers**
- Builder channel for builder communication
- Show off builds with item linking
- Friend system for collaboration
- Local chat in build zones

---

🎯 Unique Selling Points

**1. True 100% Configurability**
Unlike other chat plugins, **every single aspect** is configurable:
- Change ANY message text
- Edit ANY keyword (`[item]` to `[show]`)
- Toggle ANY feature
- Customize ANY format
- Adjust ANY limit

**2. Shadow Mute Technology**
First Minecraft plugin to implement psychological moderation:
- Muted players don't know they're muted
- Prevents ban evasion
- Reduces drama
- More effective than traditional mutes

**3. Enterprise Database Architecture**
Professional-grade data handling:
- HikariCP connection pooling
- Async operations
- SQL injection prevention
- Automatic migration support
- Optimized queries with indexes

**4. Modern Tech Stack**
Built with latest technology:
- Java 21 (latest LTS)
- Paper API 1.21 (no NMS, no version dependence)
- Kyori Adventure (native component system)
- Maven shade with relocation (no conflicts)

**5. Comprehensive Social Suite**
All-in-one solution:
- Friends, Parties, Groups, Ignore
- Everything other plugins do, in one place
- Unified permission system
- Consistent UI/UX

**6. Production-Ready**
Not a proof-of-concept:
- Error handling everywhere
- Extensive logging
- Config validation
- Migration support
- Performance optimized

---

📚 Commands Reference

**Main Commands**
```
/ultimatechat reload - Reload all configurations
/ultimatechat version - Show plugin version
/ultimatechat help - Show help menu
```

**Friend Commands**
```
/friend add <player> - Send friend request
/friend remove <player> - Remove friend
/friend accept <player> - Accept request
/friend deny <player> - Deny request
/friend list - View friends (✓ online)
/friend requests - View pending requests
/fc <message> - Friend chat
```

**Party Commands**
```
/party create - Create party
/party invite <player> - Invite to party
/party accept - Accept invite
/party decline - Decline invite
/party leave - Leave party
/party kick <player> - Kick member
/party list - View members
```

**Ignore Commands**
```
/ignore <player> - Ignore player
/ignore remove <player> - Unignore
/ignore list - View ignored players
```

**Channel Commands**
```
/channel global - Switch to global
/channel local - Switch to local
/channel admin - Switch to admin
/channel list - View available channels
/channel info - Current channel info
```

**Group Commands**
```
/group create <name> - Create group
/group delete <name> - Delete group (owner)
/group invite <group> <player> - Invite
/group accept <group> - Accept invite
/group leave <group> - Leave group
/group list - View your groups
```

---

🏆 Comparison with Other Plugins

| Feature | UltimateChat | EssentialsX Chat | VentureChat | ChatControl |
|---------|--------------|------------------|-------------|-------------|
| **MiniMessage Support** | ✅ Full | ❌ | ⚠️ Limited | ❌ |
| **Friend System** | ✅ Database | ❌ | ❌ | ❌ |
| **Party System** | ✅ | ❌ | ⚠️ Basic | ❌ |
| **Multi-Channel** | ✅ 4+ types | ⚠️ Basic | ✅ | ⚠️ Basic |
| **Discord Integration** | ✅ 2-way | ❌ | ⚠️ 1-way | ⚠️ 1-way |
| **Shadow Mute** | ✅ Unique | ❌ | ❌ | ❌ |
| **Command Spy** | ✅ | ⚠️ Via Essentials | ❌ | ✅ |
| **Item Linking** | ✅ NBT Support | ❌ | ⚠️ Basic | ❌ |
| **Database** | ✅ MySQL/SQLite | ❌ | ⚠️ MySQL only | ❌ |
| **100% Configurable** | ✅ Everything | ⚠️ Most | ⚠️ Most | ⚠️ Most |
| **Modern API** | ✅ Paper 1.21 | ⚠️ Spigot | ⚠️ Spigot | ⚠️ Spigot |

---

💡 Tips & Best Practices

**Performance**
1. Use MySQL for servers with 50+ players
2. Enable caching: `cache-formats: true`
3. Set reasonable friend limits
4. Use async database operations

**Configuration**
1. Start with defaults, customize gradually
2. Test regex patterns before deployment
3. Use color codes consistently
4. Keep announcement interval > 60 seconds

**Moderation**
1. Enable shadow mute for toxic players
2. Set up command spy for staff
3. Regularly review filter.yml
4. Adjust spam cooldowns based on community

**Social Features**
1. Promote friend system in welcome message
2. Create staff channels for each rank
3. Set appropriate friend limits per rank
4. Enable join/quit notifications

**Discord**
1. Use webhooks for simplicity
2. Use bot for 2-way communication
3. Set clear channel topic in Discord
4. Test formatting before going live

---

🎬 Conclusion

**UltimateChat** is not just a chat plugin—it's a **complete communication suite** for Minecraft servers. From basic chat formatting to advanced social systems and Discord integration, it provides everything needed for a modern, engaging player experience.

**Perfect for:**
- Server owners who want full control
- Networks requiring scalability
- Communities needing social features
- Staff teams requiring moderation tools
- Developers seeking clean, extensible code

**Built by developers, for developers, serving players.**

---

**Version:** 1.0.0
**Last Updated:** 2024
**Support:** geturplugins (discord)

🚀 Deploy with confidence. Scale with ease. Chat with style.

Need a server to run UltimateChat?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting

UltimateChats