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.
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.
Hide paid roles	Players can toggle their paid rank prefix on/off.
AstralCore actions	Registers five new action types usable in any menu or dialog.
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	Required for the `%chat_prefix%` placeholder and group-based features.
LiteBans	Yes	Mute status is checked before broadcasting channel messages.
RabbitMQ	Yes	Cross-server private messages, mentions, channel pause/broadcast.
Redis	Yes	Caching for ignores and player data.
MariaDB/PostgreSQL	Yes	Persistence for `ignores` and `private_messages`.
CraftEngine	Optional	Adventure component formatting integration.

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)
└── tags.yml           ← equippable chat tags

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`	Tracks last-message timestamps for per-channel cooldowns.
`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 — renders the message, filters viewers, fires mentions, fires ChannelChatEvent, broadcasts to subscribers.

Last modified: 25 July 2026