CarbonChat Cross-Server Prefix (backend)

Adds a gold [server] tag in front of global chat messages that came from another server, so players can tell where a message was sent. It is a CarbonChat add-on and does nothing without it.

What it does

• Watches CarbonChat's cross-server global channel (carbon:global by default).
• When a player on this server sends a message, it saves "this message came from <server-name>" in Redis for a short time.
• When a message arrives from another server, it looks that up and puts [main] (or the sender's server name) in front of it. Messages sent on this server get no tag.
• The tag is dark grey brackets around a gold server name. The player name and message keep their normal colors.

The tag is added on the receiving server. Each server that should show tags needs this plugin with its own server-name.

Status note. CarbonChat has been removed from main, info, and hub-modded. On those servers the jar is still in plugins/ but fails to load at every boot with UnknownDependencyException: Unknown/missing dependency plugins: [CarbonChat]. That error is harmless noise. The fix is to rename the jar to .disabled during a restart window. Only build still runs CarbonChat, so only there does this plugin do anything.

How players use it

Players do not interact with this plugin. They just see [server] before messages from other servers in global chat.

Staff guide

There are no commands or permissions.

To check it works: stand on one server, have someone send a global message from another server, and confirm you see the gold [their-server] tag. Messages from your own server have no tag.

Configuration

File: plugins/CarbonServerPrefixBackend/config.yml. There is no reload command. Changes need a server restart.

Key	What it is for
server-name	This server's Velocity key (main, hub, build, info, ...). The plugin refuses to start while it is change-me or blank
channel-key	The CarbonChat channel to tag. Default carbon:global. The channel must be cross-server
metadata-key-prefix	Start of the Redis key names. Leave as is
metadata-ttl-seconds	How long the "sent from" record lives in Redis. Minimum 5, default 120
redis.use-carbonchat-config	true (normal): read the Redis login from CarbonChat's own plugins/CarbonChat/config.conf
redis.host, port, username, password	Only used when use-carbonchat-config is false

With use-carbonchat-config: true the redis: login lines are ignored, so the placeholder password there is unused. Do not put real Redis passwords in this file unless you turn that off.

Data and storage

Short-lived Redis keys only, in the same Redis that CarbonChat uses for cross-server messaging:

<metadata-key-prefix>:<channel-key>:<sender uuid>:<sha256 of the rendered message>

Each key holds the sending server's name and expires after metadata-ttl-seconds. Nothing is saved on disk. Deleting these keys is safe; at worst a message shows without a tag.

Troubleshooting

Symptom	Cause	Fix
Set server-name in config.yml to the Velocity backend key... and the plugin disables	server-name is still change-me	Set it and restart
CarbonChat is not available; disabling CarbonServerPrefixBackend.	CarbonChat failed to load	Fix CarbonChat first
UnknownDependencyException ... [CarbonChat]	CarbonChat is not installed on this server	Rename carbonserverprefixbackend.jar to .disabled
Failed to connect to Redis ...	Redis is down, or the login in CarbonChat's config.conf is wrong	Fix Redis or CarbonChat's messaging-settings, then restart
Could not parse Redis host/port from CarbonChat messaging-settings	CarbonChat config layout changed	Check the url= and port= lines in that block
Remote player name and message show dark grey	Old 1.0.0 jar still loaded	Install 1.0.1 or later and restart
No tags at all	Channel is not carbon:global, or it is not cross-server	Fix channel-key or the CarbonChat channel

A good boot logs:

Registered CarbonChat backend prefix bridge for server 'build' on channel 'carbon:global'.

Maintainer notes

• How matching works: on the sending server the plugin hashes the message as rendered for the sender and stores the server name under that hash. On the receiving server, CarbonChat hands over the same rendered line, so the hash matches.
• It uses CarbonChat's internal CarbonChatEventImpl class (to know whether a message is local). That class has no compatibility promise, so check the first boot after any CarbonChat update. It was checked against CarbonChat 3.0.0-beta.28 and beta.32.
• The live jar file is named carbonserverprefixbackend.jar with no version. When replacing it, overwrite that name. Uploading a second jar with a different name gives a duplicate-plugin error.
• 1.0.1 fix: the tag must be built on an unstyled Component.empty() root. A colored root makes the remote name and message inherit dark grey. Do not "fix" it by forcing white, which would also flatten rank colors.
• A companion proxy project lives in third_party/carbonchat-cross-server-prefix (ops repo).

Building

build.gradle.kts here declares no dependencies and has no Gradle wrapper, so gradle build does not compile as committed. It needs compileOnly entries for the Paper API and CarbonChat (API and common), plus a shaded Jedis client. The 1.0.1 jar was made by swapping the rebuilt ServerPrefixFormatter.class and plugin.yml into the earlier 1.0.0 fat jar (Jedis is shaded inside it). Java 21.

Full command, permission and config tables: Reference.