CrossChat

Simple, lightweight cross-server chat for Velocity.

CrossChat is a Velocity 3.x proxy plugin that connects chat across your network, allowing players on different backend servers to communicate through a single global chat channel in real time.

Whether your network has a lobby, survival, farming, minigame, or multiple game servers, CrossChat keeps everyone connected.

---

✨ Features

• 🌐 Cross-server chat — Messages sent from any participating backend server are broadcast to players across your network in real time.
• 🎨 Fully customisable chat format — Configure your global chat appearance directly from config.yml.
• 🖌️ Legacy & MiniMessage support — Use traditional & colour codes or modern Adventure MiniMessage formatting.
• 👑 LuckPerms integration — Automatically display LuckPerms prefixes when LuckPerms is installed on your proxy.
• 🖥️ Server filtering — Choose exactly which backend servers participate in global chat.
• ⚡ Lightweight — Runs on the proxy with minimal overhead and no unnecessary features.
• 🔒 Safe message handling — Player messages are inserted as plain text, preventing players from injecting formatting codes.
• 🔌 Backend placeholder support — Extend CrossChat with the CrossChat Backend Placeholders addon to use placeholder values provided by backend plugins.

---

📋 Requirements

Requirement	Version
Java	17 or later
Velocity	3.x
LuckPerms (optional)	5.x

CrossChat runs on the Velocity proxy. You do not need to install CrossChat on every backend server.

---

📥 Installation

1. Download the latest crosschat-x.x.x.jar.
2. Place it into your Velocity plugins/ folder.
3. Restart your Velocity proxy.
4. CrossChat will automatically create its configuration.
5. Open plugins/velocityglobalchat/config.yml.
6. Configure your chat format and participating servers.
7. Restart the proxy.

That's it — CrossChat is ready to use.

---

⚙️ Configuration

The configuration file is located at:

plugins/velocityglobalchat/config.yml

Example:

# Enable or disable CrossChat
enabled: true

# Global chat format
#
# Placeholders:
#   {server}  - backend server name
#   {player}  - player's Minecraft username
#   {prefix}  - LuckPerms prefix
#   {message} - chat message
#
# Use either & colour codes OR MiniMessage.
# Do not mix both styles.
format: "&8[&b{server}&8] &7{prefix}{player}&f: {message}"

# Backend servers participating in global chat.
#
# Players on servers not listed here will not
# send or receive global chat messages.
#
# Leave empty to include every server.
servers:
  - hub
  - survival
  - farming

---

🎨 Chat Formatting

CrossChat supports both traditional Minecraft colour codes and Adventure MiniMessage.

Legacy & Codes

&8[&b{server}&8] &7{prefix}{player}&f: {message}

Example:

[ SURVIVAL ] [Admin] Ethan: Hello everyone!

MiniMessage

<dark_gray>[<aqua>{server}</aqua>]</dark_gray> <gray>{prefix}{player}</gray><white>: {message}</white>

Available Placeholders

Placeholder	Description
{server}	The backend server the player is currently connected to
{player}	The player's Minecraft username
{prefix}	The player's LuckPerms prefix
{message}	The player's chat message

Security: Player message content is always inserted as plain text, regardless of the selected formatting system. Players cannot inject additional colour codes or MiniMessage tags into global chat.

---

🔌 Backend Placeholders

Want to use information from plugins running on your backend servers?

Use CrossChat Backend Placeholders to extend CrossChat with backend-provided placeholder values.

This can allow you to display things such as:

• Player ranks
• Economy balances
• Current worlds
• Levels
• Factions
• Statistics
• Server-specific information
• Other PlaceholderAPI values

The addon works alongside CrossChat rather than replacing it.

---

🖥️ Server Filtering

You can control exactly which servers participate in global chat.

For example:

servers:
  - hub
  - survival
  - farming

Players on hub, survival, and farming can send and receive global messages.

Servers that aren't listed are excluded from global chat.

To include all connected servers, leave the list empty:

servers: []

This is useful for networks where certain servers should remain isolated, such as private instances, admin servers, or standalone minigames.

---

🔄 How It Works

CrossChat operates entirely on the Velocity proxy.

1. A player sends a chat message.
2. CrossChat receives the PlayerChatEvent on the proxy.
3. CrossChat determines the player's current backend server.
4. The configured chat format is rendered using Adventure.
5. The message is sent to players on participating servers.
6. The original chat event is denied, preventing the backend server from receiving and duplicating the message.

This means CrossChat does not need to forward the same message through every backend server.

---

🧩 Designed for Velocity

CrossChat is built specifically around the Velocity proxy and Adventure API.

Your backend servers don't need a separate CrossChat installation — the proxy handles the global chat system.

---

🛠️ Troubleshooting

Players can't see global messages

Check that:

• CrossChat is installed on Velocity.
• The player's server is included in the servers list.
• The plugin is enabled.
• There are no conflicting chat plugins cancelling or modifying the chat event.

The {prefix} placeholder is empty

Make sure LuckPerms is installed and running on the Velocity proxy, and that the player has a prefix assigned.

LuckPerms is optional, so {prefix} will simply be empty when LuckPerms isn't available.

My formatting isn't working

Make sure you're using one formatting system at a time.

Use either:

&8[&b{server}&8] ...

or:

<dark_gray>[<aqua>{server}</aqua>] ...

Do not mix legacy colour codes and MiniMessage tags in the same format.

---

📜 Licence

CrossChat is released under the MIT License.

See the repository's LICENSE file for the full licence text.