Roles & Permissions

The Role System

SCS2 replaces V1's simple member/visitor toggle with a full role hierarchy. Each player in a claim has a role that determines what they can and cannot do.

Default roles (from lowest to highest)

Role	Description
VISITOR	Any player who is not a member of the claim. By default, visitors have very limited permissions (cannot build, open containers, etc.).
MEMBER	A player who has been invited and accepted. Members can build, use containers, and interact with the claim based on their permission set.
MODERATOR	A trusted member who can manage other members — invite, kick, ban, promote, and demote players within the claim.
OWNER	The claim creator. Has full control: all permissions, can manage flags, rename the claim, transfer ownership, sell it, and more.

Custom roles

Claim owners can create custom roles with custom permission sets. Custom roles sit between VISITOR and OWNER in the hierarchy and can be assigned unique names. The maximum number of custom roles per claim is controlled by the scs.limit.roles.<amount> permission or admin settings.

Promoting and demoting

/claim promote <player> [claim]
/claim demote <player> [claim]

Moves a member up or down the role hierarchy. A moderator can promote members to moderator and demote other moderators to member. Only the owner can promote someone to moderator.

Permissions (128)

Each role has an independent set of 128 permissions that control exactly what players with that role can do inside the claim. Permissions are configured per claim — you can have different permission setups for each of your claims.

Permissions are organized into 5 categories in the GUI:

1. Building & Blocks
2. Redstone & Mechanisms
3. Containers & Workstations
4. Entities & Decorations
5. Items, Movement & Misc

Block Permissions

These permissions control what players can do with blocks inside the claim:

Permission	Description
PLACE_BLOCK	Place any block
DESTROY_BLOCK	Break any block
DESTROY_SPAWNERS	Break mob spawners specifically
USE_BUCKET	Place or collect water/lava with buckets
TRAMPLE_CROPS	Trample farmland by jumping on it
IGNITE_BLOCK	Set blocks on fire with flint & steel or fire charge

Container & Interaction Permissions

These permissions control interactions with containers, workstations, and redstone components. There are 30+ individual permissions for fine-grained control:

Containers

INTERACT_CHEST, INTERACT_TRAP_CHEST, INTERACT_ENDER_CHEST, INTERACT_BARREL, INTERACT_SHULKER_BOX, INTERACT_HOPPER, INTERACT_DROPPER, INTERACT_DISPENSER, INTERACT_SHELF

Workstations

INTERACT_FURNACE, INTERACT_BLAST_FURNACE, INTERACT_SMOKER, INTERACT_BREWING_STAND, INTERACT_ANVIL, INTERACT_ENCHANTING_TABLE, INTERACT_BEACON, INTERACT_SMITHING_TABLE, INTERACT_LOOM, INTERACT_CARTOGRAPHY_TABLE, INTERACT_STONECUTTER, INTERACT_GRINDSTONE, INTERACT_CRAFTING_TABLE, INTERACT_COMPOSTER, INTERACT_CAULDRON

Redstone & Mechanisms

INTERACT_BUTTON, INTERACT_LEVER, INTERACT_PRESSURE_PLATE, INTERACT_TRIPWIRE, INTERACT_COMPARATOR, INTERACT_REPEATER, INTERACT_NOTE_BLOCK, INTERACT_TARGET_BLOCK

Doors & Gates

INTERACT_DOOR, INTERACT_TRAPDOOR, INTERACT_FENCE_GATE

Spawners & Special Blocks

INTERACT_SPAWNER, INTERACT_TRIAL_SPAWNER, INTERACT_SCULK_CATALYST, INTERACT_SCULK_SHRIEKER, INTERACT_COMMAND_BLOCK, INTERACT_STRUCTURE_BLOCK, INTERACT_JIGSAW

Other Interactions

INTERACT_BELL, INTERACT_CAMPFIRE, INTERACT_CANDLE, INTERACT_FLOWER_POT, INTERACT_JUKEBOX, INTERACT_LECTERN_READ, INTERACT_LECTERN_TAKE, INTERACT_BOOKSHELF, INTERACT_DECORATED_POT, INTERACT_BRUSH_BLOCK, INTERACT_SIGN, INTERACT_BED, INTERACT_DRAGON_EGG, INTERACT_VAULT

This level of granularity means you can, for example, allow visitors to use buttons and doors but not open chests — something impossible with V1's simple toggle system.

Entity Permissions

Fine-grained control over how players interact with entities inside the claim. Over 20 permissions cover every type of entity interaction:

