Chat formats

Two-file system

StarChat splits formatting into mapping (who uses what) and definition (what does it look like).

• formats.yml — maps LuckPerms groups (or permissions) to format keys, with a weight system to break ties.
• format-components.yml — defines the actual layout of each format key. Multi-part: prefix, name, message, with per-part hover and click.

1 · Map a rank

formats:
  default:
    group: default        # Falls back here if no other format matches
    weight: 1
    chat-format: default_format

  helper:
    group: helper
    weight: 50
    chat-format: helper_format

  mod:
    group: mod
    weight: 60
    chat-format: mod_format

  admin:
    group: admin
    weight: 80
    chat-format: admin_format

  owner:
    group: owner
    weight: 100
    chat-format: owner_format

Permission-based instead of group-based

If you don't use LuckPerms groups for chat, swap group: for permission::

vip:
  permission: starchat.format.vip
  weight: 40
  chat-format: vip_format

2 · Define the layout

Each format is a list of numbered parts that render left-to-right. Each part can have its own hover tooltip and click action. Use {message} as the placeholder for the actual message content.

components:
  helper_format:
    '1':
      message: '&#B8E6C8&lHELPER &f%player_name% &8» '
      hover-message: |
        &#FCEB5C&lPLAYER
        &8▮ &fNᴀᴍᴇ &7%player_name% &c❤
        &8▮ &fRᴀɴᴋ &7%luckperms_prefix% &5🛡
        &f
        &#FCEB5C&l→ &rᴄʟɪᴄᴋ ᴛᴏ ᴅᴍ
      action: SUGGEST_COMMAND:/msg %player_name%
    '2':
      message: '&f{message}'
      hover-message: |
        &#FCEB5C&lREPORT MESSAGE&r
        &fIf this violates the rules, report.
        &7   &#FCEB5C&l→ &rᴄʟɪᴄᴋ ᴛᴏ ʀᴇᴘᴏʀᴛ
      action: RUN_COMMAND:/discord

Result in chat

Color codes

StarChat parses three syntaxes interchangeably — pick whichever you prefer:

• Hex: &#RRGGBB for any of 16 million colors. &#F8E593.
• Legacy: &0–&f for the 16 vanilla colors plus &l/&o/&n/&m/&r for format codes.
• MiniMessage: <gradient:red:gold>text</gradient>, <hover:show_text:'tooltip'>, <click:run_command:'/cmd'>.

Click actions

SUGGEST_COMMAND:/msg %player_name%   # puts text in the chat box
RUN_COMMAND:/spawn                   # runs immediately
OPEN_URL:https://example.com         # opens browser
NONE                                 # disables click

Available placeholders

Anything PlaceholderAPI exposes. Common ones used in formats:

• %player_name%, %player_uuid%, %player_displayname%
• %luckperms_prefix%, %luckperms_suffix%, %luckperms_primary_group_name%
• %vault_eco_balance_formatted% (requires Vault + economy plugin)
• %player_ping%, %player_world%, %statistic_player_kills%
• Inside {message} only: {message} itself plus any custom token from placeholders.yml.

Internal formats

Some channels reference fixed formats:

internal-formats:
  public-chat:        chat-format: default_format
  staff-chat:         chat-format: staffchat_format
  private-chat:       chat-format: private_message_format

Edit those keys to change DM and staff-chat layout — they share the same component grammar as player formats.

Fallback behaviour

If no rank matches, StarChat checks fallback-to-luckperms in settings.yml. When true, it uses the player's LuckPerms prefix as the format prefix. When false, the default_format applies as-is.