Towns

A Town is the central entity: a named, owned organisation with members, roles, claims, optional spawn, MOTD, bank balance, and per-server origin.

Lifecycle

/town create <name>
  └─► TownService.create
        ├─ name validation (config.yml: name-length, name-pattern, blacklisted-names)
        ├─ player quota check (creation.quotas)
        ├─ persist + Redis publish + ObjectUpdatedPacket
        ├─ seed roles from roles.yml (default-roles)
        ├─ enable default settings from settings.yml
        └─ fire TownCreateEvent (cancellable)

/town transfer <member>     /town disband
        │                          │
        ▼                          ▼
  TownService.transfer       TownService.disband
                                   ├─ fire TownDisbandEvent (cancellable)
                                   ├─ delete claims, roles, members, warps, subzones, bans
                                   ├─ broadcast ObjectDeletedPacket
                                   └─ fire TownDisbandedEvent (async-safe)

Fields

Field	Type	Description
`uniqueId`	UUID	Primary key.
`name`	String	Unique, mutable.
`ownerId`	UUID	Current owner.
`spawn`	NetworkLocation	Optional — world, x, y, z, yaw, pitch, server id.
`motd`	Component	Optional MiniMessage Message of the Day.
`createdAt`/`updatedAt`	long	Timestamps.
`members`	`List<TownMember>`	Hydrated on load.
`roles`	`List<TownRole>`	Hydrated on load — see Roles.
`settings`	`EnumSet<TownSettings>`	Toggled state — see Settings.

Selection

A town is the implicit subject of most commands. Players pick one with:

/town select <town>

The selection lives on TownPlayerData.selectedTownId and is synced by AstralSync. Selecting fires TownSelectEvent; deselecting fires TownUnselectEvent.

%towns_current% returns the name of the selected town ("none" if none).

Creation rules

config.yml > creation:

Name validation: length window, regex, blacklist.
Quotas: default-quota plus per-permission overrides. Each QuotaEntry carries owner (max towns owned) and total (max towns participated in).

Quota errors map to TOWN_LIMIT_REACHED/TOWN_LIMIT_REACHED_OTHER.

Renaming

/town rename <new-name>

Validated by the same rules as create. Sends TOWN_NAME_UPDATED, fires the generic update broadcast.

MOTD

/town motd <miniMessage…>   # set
/town motd                  # clear

The MOTD is persisted as a JSON Component on the towns row. Length is capped — TOWN_MOTD_TOO_LONG fires if exceeded.

Spawn

/town spawn set records the player's current position as the town spawn. The location must lie within one of the town's own claims (SPAWN_NOT_IN_TOWN_CLAIM otherwise). Once set, /town spawn teleports members there subject to SPAWN_TELEPORT.

ClaimListener also fires CANNOT_OBSTRUCT_TOWN_SPAWN if anyone tries to place blocks where the spawn would obstruct.

Ownership transfer

/town transfer <member>

Recipient must already be a member (CANNOT_TRANSFER_OWNERSHIP_TO_NON_MEMBER).
Recipient must have room in their owner / total quota (TRANSFER_OWNERSHIP_FAILED_OWNER_QUOTA, TRANSFER_OWNERSHIP_FAILED_MEMBER_QUOTA).
The previous owner becomes a normal member (default role).

Only the current owner may call this.

Disband

/town disband # alias: /town delete

A two-step confirmation flow:

First call sends TOWN_DELETE_CONFIRMATION.
Second call within the timeout commits the disband.

The cascade removes every related row (claims, roles, members, warps, subzones, bans) and fires TownDisbandedEvent for plugins to clean up.

TownDisbandEvent is cancellable; TownDisbandedEvent is post-fact.

Info

/town info [town] opens a menu with the MOTD, member count, claim count, balance, and creation date. Most fields come from the town_* placeholder namespace — see Placeholders.

Per-player toggles

Stored on TownPlayerData:

Toggle	Action	Placeholder
Chat redirect	`toggle-town-chat`	`%towns_chatEnabled%`
Member-join notifications	`toggle-town-members-notification`	—
Favourite warps	`pin-warp`	`%towns_favoriteWarps%`

Last modified: 25 July 2026