# Placeholders Reference

CelestialCosmetics registers a PlaceholderAPI expansion under the identifier `celestial`.

| Placeholder | Returns |
|---|---|
| `%celestial_tag%` | Equipped Tag value (empty if none) |
| `%celestial_emoji%` | Equipped Emoji, prefixed with a space (empty if none) |
| `%celestial_namecolor%` | Equipped Name Color code (falls back to `namecolor-default`) |
| `%celestial_namecolor_legacy%` | Same, but snapped to the nearest of the 16 legacy colors as a plain `&x` code — see [below](#namecolor_legacy-and-the-overhead-nametag) |
| `%celestial_chatcolor%` | Equipped Chat Color code (falls back to `chatcolor-default`) |
| `%celestial_rebirth%` | Fully styled rebirth/prestige display (falls back to `rebirth-default-style`, then the raw source value) |
| `%celestial_customstat1%` | Same as `%celestial_rebirth%`, but for the Custom Stat 1 slot (own placeholder, own styles — empty until configured) |
| `%celestial_customstat2%` | Same idea, Custom Stat 2 slot |
| `%celestial_customstat3%` | Same idea, Custom Stat 3 slot |
| `%celestial_rank%` | Full rank image for **chat** (`{effect}{background}:offset:{text}`) |
| `%celestial_rank_tab%` | Same rank image for **TAB** (uses `%img_offset_-N%`) |
| `%celestial_rankname%` | Plain rank name, no color |
| `%celestial_rankcolor%` | Equipped rank **effect** code |
| `%celestial_rankbg%` | Equipped rank **background** glyph |
| `%celestial_glow%` | Equipped Glow color name |
| `%celestial_set%` | Active Set name |
| `%celestial_keys_<crateId>%` | Keys the player holds for a given crate (e.g. `%celestial_keys_celestial%`) |

All placeholders resolve through [rank defaults](Rank-System) automatically — you never need to null-check them in your chat format.

## Chat format example

```yaml
"%celestial_rank% %celestial_namecolor%{name} %celestial_tag%%celestial_emoji%&8» %celestial_chatcolor%{message}"
```

## TAB

Use the dedicated **`%celestial_rank_tab%`** in TAB (not `%celestial_rank%`), because TAB resolves the `%img_offset%` form of the offset:

```yaml
# TAB groups.yml
tabprefix: "%celestial_rank_tab% "
customtabname: "%celestial_namecolor%%player%"
tagprefix: "%celestial_rank_tab% %celestial_namecolor_legacy%"
```

Enable TAB's **nested placeholder support** so the inner `%img_offset_-N%` resolves. Also make sure `placeholder-support` is on for `%celestial_rebirth%`, which resolves another placeholder internally.

Note `tagprefix` (the overhead nametag) uses `%celestial_namecolor_legacy%`, not the plain hex one — see why right below.

### `%celestial_namecolor_legacy%` and the overhead nametag

Minecraft's real overhead nametag (the text floating above a player's head) can **only** render one of the 16 legacy colors — a hard client limitation that applies no matter which plugin builds it, TAB included. Feeding it `%celestial_namecolor%` (arbitrary hex) silently fails to apply any color there, even though the exact same hex works fine in chat, the tablist, and menus.

`%celestial_namecolor_legacy%` rounds the player's equipped Name Color to whichever of the 16 legacy colors is closest, so it's safe to use anywhere a scoreboard team's color field is involved (a nametag plugin's `tagprefix`, or anything else building on vanilla teams). Everywhere else — chat, tablist, GUIs — keep using the full-color `%celestial_namecolor%`.

## Chat vs TAB offset — why two placeholders

ItemsAdder offsets come in two forms: `:offset_-40:` (chat listener) and `%img_offset_-40%` (PlaceholderAPI / TAB). `%celestial_rank%` emits the first, `%celestial_rank_tab%` the second — same image, correct for each consumer. See [The Rank System](Rank-System).

## Legacy color bleed

Legacy color codes don't auto-reset. Put `%celestial_namecolor%` **immediately** before the name, or the name may inherit a color from whatever came before it.

---

Next: [Economy Integration](Economy-Integration)