Permission	Description
PLACE_ENTITY	Spawn entities (spawn eggs, etc.)
DESTROY_ENTITY	Kill entities
INTERACT_ENTITY	Right-click entities (general)
DAMAGE_ENTITY	Deal damage to entities
SHEAR_ENTITY	Shear sheep and mooshrooms
FEED_ENTITY	Feed animals
RIDE_ENTITY	Mount and steer rideable mobs (horses, pigs, striders, etc.)
MOUNT_ENTITY	Sit on / become a passenger of an entity (boats, minecarts, llamas as caravan member, etc.)
LEAD_ENTITY	Attach leads to entities
NAME_TAG_ENTITY	Use name tags on entities
BREED_ENTITY	Breed animals
TAME_ENTITY	Tame wolves, cats, etc.
MILK_ENTITY	Milk cows and mooshrooms
CAPTURE_ENTITY	Capture entities (e.g., with leads or buckets)
INTERACT_VILLAGER	Trade with villagers
INTERACT_GOLEM	Interact with iron / snow golems (offer flowers, etc.)
TRADE_WANDERING_TRADER	Trade with wandering traders

Armor Stands, Item Frames & Paintings

Permission	Description
PLACE_ARMOR_STAND	Place armor stands
DESTROY_ARMOR_STAND	Break armor stands
INTERACT_ARMOR_STAND	Modify armor stand equipment
PLACE_ITEM_FRAME	Place item frames / glow item frames
DESTROY_ITEM_FRAME	Break item frames
INTERACT_ITEM_FRAME	Rotate items in item frames
PLACE_PAINTING	Place paintings
DESTROY_PAINTING	Break paintings
INTERACT_PAINTING	Right-click paintings (cycle painting variant on 1.21+)

Vehicles

PLACE_VEHICLE, DESTROY_VEHICLE, INTERACT_VEHICLE — control placement, destruction, and use of boats and minecarts.

Item Usage Permissions

These 15+ permissions control which items players can use inside the claim:

Permission	Description
USE_BOW_CROSSBOW	Fire bows and crossbows
USE_TRIDENT	Throw tridents
USE_ENDER_PEARL	Throw ender pearls
USE_CHORUS_FRUIT	Eat chorus fruit (causes teleportation)
USE_FIREWORK	Launch fireworks
USE_FISHING_ROD	Cast fishing rods
USE_WIND_CHARGE	Use wind charges
USE_SHIELD	Block with shields
USE_ELYTRA	Glide with elytra
USE_POTION	Use splash/lingering potions
USE_SPYGLASS	Use the spyglass
USE_BRUSH	Use archaeology brushes
USE_BUNDLE	Use bundles
USE_MAP	Use maps
USE_FIRE_CHARGE	Use fire charges
USE_SNOWBALL	Throw snowballs
USE_EGG	Throw eggs

Player Action Permissions

These permissions control general player actions and movement within the claim:

Permission	Description
PICKUP_ITEM	Pick up dropped items
DROP_ITEM	Drop items from inventory
ENTER	Enter the claim (if disabled, the player is pushed back)
LEAVE	Leave the claim (if disabled, the player is pushed back inside — useful for jails, event arenas)
TELEPORT	Teleport into the claim
FLY	Use /claim fly in the claim
SLEEP	Sleep in beds
EAT	Eat food
DRINK	Drink potions
CROUCH	Sneak (used by some interaction systems)
FROSTWALKER	Activate Frost Walker enchantment
PROJECTILE_LAUNCH	Launch any projectile
TOTEM_USE	Activate Totem of Undying
EQUIP_ARMOR	Equip armor
EQUIP_ITEM	Equip items to offhand
EXP_DROP_PICKUP	Pick up experience orbs
USE_PORTAL	Travel through nether / end / custom portals located inside the claim
SCULK_SENSOR_TRIGGER	Cause sculk sensors to emit a redstone pulse via player movement / interaction
RECEIVE_BEACON_EFFECTS	Receive the active beacon's potion effects while inside the claim
NATURAL_HEALTH_REGEN	Naturally regenerate health (vanilla full-hunger regen) while inside the claim. Potion regen, golden apples, and command-driven heals are unaffected.

Temporary Invites

Invitations can carry an optional duration, after which the member is auto-kicked:

/claim invite <player> [duration] [claim]

The duration argument accepts the same format as ban durations (10m, 12h, 7d, 2w, 1mo, 1y). Omit it for a permanent invite — behaviour is unchanged from previous versions.

How expiration works

• Persistent across restarts — the expiry timestamp is stored in the database alongside the member row, so server restarts don't reset the countdown.
• Precise expiration — a per-invite task fires at the exact expiry moment. A 5-minute safety sweep also runs in the background to catch any edge case (e.g. a task lost to a Folia region being unloaded).
• Online kick notification — if the member is online when the invite expires, they receive a chat message and hear the kick sound. Offline members are simply removed from the claim.
• Owner feedback — the member GUI (Java + Bedrock) shows the remaining time in the member head's lore. The placeholder %expires% resolves to the remaining duration or no-expiration for permanent members.

Claim Templates

Templates let you save a claim's permissions + flags once, then apply them to any of your other claims with a single command:

/claim template save <name>         # save current claim's perms + flags
/claim template apply <name> [claim] # overwrite target claim's perms + flags
/claim template list                   # list your templates
/claim template delete <name>        # remove a template

