Velocity Integration

Relays global chat across multiple Paper / Folia servers via a Velocity proxy.

About compatibility

The Paper and Velocity plugins are versioned independently. Using the latest of both always works. If you need to mix older versions, see Paper / Velocity Compatibility.

Setup

1. Install the Velocity Plugin

Place LunaticChat-<version>-velocity.jar in the Velocity plugins/ directory and restart the proxy.

2. Paper-Side Configuration

Set the following in each Paper server's config.yml.

features:
  velocityIntegration:
    enabled: true
    crossServerGlobalChat: true
    serverName: "survival"    # Must match the server name in the Velocity configuration

3. Verify the Connection

/lcv status

You can check the connection status, protocol version, Velocity plugin version, and more (permission: lunaticchat.command.lcv.status, default: op).

Cross-Server Global Chat

When crossServerGlobalChat is set to true, player chat messages are relayed via Velocity to all other Paper servers.

Message Flow

1. A player sends a chat message
2. The Paper server sends the message to Velocity
3. Velocity relays the message to all servers except the sender's
4. The message is displayed to players on each server

Message Deduplication

Each message is assigned a unique ID, and a cache prevents the same message from being displayed more than once. The cache size can be configured with messageDeduplicationCacheSize (default: 100).

Entries expire 60 seconds after they are recorded. If the cache is still over its configured size after expired entries are cleared, the oldest remaining entries are dropped.

Cross-Server Direct Messages Paper v1.3.0~ / Velocity v1.2.0~

Setting crossServerDirectMessage to true lets players exchange direct messages with players on other servers connected to the same proxy.

Connection States

The states reported by /lcv status and their meanings:

State	Description
DISCONNECTED	Not connected
HANDSHAKING	Handshake in progress
CONNECTED	Connected
FAILED	Connection failed

The handshake timeout is 5 seconds. If the handshake times out, the state becomes FAILED.

Until the state is CONNECTED, the server ignores global chat and direct messages relayed from other servers. A server stuck in FAILED therefore shows nothing from the rest of the network.

Keep the Velocity plugin up to date

A backend cannot tell a message the proxy relayed from one a player's client sent on the same connection, so it relies on the Velocity plugin to drop messages that players send on the LunaticChat channel. Velocity plugin v1.3.1 and earlier passed them on (GHSA-4p78-89rh-8px5). Updating only the Paper plugin does not close this.

Troubleshooting FAILED

• Confirm the Velocity plugin is installed and the proxy is running
• Confirm the Paper serverName matches the server name configured in Velocity
• Confirm the protocol versions of the Paper and Velocity plugins are compatible — see the compatibility matrix

Configuration Reference

Setting Key	Default	Description
enabled	false	Enable Velocity integration
crossServerGlobalChat	false	Enable cross-server global chat
crossServerDirectMessage	false	Enable cross-server direct messages
serverName	"Unknown"	This server's own name. Fills {server} in cross-server chat and is how the server recognises its own players. Set it to the name registered in velocity.toml
messageDeduplicationCacheSize	100	Size of the message deduplication cache

Message Format

The display format for cross-server chat can be customized via messageFormat.crossServerGlobalChatFormat in config.yml. See Message Format for details.

Related Documents

• Paper / Velocity Compatibility — protocol version and rolling update details