Claims

A claim is a single chunk owned by a town. Claims are independent rows in the claims table; there is no contiguity requirement on the schema level, but the adjacency rule is enforced when claiming.

Claim model

Field	Type	Description
`uniqueId`	UUID	Primary key.
`townId`	UUID	Owning town.
`x`/`z`	int	Chunk coordinates.
`world`	String	World name.
`serverId`	UUID	Source server.
`createdAt`	long	Timestamp.

ClaimService keeps a chunk-key → claim lookup in Redis and Caffeine, so per-chunk owner queries (TownAPI.findTownByChunk) are O(1).

Claiming

/town claim
    │  permission: CLAIM_LAND
    ▼
ClaimService.create(player, town, location)
    ├── world allowed (CLAIM_DISABLED_IN_WORLD)
    ├── chunk free (CHUNK_ALREADY_CLAIMED)
    ├── adjacency (CHUNK_CLAIM_NOT_ADJACENT) — except for the very first claim
    ├── max-claims cap (CHUNK_CLAIM_LIMIT_REACHED)
    ├── min distance from spawn (CLAIM_TOO_CLOSE_FROM_SPAWN)
    ├── min distance between towns (CLAIM_NEAR_OTHER_TOWN)
    ├── cost = $e(cost-expression) — paid out of the town bank
    │   └── INSUFFICIENT_FUNDS on shortfall
    ├── persist + cache + network broadcast
    ├── fire TownClaimEvent
    └── CHUNK_CLAIM_SUCCESS

Configuration knobs (`config.yml > claim`)

Field	Meaning
`min-distance-from-spawn`	Chunks. World-spawn buffer.
`min-distance-between-towns`	Chunks between this town and any other.
`max-claims`	Hard cap.
`free-claims`	The first N claims cost zero regardless of the formula.
`cost-expression`	AstralCore expression. Variables: `%claim_index%` (1-based count after this claim), `%claim_total%` (current count before).

A typical formula:

cost-expression: "$e(100 * %claim_index%)"

That yields 100, 200, 300, … per additional claim. Set to $e(0) to disable the economy gate.

Unclaiming

/town unclaim
    │  permission: UNCLAIM_LAND
    ▼
ClaimService.delete(player, town)
    ├── chunk owned by the actor's town (CHUNK_NOT_CLAIMED)
    ├── persist + cache + network broadcast
    ├── fire TownUnclaimEvent
    └── CHUNK_UNCLAIM_SUCCESS

The town spawn is reset if the unclaimed chunk contained it.

Auto-claim

/town autoclaim

Toggles a per-player auto-claim flag. While active, every chunk the player enters is claimed as long as all the standard checks pass. The flag is cleared on TownExitEvent and on quit.

Auto-claim swallows a chunk's worth of failures silently except for AUTO_CLAIM_FAILED_WORLD and AUTO_CLAIM_ENABLED / AUTO_CLAIM_DISABLED toggle messages.

Wilderness

Unclaimed land falls back to config.yml > wilderness:

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

Players entering wilderness see the title / subtitle. The permissions set acts as the wilderness role — what anyone can do — and the settings set decides which environment behaviours stay on.

Listener-driven enforcement

PermissionListener and SettingsListener (see Events) run on every relevant Bukkit event. They resolve the chunk to a claim, then the claim to a town, then check the player's role permissions and the town's settings. Both listeners short-circuit when the player has town.admin.

Particle visualisation

/town particles toggles a per-player overlay rendered by ParticleViewTask. Lines mark the edge of each adjacent claim. Disabled in worlds where claims are disabled (PARTICLES_VIEW_DISABLED_IN_WORLD).

BlueMap integration

When BlueMap is present, BlueMapHook groups each town's claims into continuous polygons (via the Cheese library), extrudes them to show height, and labels them with the town name. The detail tooltip is the map-town-detail field in config.yml, MiniMessage with placeholders.

The refresh job runs every 72 000 ticks (≈1 hour) and on world load.

Last modified: 25 July 2026