Formats

A format is a whole chat line, described by a file under chat/formats/. The file name is the format name: vip.yml is the format vip. Two ship — default.yml and msg.yml — and both are rewritten on the first start if they are missing.

A file is one format, or several

A file with components: at its root is one format, named after the file.

A file without one is read block by block: each top-level block that has a components: section becomes a format named file.block. That is how msg.yml produces msg.sender and msg.receiver. A block format never takes part in the weight contest below — it is asked for by name, by the feature that needs it.

permission: exyliachatcosmetics.chat.format.vip   # empty = everybody
weight: 10                                        # heaviest qualifying format wins
per-viewer: false                                 # true renders the line once per reader
components:
  '1':
    text: '{tag}{nick} {letters_black}» '
    hover:
      - '{secondary}Player'
      - ' {letters_black}▎ {letters}Name {letters_black}» {info}{name}'
    click: 'SUGGEST_COMMAND:/msg {name} '
  '2':
    text: '{message}'

The component keys are names, not indices; '1', '2' is a convention, not a requirement. A component with no text is skipped and reported. A format that ends up with no usable component is dropped, and if default is the one that failed the console says so and messages are sent bare.

Inside a component

A click that is not one of those four is reported when the file is read, rather than silently dropped on every message afterwards.

Tokens work in all three. A click carries its tokens as plain text, so SUGGEST_COMMAND:/msg {name} puts the player's actual name into the chat box rather than the literal {name}.

Which format a message wears

Tokens

Tokens are components, placed into the line directly — no placeholder round-trip, and a tag or a coloured name keeps its own colours instead of being flattened into a string.

Private-message formats get their own set instead: {message}, {sender}, {sender_nick}, {sender_tag}, {receiver}, {receiver_nick}, {receiver_tag}.

Braces rather than percent signs, so a token can never collide with a placeholder. A brace pair nobody claims — {primary}, {letters_black} — is left for the text engine, which reads it as a palette colour.

The colour a line was written in carries across a token: the piece before {nick} opens a colour, the token is drawn under it as a fallback, and the piece after it continues the same sentence. Anything that names its own colour, an item's name for one, still wins.

Placeholders and per-viewer

Any %placeholder% ExyliaLib or PlaceholderAPI knows works in text, hover and click. By default it resolves for the sender, because the line is about them.

Turn per-viewer: true on and the line is rendered once for each reader: %player_…% is then the reader and %target_…% stays the sender. That is the switch for a line that says something about whoever is looking at it.

A %rel_…% placeholder makes a format viewer-aware on its own, in text, hover or click, without per-viewer being set — a relational placeholder has no meaning without a reader.

Padding falls outside the hover and the click

The blanks a component is padded with are taken off both of its ends before the hover and the click go on, and put back afterwards. A gap belongs to neither of the pieces it separates.

Without that, the space in '{nick} ➞ ' sat inside the hover, and hovering the arrow answered "Player" right where the message began. The peeling happens on the rendered piece rather than on the written text, so a blank that a placeholder left behind — an empty rank prefix in '{prefix} {nick}' — falls outside the hover just the same.

This is also why msg.yml has a component that is nothing but a space between the heading and the message: a deliberate gap that answers to neither.

To check where a hover actually stops, use /cca chat line [message]. It renders your own line, sends it to you, and writes to the console the same line broken into the stretches that share a hover and a click.

What ships

default.yml

Three components, and it is a worked example of everything above.

The separator is its own component precisely so that neither the name's hover nor the message's report click reaches the arrow between them. weight: 0, no permission: everybody gets it unless a heavier format applies.

msg.yml

Two blocks, sender and receiver, giving the formats msg.sender and msg.receiver. Each has three components: a heading — [You ➜ them] on one screen, [them ➜ You] on the other — that hovers with who the message is with and clicks to SUGGEST_COMMAND:/reply , then a bare space, then {message} hovering "Click to copy it" with COPY:{message}.

Each screen is rendered with its own reader as the viewer and the other person as the placeholder target, so a hover about "them" is about the right person on both.

Related

The format permission node is on Permissions, and /cca chat line on Commands.