Town Chat

Town chat is a per-town channel routed through AstralChat. Members opt in to "town chat mode" via /town chat; while it is on, every message they type in normal chat is redirected to their selected town instead of the global channel.

Toggling redirect

/town chat # toggle on/off

State lives on TownPlayerData.chatEnabled. Confirmation messages: CHAT_ENABLED/CHAT_DISABLED.

The action equivalent is toggle-town-chat (no arguments) — useful for menu buttons.

Sending one-off messages

/town chat <message>      # send one message, ignoring the toggle
/tc <message>             # short-form shortcut

The message uses the CHAT_FORMAT template from messages.yml with placeholders for the sender's display name, the town name, and the message.

Broadcasting

/town chat broadcast <message>

Permission: CHAT_BROADCAST. Delivered to every member regardless of their selected town. Format: BROADCAST_FORMAT.

Pipeline

Player types chat
    │
    ▼
ChatListener (AsyncChatEvent, HIGH priority)
    │
    ├── if chatEnabled and player has a selected town:
    │   ├── cancel the AsyncChatEvent
    │   └── TownChatService.message(player, town, component)
    │           ├── TownChatMessagePacket published to RabbitMQ
    │           └── delivered on each server to every online member
    │
    └── otherwise: pass through to AstralChat as normal

Because the redirect happens at HIGH priority before AstralChat's render listener, town chat avoids the channel formatter / filter pipeline — town messages are not seen by social spy and are not affected by global filters. Use the CHAT_FORMAT template for any formatting you need.

Cross-server delivery

TownChatMessagePacket carries the rendered component and the town UUID. The recipient server resolves the town from its cache, then loops over the local online members and delivers the component. Members on the originating server receive it through the same packet to keep the rendering pipeline single-pathed.

Placeholder

%towns_chatEnabled% returns the viewer's current toggle state — useful for menu visibility:

items:
  toggle:
    item-stack:
      material: NAME_TAG
      name: "Town chat: %towns_chatEnabled%"
    actions:
      LEFT:
        - "[toggle-town-chat]"

Last modified: 25 July 2026