What's stored

• Role permissions for every role (default + custom)
• All flag values
• The list of custom roles, if any

What's not stored

• Members, bans, spawn point, name, description, icon
• Chunks — templates never change the claim's shape

Per-player scope

Templates are saved per owner. Another player can't apply or see your templates.

Migrations

On plugin startup, templates are backfilled the same way claims are — if a new permission or flag key is added in a future release, your saved templates automatically gain that key (defaulting to the role's factory value) so apply doesn't wipe keys it doesn't know about.

Favourites

Players can bookmark claims they care about so they float to the top of the list and carry a ★ marker. Works on both Java and Bedrock.

How to toggle

• /claim favorite while standing in a claim.
• /claim favorite <name> for a claim you own.
• Inside /claim list (Java): shift-click the claim head.
• Inside /claim list (Bedrock): tap the Manage favorites button at the top.

Viewing favourites

• /claim favorites opens a GUI filtered to your favourites only (Java or Bedrock variant, auto-detected).
• Inside /claim list, the top button on Bedrock and the ★ marker on Java make it easy to spot them.

Where it's stored

The favourite list lives in PlayerData.settings["favorite-claims"] as a simple array of claim ids — no new table, no schema migration. Deleted claim ids are lazily pruned the next time the favourites are consulted.

API

Plugins can read or mutate favourites through the public API:

api.isFavorite(playerUuid, claimId);
api.addFavorite(playerUuid, claim);     // fires ClaimFavoriteEvent
api.removeFavorite(playerUuid, claim);  // fires ClaimFavoriteEvent
api.getFavoriteClaimIds(playerUuid);
api.getFavoriteClaims(playerUuid);

Both mutators fire ClaimFavoriteEvent with a FAVORITE or UNFAVORITE action, so other plugins can react (e.g. persisting to an external dashboard).

Claim chat (/cc)

/cc <message> broadcasts one line to every online member across every claim the sender owns. Think of it as a "team chat" spanning all your claims — useful when you run several small builds with overlapping groups of trusted players.

• Format is driven by the claim-chat-format lang key (placeholders: %player%, %message%).
• Permission: scs.claim.chat (default true).
• Recipients are computed by taking the union of every member UUID across every claim of the sender — so members who belong to multiple claims only receive the line once.
• Sender always sees their own line.
• If the sender owns no claim, the command is a no-op with a chat message.

Unclaim requests (/requnclaim) — 2.5.0

Players can submit a staff-reviewed request to unclaim a chunk or an entire claim instead of bothering admins in DMs. The full flow is gated by unclaim-requests.* in config.yml.

Player flow

1. /requnclaim [chunk|claim] [reason] while standing inside the target claim. Scope keyword optional (default scope picked from config). Reason optional unless unclaim-requests.reason.required: true.
2. A chat message appears with a clickable [CONFIRM] button. The request is not persisted until clicked — the 60-second token TTL avoids stale confirmations when the player walked out and back into a different claim.
3. After confirmation, the request lands in the staff queue. The player is told to wait; per-player cooldown (unclaim-requests.cooldown-seconds) starts.

Staff flow

1. Online holders of scs.admin.unclaimrequest.notify receive a chat ping when a new request arrives (configurable via unclaim-requests.notifications.notify-staff-on-new-request). A Discord embed is also posted when discord-webhook.enabled is on, so offline staff don't miss it.
2. Run /viewrequnclaim to open the review GUI — every pending request is shown as a player head (the requester's). Hover shows scope, owner, claim name, world+chunk coordinates, reason and submission date.
3. Left-click the head to teleport to the chunk. Shift+right-click to approve (triggers a force-unclaim of the chunk or claim, depending on the scope). Shift+left-click to deny.
4. The requester (if online) is notified of the outcome.

Auto-resolve sweep

An async task scans pending requests on a configurable interval (default hourly) and auto-resolves entries whose target claim no longer exists OR whose requester has been offline for more than the configured threshold. Resolved rows older than archive-after-days are physically deleted from the DB.

Configuration sample

unclaim-requests:
  enabled: true
  scope:
    allow-claim: true     # /requnclaim claim ...
    allow-chunk: true     # /requnclaim chunk ...
  cooldown-seconds: 300   # 0 disables
  max-pending-per-player: 5  # 0 = unlimited
  reason:
    required: false
    min-length: 0
    max-length: 200
  auto-resolve:
    enabled: true
    when-claim-deleted: true
    when-requester-offline-days: 30   # 0 disables
    check-interval-minutes: 60
    archive-after-days: 30            # 0 keeps full history
  notifications:
    notify-staff-on-new-request: true
    notify-requester-on-resolved: true

Permissions

• scs.requnclaim — submit requests (default true).
• scs.admin.viewrequnclaim — open the review GUI (default op).
• scs.admin.unclaimrequest.notify — receive new-request chat pings (default op).
• scs.admin.unclaimrequest.review — approve/deny from the GUI (default op).