Channels

A channel is a named broadcast scope with its own format, permission, cooldown, and optional custom command. Players subscribe to channels to receive their messages and use the channel's command (or the default channel's slash-chat) to send.

Channel YAML

channels:
  staff-chat:
    name: "staff"
    format: "<gray>[<#659ccc><bold>Staff</bold></#659ccc>]</gray> <#659ccc>%displayName%<gray>:<reset> <#7ec3ff>%message%"
    permission: "chat.channel.staff"
    command: "chatstaff"
    filtered: false
    cooldown: "0s"
    auto-subscribe: true

Fields

Field	Type	Required	Description
`name`	String	Yes	Runtime identifier used in `/subscribe <name>`, `/channel broadcast <name>`, and `%chat_subscribed_<name>%`.
`format`	MiniMessage	Yes	Per-message format. See Format variables.
`default`	boolean	One channel must be `true`	The fallback channel for plain chat. Picked by the first match of `default: true` — set exactly one.
`permission`	String	No	Permission required to use and (currently) subscribe to the channel.
`command`	String	No	Registers an alias command — e.g. `command: "chatstaff"` adds `/chatstaff <message>`.
`cooldown`	Duration	Yes	Minimum gap between messages a single player can send in this channel. `0s` disables it.
`filtered`	boolean	Yes	When `true` the filters in `filters.yml` are applied to messages in this channel.
`auto-subscribe`	boolean	Yes	Reserved — see Subscription for current behaviour.

Format variables

Inside a channel format, the following placeholders are available:

Variable	Source	Value
`%message%`	Renderer	The (possibly filter-modified) chat body.
`%displayName%`	Renderer	The sender's Adventure display name.
`%chat_prefix%`	AstralChat placeholder	LuckPerms prefix of the sender's highest staff > paid > free group.
`%chat_equippedTag_component%`	AstralChat placeholder	The MiniMessage component of the sender's equipped tag (empty if none).
`%chat_*%`	AstralChat placeholder	Any other chat placeholder.
`%*%`	PlaceholderAPI	Any other registered PAPI expansion.

Subscription

Players opt in to channels via /subscribe <name> and out via /unsubscribe <name>. Subscription state is stored on the player's PlayerChatData and persisted by AstralSync, so it survives reconnects and server hops.

%chat_subscribed_<name>% returns true/false for the viewing player — useful in menu visibility requirements.

Custom commands

If a channel sets command:, AstralChat registers a per-channel ACF command with that name. The command takes the rest of the line as the message:

/chatstaff Hello team!

When the command fires:

The channel's permission is checked (if set).
The sender's mute status is queried via LiteBans (asynchronously).
The message is parsed as MiniMessage, rendered through AstralChatRenderer, and broadcast as a non-default channel message.

The default channel — the one with default: true — does not need a custom command; plain / chat goes through it.

Cooldowns

Cooldown is enforced by ChannelListener on every channel message:

last-message timestamp + cooldown > now ?
  ├── send `channel-cooldown` message with remaining %time%
  └── cancel the event

Players holding astralchat.cooldown.bypass are exempt.

Pausing

/channel pause <name> [duration] parks a channel for a duration (default 1d). While paused, the channel rejects new messages with channel-currently-paused. /channel resume <name> lifts the pause manually. The pause is broadcast network-wide via ChannelPausePacket so every server sees it; ChannelResumePacket does the reverse.

Broadcasting

/channel broadcast <channel> <message> skips the cooldown/filter pipeline and delivers a one-off network-wide message. It is the recommended way for staff to announce in any channel without joining it.

The broadcast uses ChannelBroadcastPacket for cross-server delivery and the channel-broadcast message template for rendering.

Last modified: 25 July 2026