Roles & Permissions

Each town owns a list of TownRoles, and each role carries an EnumSet<PermissionType>. Permission checks for both passive listeners (block break, container open, etc.) and active commands (/town claim, /town invite, …) walk the player's role.

Role model

Field	Type	Description
`uniqueId`	UUID	Primary key.
`townId`	UUID	Owner town.
`scope`	UUID?	When set, the role is subzone-scoped to that subzone. Town-wide roles leave this null.
`name`	String	Internal identifier.
`displayName`	Component	MiniMessage shown in menus.
`description`	String	Free text.
`defaultRole`	boolean	The role granted to every new member. Exactly one per town (or per subzone).
`permissions`	`EnumSet<PermissionType>`	What this role can do.
`weight()`	int	Default role: `-1`. Others: number of permissions held. Used for ordering & "higher role" comparisons.

Seed roles

roles.yml > default-roles defines the roles created automatically with every new town. Exactly one entry must set is-default: true — that role becomes the default for new members. See Configuration.

CRUD

Roles are managed through dialogs powered by the create-town-role, edit-town-role, and delete-town-role actions (see Actions). Common entry points are inside the town menu hub.

Cannot:

Delete the default role (CANNOT_DELETE_DEFAULT_ROLE).
Modify a role owned by a player at a higher weight than yours (CANNOT_MODIFY_HIGHER_ROLE).
Modify your own role (CANNOT_MODIFY_SELF_ROLE).
Modify the owner's role (CANNOT_MODIFY_OWNER_ROLE).

Each mutation writes an audit log entry — see Logs.

Assigning roles

Path	Permission
`/town members role <member> <role>`	`ASSIGN_ROLES`
Menu via `cycle-member-town-role`	`ASSIGN_ROLES`

The cycle-member-town-role action moves the member to the next role by weight, looping at the top.

Permission catalogue (`PermissionType`)

83 typed permissions, grouped by area:

World & interaction

Permission	Gate
`TOWN_ENTER`	Whether non-members may step inside claims.
`BLOCK_PLACE`	Place blocks.
`BLOCK_BREAK`	Break blocks.
`SPAWNERS_BREAK`	Break monster spawners specifically.
`BLOCK_IGNITE`	Light blocks on fire (flint, lava).
`PLANT`	Plant saplings, crops.
`HARVEST`	Break grown crops.
`HARVEST_RIGHT_CLICK`	Right-click harvest (berries, sweet berries).
`TRAMPLE_FARMLAND`	Step on farmland and trample it.
`SHEAR`	Shear sheep and certain blocks.
`ITEM_PICKUP`/`ITEM_DROP`	Item handling.
`INTERACT_GENERAL`	Any non-specialised interaction.
`INTERACT_DOORS`/`INTERACT_TRAPDOORS`/`INTERACT_BUTTONS`/`INTERACT_LEVERS`	Self-explanatory.
`INTERACT_MECHANISMS`	Pistons, dispensers, redstone wired devices.
`INTERACT_CONTAINERS`	Chests, barrels, hoppers, shulkers.
`INTERACT_ANVIL`/`INTERACT_FURNACE`/`INTERACT_CRAFTING_TABLE`/`INTERACT_ENCHANTING_TABLE`	Per-block UIs.
`INTERACT_ITEM_FRAME`	Place / rotate / remove.
`EDIT_SIGN`	Sign editing.
`VEHICLE_CREATE`/`VEHICLE_USE`	Boats, minecarts.
`ATTACK_PLAYER`/`ATTACK_ANIMAL`/`ATTACK_MONSTER`	Combat.
`FLY`/`ELYTRA`	Flight modes.
`ENDER_PEARL`	Use pearls inside claims.
`LAUNCH_PROJECTILES`/`THROW_POTIONS`	Ranged.
`ASE`/`LEASH`	Misc movement.

Members

Permission	Gate
`INVITE`	`/town invite`.
`KICK`	`/town members kick`.
`BAN`	`/town ban`, `/town unban`.

Roles

Permission	Gate
`MANAGE_ROLES`	Create / edit / delete roles.
`ASSIGN_ROLES`	Assign a role to a member.
`MANAGE_PERMISSIONS`	Toggle the permission entries inside a role.

Town governance

Permission	Gate
`CLAIM_LAND`/`UNCLAIM_LAND`	`/town claim`, `/town unclaim`.
`SPAWN_SET`/`SPAWN_TELEPORT`	Spawn management.
`NAME_CHANGE`	`/town rename`.
`SETTINGS_CHANGE`	Toggle `TownSettings`.
`DELETE_TOWN`	`/town disband` (owner-only in addition).
`TRANSFER_OWNERSHIP`	Reserved; ownership transfer is currently owner-only.

Economy

Permission	Gate
`BANK_WITHDRAW`/`BANK_DEPOSIT`	Town bank ops.

Features

Permission	Gate
`WARPS`	Create / delete warps.
`LOGS`	Read the audit log.
`SUB_ZONES`	Subzone CRUD.
`SUMMON_PET`	Use the pet system inside the claim.
`CREATE_PLAYER_SHOP`	Spawn shop signs inside the claim.
`SET_HOME`	Use `/sethome` inside the claim.
`PLACE_FURNITURE`/`BREAK_FURNITURE`	CraftEngine furniture.
`MANAGE_RELATIONS`	Reserved for the inter-town diplomacy API.
`TOP_COMMAND`	Use `/top` (top-block teleport) inside the claim.
`CHAT_BROADCAST`	Use `/town chat broadcast`.

Permission resolution

Town.hasPermission(player, type, location) and the matching subzone overload follow this order:

If the player has town.admin, return true.
If they are the owner, return true.
If the location is inside a subzone:
- If the player is a subzone member, use their subzone role's permissions.
- Otherwise fall through to step 4.
Use the player's town role's permissions.

TownAPI.hasPermission(player, location, type) resolves the same way and is the recommended entry point for external plugins.

Last modified: 25 July 2026