Placeholders

AstralChat registers three placeholder namespaces with AstralCore: chat_* (network-wide queries), channel_* (per-channel queries), and tag_* (per-tag queries). For the underlying placeholder syntax (%a_b_c%, %a_{b_c}%, $e(...)), see Placeholders.

`chat_*`

Placeholder	Type	Description
`%chat_prefix%`	Component	The LuckPerms prefix of the viewer's highest-weight group within `groups.yml`. Walks staff → paid (if `showPaidRoles` is on) → free.
`%chat_equippedTag%`	ChatTag	The viewer's equipped tag, or empty when none. Chain into `%chat_equippedTag_component%`.
`%chat_equippedTag_component%`	Component	Shorthand for the badge component — what you almost always want in a channel format.
`%chat_subscribed_<channel>%`	Boolean	`true` if the viewer is subscribed to that channel.
`%chat_privateMessagesEnabled%`	Boolean	Reflects `/togglepm`.
`%chat_mentionsEnabled%`	Boolean	Reflects the `toggle-chat-mentions` action.
`%chat_showPaidRoles%`	Boolean	Reflects the `toggle-paid-roles` action.
`%chat_tags%`	ItemProvider	Every tag in `tags.yml`, ready to be used as a layout `provider`. Sorted so the tags the viewer already owns (i.e. holds the `permission` for) come first, then by tag id — a tag menu therefore opens on what the player can actually equip.
`%chat_channels%`	ItemProvider	Every channel from `config.yml`.
`%chat_channel_<key>%`	ChatChannel	The channel under that map key in `config.yml` — the YAML key, not the `name` field (`%chat_channel_staff-chat%`, not `%chat_channel_staff%`). Chain into `%chat_channel_staff-chat_format%`, etc.
`%chat_additionalPrefixes%`	Component	The concatenation of every `additional-prefixes` entry from `groups.yml` whose key the viewer holds as a permission — cosmetic badges appended next to the rank prefix. Empty when none match.

%chat_prefix% is the integration point with LuckPerms. The plugin reads groups.yml to know which group names belong to which bucket and picks the highest-weight match among the player's inherited groups:

additional-prefixes:
  group.classic: "%img_icons:galaxie%"

permissions:
  staff: [moderator, admin]
  paid:  [vip, mvp]
  free:  [default, member]

Resolution walks staff → paid (only when the viewer's showPaidRoles toggle is on) → free, and within a bucket picks the highest-weight inherited group whose weight does not exceed the viewer's primary group weight. additional-prefixes is a separate map: its keys are plain permission nodes, not group names, and every match contributes its component to %chat_additionalPrefixes%.

`channel_*`

A ChatChannel placeholder. The base form (%chat_channel_<name>%) returns the channel itself; chain keys to drill into it.

Placeholder	Type	Description
`%channel_name%`	String	The channel's runtime name.
`%channel_format%`	ComponentWrapper	The MiniMessage format.
`%channel_default%`	Boolean	`true` for the default channel.
`%channel_permission%`	String	Required permission, or null.
`%channel_command%`	String	Custom command name, or null.
`%channel_cooldown%`	Duration	Cooldown duration.
`%channel_filtered%`	Boolean	Whether filters apply.
`%channel_autoSubscribe%`	Boolean	Value of the YAML flag.
`%channel_subscribed%`	Boolean	`true` when the viewer is subscribed.

Typical use in a menu layout that lists every channel:

layouts:
  channels:
    provider: "%chat_channels%"
    taint: "channel"

items:
  channel-item:
    taints: [ "channel" ]
    item-stack:
      material: PAPER
      name: "%channel_name%"
      lore:
        - "<gray>Cooldown: <white>%channel_cooldown%"
        - "<gray>Filtered: <white>%channel_filtered%"
        - "<gray>Subscribed: <white>%channel_subscribed%"
    actions:
      LEFT:
        - "[player] subscribe %channel_name%"

`tag_*`

A ChatTag placeholder, used inside the %chat_tags% layout.

Placeholder	Type	Description
`%tag_id%`	String	Tag id.
`%tag_component%`	Component	The badge.
`%tag_description%`	List<Component>	Lore lines.
`%tag_permission%`	String	Required permission, or null.
`%tag_equipped%`	Boolean	`true` when this is the viewer's currently-equipped tag.

layouts:
  tags:
    provider: "%chat_tags%"
    taint: "tag"

items:
  tag-item:
    taints: [ "tag" ]
    item-stack:
      material: NAME_TAG
      name: "%tag_component%"
      lore: "%tag_description%"
    view-requirements:
      - "[permission] %tag_permission%"
    actions:
      LEFT:
        - "[equip-chat-tag] %tag_id%"

Last modified: 03 September 2026