AstralTown Overview

AstralTown is the land-claim, town-governance, and player-organisation plugin for AstralRealms. Players create towns, claim chunks, define roles, invite members, build subzones with their own rules, drop warps, and run a town bank — all driven from YAML configuration and the AstralCore action / placeholder framework.

Highlights

Area	Summary
Towns	Create, rename, MOTD, spawn, ownership transfer, disband — fully network-aware.
Roles	Per-town role registry with 83 typed permissions and configurable default roles.
Members	Invitation flow, kick, leave, bans with reasons, online roster.
Claims	Per-chunk claims with adjacency rules, distance-from-spawn floor, formula-based cost.
Settings	27 togglable environment flags (PvP, mob spawning, fire spread, …) per town.
Subzones	Cuboid regions inside a town with their own roles, members, and setting overrides.
Warps	Town-defined teleport points, weekly-visit tracking, per-player favourite pins.
Bank	Deposit / withdraw economy.
Town chat	Private chat channel routed through AstralChat.
Audit logs	Typed `LogPayload` records for every meaningful change.
Visualisation	Particle borders around claims and subzones + BlueMap polygons.
API	`TownAPI` static accessors, custom Bukkit events, 22 registered AstralCore actions, dedicated placeholder namespaces.

Requirements

Dependency	Required	Notes
Paper 1.21+	Yes	—
AstralCore	Yes	Menus, dialogs, actions, placeholders, configuration framework.
AstralSync	Yes	Persists `TownPlayerData` (selected town, chat toggle, favourite warps).
AstralChat	Yes	Town chat is wired through the `AsyncChatEvent` pipeline.
MariaDB / PostgreSQL	Yes	Twelve tables, schema applied automatically.
Redis	Yes	Distributed cache for towns, claims, members.
RabbitMQ	Yes	Cross-server synchronisation of mutations.
BlueMap	Optional	When present, claims are rendered as 3D polygons on the web map.

Architecture at a glance

plugins/AstralTown/
├── config.yml         ← town creation rules, claim cost, wilderness, quotas
├── messages.yml       ← 193 message keys
├── settings.yml       ← TownSettings UI icons + default settings
├── permissions.yml    ← PermissionType UI icons
├── roles.yml          ← seed roles (display name, permissions, default)
├── logs.yml           ← LogType UI icons
├── servers.yml        ← per-server overrides
└── menus/             ← AstralCore menu YAMLs

Services exposed by the plugin

Getter	Use
`towns()`/`TownService`	Town CRUD, name validation, network sync.
`claims()`/`ClaimService`	Chunk claim management, cost formula, auto-claim.
`roles()`/`RoleService`	Role create / edit / delete dialog flow.
`members()`/`MemberService`	Invitations, kicks, role assignment.
`invitations()`/`InvitationService`	Invitation lifecycle.
`bans()`/`BanService`	Per-town bans.
`bank()`/`BankService`	Deposit / withdraw.
`warps()`/`WarpService`	Warp CRUD + visit tracking.
`subZones()`/`SubZoneService`	Subzone creation, edit, members, roles.
`settings()`/`SettingsService`	Town settings toggle + dirty tracking.
`chat()`/`TownChatService`	Town chat broadcast, cross-server.
`logs()`/`LogService`	Audit-log writes & queries.
`particles()`/`ParticleService`	Particle visualisation jobs.
`menus()`/`MenuService`	Menu container.

See Developer API for the full surface.

Pipeline overview

Player action ─► Command / Action
                 │
                 ▼
              Service layer (Bukkit-aware)
                 │
                 ├── permission check (Town.hasPermission(player, type, location))
                 ├── repository write (DB + Redis + Caffeine cache)
                 ├── audit log (typed LogPayload)
                 ├── network broadcast (ObjectUpdatedPacket / ObjectDeletedPacket / domain packet)
                 └── custom Bukkit event (cancellable for create / disband)

Permission enforcement happens passively too: PermissionListener checks every block / interaction event against the town's permissions, and SettingsListener filters environment events by the town's TownSettings.

Last modified: 25 July 2026