PlayerWaypointColors

Overview

PlayerWaypointColors lets players set their own waypoint colors and lets admins set colors for other players. Optional PlaceholderAPI integration for automatic color assignment on join, exporting a player's current color to other plugins (chat, scoreboards, etc.), and configurable server defaults.

Features

• Assign custom hex colors to player waypoints (e.g., #FF0000 or FF0000 for red)
• Simple commands for players and admins
• Configurable default color applied to players on join
• Optional PlaceholderAPI integration:
  • Read a player's color from a placeholder on join (e.g., from LuckPerms meta)
  • Export the player's current color via %pwc_color_<format>% so other plugins can use it (MiniMessage, hex, raw, legacy spigot, or any custom format you define)

Compatibility

• Minecraft: Spigot 1.21.11+ or Paper 1.21.11+
• Optional: PlaceholderAPI

Installation

1. Download the latest PlayerWaypointColors.jar.
2. Place it in your server's plugins folder.
3. (Optional) Install PlaceholderAPI if you want PAPI features.
4. Start or reload your server.

Commands & Permissions

Configuration

The plugin creates a config.yml file on first run. Existing files are upgraded in place when new options are added.

Example config:

placeholderapi:
  auto-apply-on-join: false
  variable: ""
placeholders:
  formats:
    minimessage: "<#{HEX}>"
    hex: "#{HEX}"
    raw: "{HEX}"
    legacy: "&x&{R1}&{R2}&{G1}&{G2}&{B1}&{B2}"
default-color: ""
default-color-force: false

PlaceholderAPI Integration

PWC integrates with PlaceholderAPI in both directions: it can read a placeholder to assign a color on join, and it exposes its own placeholder so other plugins can read each player's current color.

Reading colors from a placeholder (auto-apply on join)

Set variable in config.yml to a placeholder (e.g., %luckperms_meta_color%) that returns a hex code in the format #00FF00 or 00FF00.

The easiest setup uses LuckPerms meta:

1. Set the permission meta.color.#FF0000 on a group
2. Set auto-apply-on-join to true
3. Set variable to %luckperms_meta_color%
4. Save config.yml and restart your server

Alternatively, use the PlaceholderAPI String expansion (particularly %string_replaceCharacters_<configuration>_<string>%) to coerce another placeholder into a valid hex code.

Exposing a player's current color to other plugins

PWC registers %pwc_color_<format>% where <format> is any key under placeholders.formats in config.yml. Out of the box:

Add your own keys in config.yml to support whatever syntax your chat or scoreboard plugin needs. Templates can use these variables (case-sensitive):

• {HEX} — uppercase 6-char hex (e.g. FF0000)
• {hex} — lowercase 6-char hex (e.g. ff0000)
• {R1} {R2} {G1} {G2} {B1} {B2} — each channel split into its two hex digits

Example: a chat plugin using <#hex> MiniMessage syntax can format messages like %pwc_color_minimessage%<player_name></...> to color player names with each player's chosen waypoint color.

If a player hasn't picked or been assigned a color, the placeholder returns an empty string regardless of the format requested.

Default Color on Join

Set default-color to a hex value (e.g. 00FF00) to apply that color to players who don't already have one. Leave empty to disable.

default-color-force:

• false (default): only applies the default if the player has no color set. Won't overwrite a color they picked with /pwc set.
• true: applies the default on every join, overwriting whatever color the player previously had — except a color set by auto-apply-on-join above, which always wins.