Configuration Files

Every YAML in plugins/AstralTown/ (except menus/ and messages.yml) is documented here. Reload with /town reload.

`config.yml`

The main behavioural configuration.

creation:
  name-length:
    min: 3
    max: 16
  name-pattern: "^[A-Za-z0-9_]{3,16}$"
  blacklisted-names:
    - "admin"
    - "staff"
  quotas:
    default-quota:
      owner: 1
      total: 3
    permissions:
      town.create.vip:
        owner: 2
        total: 5

claim:
  min-distance-from-spawn: 256
  max-claims: 64
  min-distance-between-towns: 5
  free-claims: 16
  cost-expression: "$e(%claim_index%*100)"

wilderness:
  permissions:
    - BLOCK_PLACE
    - BLOCK_BREAK
    - INTERACT_DOORS
  settings:
    - SPAWN_ANIMALS
    - SPAWN_MONSTERS
  title: "<gold>Wilderness"
  sub-title: "<gray>No town owns this land"

maximum-members-per-town: 50

map-town-detail: "<bold>%town_name%</bold><br><gray>Members: %town_members%"

`creation`

Field	Type	Description
`name-length.min`/`name-length.max`	int	Allowed character range.
`name-pattern`	regex	Names that do not match are rejected with `INVALID_TOWN_NAME`.
`blacklisted-names`	`Set<String>`	Case-insensitive bans.
`quotas.default-quota`	`QuotaEntry`	`owner` = max towns owned; `total` = max towns participated in.
`quotas.permissions`	`Map<String, QuotaEntry>`	Permission-keyed overrides. The highest matching entry wins.

`claim`

Field	Description
`min-distance-from-spawn`	Chunks. Claims rejected within this radius of world spawn.
`max-claims`	Hard cap per town.
`min-distance-between-towns`	Chunks. Prevents claims abutting another town.
`free-claims`	First N claims cost nothing.
`cost-expression`	AstralCore `$e(...)` expression evaluated per claim. Variables: `%claim_index%`, `%claim_total%`.

`wilderness`

Applied outside any town claim:

Field	Description
`permissions`	`Set<PermissionType>` — defaults to `BLOCK_PLACE / BLOCK_BREAK` etc., gating what's allowed in unclaimed land.
`settings`	`Set<TownSettings>` — enabled outside towns (e.g. `SPAWN_MONSTERS`).
`title`/`sub-title`	MiniMessage shown on entering wilderness.

`roles.yml`

Seed roles every new town receives.

default-roles:
  citizen:
    display-name: "<gray>Citizen"
    description: "Default role for new members."
    is-default: true
    permissions:
      default:
        - BLOCK_PLACE
        - BLOCK_BREAK
        - INTERACT_DOORS
        - INTERACT_CONTAINERS

  builder:
    display-name: "<yellow>Builder"
    description: "Trusted builders."
    is-default: false
    permissions:
      default:
        - BLOCK_PLACE
        - BLOCK_BREAK
        - INTERACT_*

Field	Description
`display-name`	MiniMessage shown in menus.
`description`	Free-text helper.
`is-default`	Exactly one role must be `true` — it is the role assigned to new members.
`permissions.default`	`EnumSet<PermissionType>` — see Roles for the full list.

`settings.yml`

UI icons for the per-town settings menu and the network-wide defaults.

default-settings:
  - SPAWN_ANIMALS
  - PVP

settings:
  PVP:
    material: "DIAMOND_SWORD"
    name: "<red>PvP"
    lore:
      - "<gray>Players can attack each other."
  SPAWN_ANIMALS:
    material: "WHEAT"
    name: "<yellow>Spawn animals"

Field	Description
`default-settings`	Settings enabled on every newly-created town.
`settings`	`Map<TownSettings, ItemStackWrapper>` — the icon shown for each toggle.

`permissions.yml`

UI icons for the per-role permission menu.

permissions:
  BLOCK_PLACE:
    material: "GRASS_BLOCK"
    name: "<green>Place blocks"
  INVITE:
    material: "WRITABLE_BOOK"
    name: "<aqua>Invite members"

Every entry in PermissionType should have an icon — missing entries fall back to a placeholder.

`logs.yml`

UI icons for the log viewer, keyed by LogType.

displays:
  CLAIM:
    material: "MAP"
    name: "<gold>Claimed chunk"
  ASSIGN_ROLE:
    material: "WRITABLE_BOOK"
    name: "<aqua>Role assigned"

See Logs for the full LogType catalogue.

`servers.yml`

Per-server overrides — most notably which server groups should activate the plugin.

enabled-groups:
  - "survival"
  - "creative"

Servers not in enabled-groups load the JAR but stay inert (no listeners, no commands).

`database.properties`

A standard JDBC properties file. AstralTown reuses the connection model from AstralCore — see the AstralCore database docs.

Last modified: 25 July 2026