Rank System

The Rank System

CelestialCosmetics can render a rank as a layered image in chat and TAB, composed from up to three independently-chosen layers plus a fixed per-rank text glyph. It's written as a single prefix.<weight> node in LuckPerms, so any plugin that reads prefixes (chat, TAB, holograms) can show it.

This is an advanced, ItemsAdder-oriented feature. If you just want to color a rank name, a simple template works too (see Simple mode).

The layout

The final prefix is assembled from this template (rank-color.template in rankcolors.yml):

{effect}{background}&r{offset}{text}

Token	What it is	Chosen by
{background}	the "plate" image behind the rank (an ItemsAdder glyph)	the player equips a Rank Background
{effect}	a color / shader-trigger code that tints the background	the player equips a Rank Effect
&r	a reset so the effect doesn't bleed onto the text	fixed in the template
{offset}	moves the text left onto the background	per-rank number
{text}	the rank's fixed text glyph (e.g. an OWNER image)	fixed per LuckPerms group

So the player picks a background and, separately, an effect that recolors it; the text of the rank is fixed per rank; and the offset slides the text onto the plate.

Why the &r matters: effect codes (especially shader-trigger hex like &#F0F0xx) would otherwise continue past the background and displace/recolor the text. The reset stops the effect at the background. Keep it in your template.

The offset — chat vs TAB

ItemsAdder exposes offsets in two forms, and each consumer needs its own:

• Chat → :offset_-40: (parsed by ItemsAdder's chat listener)
• TAB → %img_offset_-40% (a PlaceholderAPI placeholder TAB resolves)

You only store the number; the plugin builds the right form for each placeholder:

rank-color:
  offset-format-chat: ':offset_{n}:'
  offset-format-tab: '%img_offset_{n}%'

Then use the two placeholders accordingly:

• %celestial_rank% in your chat format
• %celestial_rank_tab% in TAB (tabprefix) — enable TAB's nested-placeholder support so the inner %img_offset% resolves.

Per-rank configuration (rankcolors.yml)

rank-color:
  weight: 200                 # prefix weight (must be higher than base rank prefixes)
  apply-on-join: false        # write the rank image for every mapped rank on join
  template: '{effect}{background}&r{offset}{text}'
  offset-format-chat: ':offset_{n}:'
  offset-format-tab: '%img_offset_{n}%'
  luckperms-prefix-variant: chat   # which form is baked into the LuckPerms prefix
  offset: ''                  # global fallback offset number
  default-effect: ''          # raw fallback when no effect is equipped
  default-background: ''       # raw fallback when no background is equipped
  ranks:
    owner:
      name: 'Owner'            # plain name (used by %celestial_rankname% and if text is blank)
      text: 'ꃼ'               # the ItemsAdder rank-text glyph
      background: '𞄊'          # this rank's DEFAULT background glyph (sized to its text)
      offset: -53              # offset number for THIS rank's tag
    manager:
      name: 'Manager'
      text: 'ꈋ'
      background: '𞄒'          # a wider plate — MANAGER is a longer word
      offset: -60
    default:
      name: 'Member'
      text: 'ü'
      background: ''
      offset: -40
  colors:                     # the EFFECTS players can equip (RANKCOLOR)
    gold:
      display: '&6Gold'
      value: '&6'             # or a shader-trigger hex like &#F0F03C
      icon: GOLD_INGOT
      permission: celestial.cosmetics.rankcolor.gold

How each layer resolves

• Effect = the equipped Rank Effect's value, else rank-color.default-effect.
• Background = the equipped Rank Background's value (if allowed for the rank), else the rank's own background, else rank-color.default-background.
• Offset = the rank's offset, else the global rank-color.offset. (A per-background offset can override it — see Rank Backgrounds.)
• Text = the rank's text glyph; if blank, the plain name is shown so nothing breaks before you add glyphs.

Simple mode

Don't use ItemsAdder? Set a plain template and leave the glyphs empty:

rank-color:
  template: '{effect}{rank} '
  ranks:
    owner: { name: '[Owner]' }
  colors:
    gold: { display: '&6Gold', value: '&6', icon: GOLD_INGOT }

{rank} = the rank's name. The player equips an effect (a color) that recolors the rank name. That's the classic "rank color" behaviour.

Placeholders

Placeholder	Returns
%celestial_rank%	the full assembled rank image, chat form (:offset:)
%celestial_rank_tab%	the same image, TAB form (%img_offset%)
%celestial_rankname%	the plain rank name, no color
%celestial_rankcolor%	the equipped effect code
%celestial_rankbg%	the equipped background glyph

Notes

• apply-on-join: true writes the image for every mapped rank on join, so ranks show out of the box (not only after equipping something). Leave it false while you're still filling in glyphs so it doesn't override your current prefix.
• The rank glyphs (background, text) and offsets come from your ItemsAdder pack. Size each rank's background to its text width, then dial the offset once per rank.

---

Next: Rank Backgrounds