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

- Optional: Spigot 1.21.11+ or Paper 1.21.11+ - Optional: Optional:

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

| Command | Description | Permission | Default | |--------------------------------------------------|--------------------------------------------|-----------------------------|---------| | `/pwc help` | Show help message | playerwaypointcolor.help | all | | `/pwc set <color|hex> [#hexcode]` | Set your own waypoint color | playerwaypointcolor.self | OP | | `/pwc setother <player> <color|hex> [#hexcode]` | Set another player's waypoint color | playerwaypointcolor.others | OP | | `/pwc get` | Get your own waypoint color | playerwaypointcolor.self | OP | | `/pwc get <player>` | Get another player's waypoint color | playerwaypointcolor.others | OP | | `/pwc reset` | Reset your own waypoint color | playerwaypointcolor.self | OP | | `/pwc reset <player>` | Reset another player's waypoint color | playerwaypointcolor.others | OP |

Configuration

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

Example config: ```yaml 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 exposes 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:

| Placeholder | Returns | Example | |---------------------------|---------------------------|------------------| | `%pwc_color_minimessage%` | MiniMessage hex tag | `<#FF0000>` | | `%pwc_color_hex%` | hex with leading `#` | `#FF0000` | | `%pwc_color_raw%` | bare 6-character hex | `FF0000` | | `%pwc_color_legacy%` | Spigot legacy color codes | `&x&F&F&0&0&0&0` |

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.