Installation

1. Pre-flight

Ensure these are reachable from every node:

A MariaDB or PostgreSQL instance with credentials provisioned for AstralCore.
Redis (any 6+ build).
RabbitMQ.
AstralCore, AstralSync, and AstralChat installed and configured.

2. Drop the JAR

Copy AstralTown-<version>.jar into plugins/ on every server that should host towns. AstralTown reads its enabled server list from servers.yml.

3. First start

On first start the plugin generates:

plugins/AstralTown/
├── config.yml
├── messages.yml
├── settings.yml
├── permissions.yml
├── roles.yml
├── servers.yml
├── logs.yml
├── database.properties
└── menus/

The database schema (12 tables) is applied automatically on the first connection:

Table	Purpose
`towns`	One row per town (name, owner, spawn, MOTD).
`members`	Town membership rows.
`roles`	Town and subzone roles.
`role_permissions`	Many-to-many between roles and `PermissionType`.
`claims`	One row per claimed chunk.
`subzones`	Cuboid regions.
`subzone_members`	Subzone membership.
`subzone_roles`	Subzone-scoped roles.
`subzone_settings`	Per-subzone `TownSettings` overrides.
`invitations`	Pending invitations with expiry.
`town_bans`	Banned-from-town records.
`warps`	Warp definitions.
`warp_visits`	Per-warp visit tracking.
`town_logs`	Audit log with typed JSON payloads.

Per-player state (selected town, chat toggle, favourite warps, member-notification toggle) is stored as the TownPlayerData AstralSync snapshot, not in these tables.

4. Configure

Walk through the configuration files in this order:

servers.yml — list the groups where AstralTown is active.
config.yml — name length / pattern, claim limits, claim cost formula, wilderness rules, per-permission town quotas. See Configuration.
roles.yml — seed roles every new town gets. See Roles.
permissions.yml and settings.yml — UI icons for the permission/setting menus.
messages.yml — localise the 193 strings. See Messages.
menus/ — every screen players see is an AstralCore menu; tweak freely.

Reload at runtime with /town reload or the relevant subcommand — restart only when changing the database, Redis, or RabbitMQ.

Permissions

There is no fixed astraltown.* permission tree because every action is gated by the town's role-based PermissionType. The two operational permissions you may want to grant explicitly:

Node	Scope
`town.admin`	Bypass town role checks (staff).
`town.create.*`	Town-creation quotas (see `creation.quotas.permissions` in `config.yml`).

See PermissionType in Roles for the full role-based permission catalogue.

Last modified: 25 July 2026