Installation

Setting up ChatColor on your Minecraft server is a quick and easy process.

Requirements

  • Server Software: Paper (recommended) or Spigot 1.21+
  • Java Version: Java 21 or newer.
  • Optional Dependencies: PlaceholderAPI for additional placeholder support.

Platform support

Platform Supported Notes
Paper 1.21+ ✅ Full Recommended. Uses the modern chat pipeline for exact gradient rendering.
Folia ✅ Full Region-thread safe. See Chat Compatibility.
Canvas ✅ Full Declared supported in plugin.yml.
Spigot 1.21+ ⚠️ Limited No modern chat event, so gradients are approximated to the nearest of the 16 named colors.

Setup Steps

  1. Download: Get the latest ChatColor.jar file.
  2. Install: Place the .jar file into your server's plugins/ directory.
  3. Start Server: Start (or restart) your server to generate the default configuration files.
  4. Configure: Adjust the configuration files in the plugins/ChatColor/ folder (see Configuration).
  5. Reload: Use /color reload to apply any changes made to the configuration files while the server is running.

Verifying the install

On startup, ChatColor logs which chat pipeline it hooked:

[ChatColor] Chat hook: MODERN (AsyncChatEvent), priority HIGHEST

MODERN is what you want on Paper and Folia. If it says LEGACY on those platforms, check chat-hook in config.yml — it should be "AUTO".

The plugin also reports how many color permissions it registered:

[ChatColor] Registered 42 colour permission(s).

Those nodes are registered with the server at runtime, which is what lets LuckPerms tab-complete them and lets chatcolor.custom.* actually expand.

Updating

Drop the new jar in and restart. ChatColor migrates your configuration automatically: it adds any new keys, preserves your existing values, and writes a timestamped backup to backups/ first.

Use a full restart rather than a plugin reloader when updating. The chat listener binds one tick after enable so it can register after other chat plugins, and reloader plugins can break that ordering.

Troubleshooting

If colors aren't appearing in chat, run /color debug and read the console — see Chat Compatibility for how to interpret the output.