AstralChat Overview

AstralChat is the network-wide chat plugin for AstralRealms. It replaces vanilla chat with a configurable channel system, cross-server private messaging, filters, tags, mentions, and a public API that other plugins can hook into.

What it provides

Feature	Summary
Channels	YAML-defined chat channels with their own format, permission, cooldown, and optional custom command.
Private messages	`/msg`, `/reply`, `/togglepm`, `/ignore`, network-wide via RabbitMQ.
Social spy	Staff command to monitor private messages with bypass permissions.
Filters	Regex, caps, and similarity filters with configurable per-violation actions.
Auto moderation	Every stored message is scored by a remote classifier; hits notify staff and are recorded, with a sampled set of clean ones, as a labellable training set.
Message archive	Public channel messages and private messages are persisted to `chat_messages`.
Mentions	`@name` mentions deliver a sound, title, and message across servers.
Chat tags	YAML-defined prefix tags players can equip via menu actions.
Nicknames	`/nick`, with a 16-character cap and a character whitelist; staff can reset another player's.
Hide paid roles	Players can toggle their paid rank prefix on/off.
AstralCore actions	Registers five action types — four globally, one plugin-scoped.
Developer API	Public services, a cancellable `ChannelChatEvent`, and a `chat` placeholder namespace.

Requirements

Dependency	Required	Notes
Paper 1.21+	Yes	`api-version: 1.21`
AstralCore	Yes	Menus, configuration, action framework, placeholders.
AstralSync	Yes	Persists `PlayerChatData` (tag, nickname, toggles, subscriptions).
LuckPerms	Yes	`depend`. Required for `%chat_prefix%`, the group buckets, and the network-wide ignore bypass lookup.
CraftEngine	Yes	`depend`. Emoji and item-hover formatting in rendered messages.
LiteBans	Optional	`softdepend`. Mute status is checked in the per-channel commands only — the default channel has no mute check yet.
RabbitMQ	Yes	Cross-server private messages, mentions, channel pause/broadcast.
Redis	Yes	Caching for ignores and player data.
MariaDB/PostgreSQL	Yes	Persistence for `ignores`, `chat_messages` and `flagged_messages`.
A moderation classifier	Optional	The endpoint `moderation.yml` points at. Without it, the classifier half of auto moderation stays off.

Architecture at a glance

plugins/AstralChat/
├── config.yml         ← enabled groups, global formats, channels, social spy
├── messages.yml       ← all player-facing strings
├── filters.yml        ← whitelist + filter definitions
├── groups.yml         ← LuckPerms group buckets (free / paid / staff)
├── moderation.yml     ← classifier endpoint, thresholds, notifications, dataset
├── tags.yml           ← equippable chat tags
└── menus/             ← the ignored-list menu (not generated — you create it)

Service	Responsibility
`ChannelService`	Pause/resume/broadcast channel messages, schedule auto-resume.
`PaperChatService`	Renders and broadcasts the actual chat component to viewers.
`PrivateMessageService`	Routes `/msg` requests through RabbitMQ to the recipient's server.
`IgnoreServiceImpl`	Reads/writes the `ignores` table; preloaded into Redis on join.
`FilterService`	Runs each registered `ChatFilter` against incoming messages.
`MentionService`	Detects `@name` substrings and delivers cross-server mention notifications.
`TagService`	Loads `tags.yml` and provides lookup by id.
`ModerationService`	Two jobs: the recent-message cache the similarity filter and the cooldowns read, and the HTTP call to the moderation classifier.
`AutoModerationService`	Applies the local thresholds, notifies staff, and records decisions into `flagged_messages`.
`MessageStorageService`	Persists chat and private messages to `chat_messages`, and hands each one to auto moderation.
`PlayerService`	Caches `PlayerChatData` (subscriptions, toggles, equipped tag).

The chat pipeline is driven by three Bukkit listeners:

ChannelListener — enforces pause state and per-channel cooldown.
FiltersListener — runs filters when the channel has filtered: true.
DefaultChannelChatListener — hands the message body to PaperChatService, which fires ChannelChatEvent (filters run there), renders the final line, broadcasts it to the other servers, caches it for the similarity filter and stores it; the listener then trims the viewer list and fires mentions.

Filters only ever see the player's own words: the component handed to ChannelChatEvent is the unrendered message body, and the final line is rendered from whatever the filters left of it, so a prefix or a display name can never be censored.

Setting disable-all-chat-channels: true in config.yml skips all three listeners, registers no per-channel command, and drops incoming cross-server chat packets — useful on a server that must load the plugin for its API and its private messages without taking over chat.

Last modified: 03 September 2026