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, LiteBans, AstralCore, and AstralSync installed on every node that should run AstralChat.

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
└── tags.yml

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.

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.cooldown.bypass`	Bypass per-channel cooldowns.

The social-spy permission nodes are configurable in config.yml (social-spy.permission and social-spy.bypass-permission). The shipped defaults are chat.socialspy and chat.socialspy.bypass.

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 two 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 IF NOT EXISTS private_messages (
    id UUID PRIMARY KEY,
    sender_id UUID NOT NULL,
    recipient_id UUID NOT NULL,
    message JSON NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_sender_created (sender_id, created_at DESC),
    INDEX idx_receiver_created (recipient_id, created_at DESC),
    INDEX idx_created (created_at)
);

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

Last modified: 25 July 2026