Installation

1. Pre-flight

Make sure these are running before installing AstralChat:

A Redis server reachable by every game server.
A RabbitMQ broker reachable by every game server.
A MariaDB or PostgreSQL database with credentials provisioned for AstralCore.
LuckPerms, CraftEngine, AstralCore, and AstralSync installed on every node that should run AstralChat (all four are hard depends — the plugin will not enable without them).
Optionally LiteBans (softdepend, used for the mute check in per-channel commands) and a moderation classifier endpoint for auto moderation.

2. Drop the JAR

Copy AstralChat-<version>.jar into the plugins/ directory of each server that should participate in chat. AstralChat reads its enabled server list from config.yml; servers that are not in enabled-groups load the plugin but stay silent — see Configuration.

3. First start

On first start the plugin generates:

plugins/AstralChat/
├── config.yml
├── messages.yml
├── filters.yml
├── groups.yml
├── moderation.yml
└── tags.yml

The menus/ folder is not generated — MenuContainer only loads what is already there. Create plugins/AstralChat/menus/ and put an ignored-list menu in it, otherwise /ignore with no argument fails with the unexpected-error message.

The database schema is applied automatically — see Database.

4. Configure

config.yml — set enabled-groups, define your channels, tweak the social-spy format. See Configuration and Channels.
messages.yml — localise every player-facing string. See Messages.
filters.yml — enable filters and set their thresholds. See Filters.
groups.yml — list your LuckPerms groups under free/paid/staff so the %chat_prefix% placeholder can pick the right prefix.
tags.yml — define equippable chat tags. See Chat Tags.
moderation.yml — point at your classifier, set thresholds, and decide what is recorded. See Auto Moderation. Leave url empty to keep the classifier off.

Reload at runtime with /chat reload or /channel reload — no restart required.

Permissions

Command permissions

Node	Command
`astralchat.broadcast`	`/broadcast`
`astralchat.channel.pause`	`/channel pause`
`astralchat.channel.resume`	`/channel resume`
`astralchat.channel.broadcast`	`/channel broadcast`
`astralchat.channel.list`	`/channel list`
`astralchat.channel.reload`	`/channel reload`
`astralchat.channel`	Required on top of every `/channel` subcommand.
`astralchat.socialspy`	`/socialspy`
`chat.command`	`/chat` and its subcommands.
`chat.command.moderation`	`/chatmod` — see Auto Moderation.
`chat.nick`	`/nick`
`chat.nick.reset`	`/nick reset <player>` (on top of `chat.nick`).

Other nodes

Node	Grants
`astralchat.cooldown.bypass`	Bypass per-channel cooldowns.
`astralchat.filters.bypass`	Skip `filters.yml` entirely.
`astralchat.ignore.bypass`	Cannot be ignored: this player's messages are always delivered, and `/ignore` refuses to target them. Resolved network-wide through LuckPerms.

/socialspy is gated by the hard-coded astralchat.socialspy node. The social-spy.permission key in config.yml is not read by the current code; only social-spy.bypass-permission (shipped default chat.socialspy.bypass) is, and it marks players who must never be spied on.

Per-channel access

The permission field on a channel definition is the runtime permission node — there is no fixed prefix. The default config.yml uses chat.channel.<name> (e.g. chat.channel.staff), but you can pick any string.

Database schema

AstralChat ships with schema.sql that creates three tables on first start:

CREATE TABLE IF NOT EXISTS ignores (
    id UUID PRIMARY KEY,
    ignorer_id UUID NOT NULL,
    ignored_id UUID NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_ignorer_ignored (ignorer_id, ignored_id),
    INDEX idx_ignored_id (ignored_id)
);

CREATE TABLE chat_messages (
    id           UUID PRIMARY KEY,
    channel      VARCHAR(32)  NULL,
    sender_id    UUID         NOT NULL,
    recipient_id UUID         NULL,
    content      VARCHAR(512) NOT NULL,
    created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_channel_time (channel, created_at),
    INDEX idx_sender_time  (sender_id, created_at),
    INDEX idx_recipient_time (recipient_id, created_at)
);

Table	Holds
`ignores`	One row per ignore relationship.
`chat_messages`	Every stored message — public channel messages (`recipient_id` null) and private messages (`channel` = `private-message`).
`flagged_messages`	One row per recorded moderation decision, plus the human labels. Its schema is documented on the Auto Moderation page.

Per-player chat state (equipped tag, toggles, subscriptions, nickname) is stored as a PlayerChatData AstralSync snapshot, not in these tables.

Last modified: 03 September 2026