Chat Tags

Chat tags are MiniMessage badges players can equip to show up in front of their display name on every channel they speak in. Tags live in tags.yml and are exposed via %chat_equippedTag_component% so they slot into any channel format.

tags.yml

tags:
  lumberjack:
    id: "lumberjack"
    component: "<hover:show_text:'<green>Bûcheron'><green>[<bold>L</bold>]</green>"
    permission: "chat.tag.lumberjack"
    description:
      - "<gray>Awarded for completing the lumberjack questline."
      - "<gray>Use /tag to equip."

  pilier:
    id: "pilier"
    component: "<hover:show_text:'<gold>Pilier de la communauté'><gold>[<bold>P</bold>]</gold>"
    permission: "chat.tag.pilier"
    description:
      - "<gray>Long-time supporter of the network."

Fields

Field	Type	Required	Description
`id`	String	Yes	Internal identifier; must match the map key.
`component`	MiniMessage	Yes	The badge itself. Wrap with `<hover>` for a tooltip.
`description`	`List<String>` (MiniMessage)	Yes	Lore lines shown when the tag appears in a menu.
`permission`	String	No	Required to equip. Omit to make the tag freely available.

Equipping

Tags are equipped through the equip-chat-tag and unequip-chat-tag actions — typically wired to a menu:

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

The currently equipped tag is stored on PlayerChatData.chatTag (just the id) and persisted by AstralSync. On equip the player receives tag-equipped; on remove tag-unequipped.

See Actions for the full action reference.

Placeholders

Tags expose a tag_* placeholder namespace (see Placeholders). The chat-namespace shortcut %chat_equippedTag% returns the resolved ChatTag for the current viewer, and %chat_equippedTag_component% drills straight to the badge component — that is the placeholder you almost always want in a channel format.

Last modified: 25 July 2026