Content

# Permissions & Land Claiming — Player and Admin Guide

---

## Part 1 — Player Roles

Every player on a server has one of these roles, ranked lowest to highest:

| Role | Level | What they can do |
|---|---|---|
| **Banned** | 0 | Cannot connect |
| **Player** | 1 | Default. Can build in unprotected areas |
| **Member** | 2 | Can break blocks with no ACL (see below) |
| **Moderator** | 3 | Can kick, ban, use admin commands |
| **Admin** | 4 | Can promote/demote others, teleport players, manage regions |
| **Owner** | 5 | Full server authority |

Roles survive disconnects — they are stored in `saves/roles.json`.

In **singleplayer** all admin commands are always available regardless of role.

---

## Part 2 — Server Admin Commands

All commands are typed in the console (press `/` or `T` to open chat, prefix with `/`).

### Role Management (Admin+)

```
/promote <name> <role>    — Set a player's role (player/member/moderator/admin/owner)
/demote  <name> <role>    — Same as promote but conventionally used to lower
/role    <name>           — Show a player's current role
```

### Moderation (Moderator+)

```
/kick <name> [reason]     — Disconnect a player with an optional message
/ban  <name>              — Permanently ban (sets role to Banned, saves to disk)
/unban <name>             — Restore a banned player back to Player role
/list                     — Show all currently connected players and their roles
/broadcast <message>      — Send a server-wide announcement
/mute <name>              — Silence a player's chat
```

### Teleportation (Moderator+)

```
/tp <x> <y> <z>           — Teleport yourself to coordinates
/tphere <name>            — Pull a player to your location
/tpto <name>              — Teleport yourself to a player
/tp <name> <x> <y> <z>   — Teleport a specific player to coordinates
```

### World / Game (Moderator+)

```
/fly                      — Toggle fly/no-clip mode
/speed <value>            — Set movement speed (default 30, max 500)
/gm c [player]            — Set creative mode (infinite blocks, no fall damage)
/gm s [player]            — Set survival mode
/give <block> [count]     — Give yourself a block or item
/clear                    — Clear your hotbar
/time <day|night|value>   — Set time of day
/weather <clear|rain|...> — Set weather
```

---

## Part 3 — Per-Block ACLs (Block Permissions)

Every block can optionally carry an **ACL (Access Control List)** stored in `saves/block_perms.dat`.

### Default behaviour (no ACL on a block)

- **Interact** (right-click): any Player+ can do it.
- **Break**: only Member+ can break blocks with no ACL. Players cannot break blocks they did not place unless they are Member or higher.

### When a block has an ACL

The ACL records:
- **Owner** — the username who placed/claimed it. The owner can always break their own block regardless of any other setting.
- **minInteractRole** — minimum role needed to right-click (default: Player).
- **minBreakRole** — minimum role needed to break it (default: Member).
- **Whitelist** — specific usernames who bypass the minRole checks and can always interact.
- **Blacklist** — specific usernames who are always denied, regardless of role.

Check order: blacklist ? whitelist ? role comparison.

### Which blocks automatically get ACLs when placed?

These blocks call `BlockPermManager::claim()` on first interaction, registering the placer as owner:

- **Billboard** — claimed on first right-click
- **Exhibit Diorama** — claimed on first right-click
- **Action Block** — claimed on first right-click
- **Home Deed** — claimed on placement (see Part 4)

For all other blocks, breaking is restricted to Member+ by default unless you are the original placer.

---

## Part 4 — Home Deed (Player Housing Claim)

### What it does

Placing a **Home Deed** block registers a private region of the world to you. Other players cannot build or break blocks inside your region unless you invite them.

### How to claim a home

1. Build a structure (optional but recommended — walls + roof let the game auto-detect the interior).
2. Place the **Home Deed** block at or near your doorway.
3. The game runs a BFS flood-fill scan starting above the deed block, up to 3000 air blocks.
   - If it finds an enclosed volume it uses that exact interior as your region.
   - If the space is open or too large it falls back to a fixed **20 × 10 × 20** box centred on the deed.
4. A **GroupPerms cuboid region** named `home_<yourname>` is created covering that volume. Only members of that group can build inside.

### One home per player

If you already own a home and place a new deed, the old region and group are automatically deleted and replaced.

### Home types (decor score)

The game counts how many distinct furniture/decoration block types are inside your region (max 16 types counted):

| Score | Home Title |
|---|---|
| 0–2 | Shack |
| 3–5 | Cabin |
| 6–9 | Cottage |
| 10–13 | Manor |
| 14+ | Estate |

Furniture blocks that count toward the score: Bed, Bookshelf, Chair, Crafting Table, Furnace, Chest, Guild Table, Iron Bars, Torch, Copper Torch, Fireplace, Lamp, Furn Table.

### Home commands (all players)

```
/home                      — Teleport to your home spawn point
/home info                 — Show region bounds, home type, decor score, and guest list
/home invite <player>      — Add a player as a guest (they can build inside your home)
/home kick <player>        — Remove a guest from your home
/home lock                 — Lock your home — non-guests are teleported out if they enter
/home unlock               — Unlock your home — anyone can enter freely
/home score                — Print your current decor score and home type
```

### E-key inspect

Press **E** while looking at any Home Deed block to see:
- The owner's name and home type
- Current decor score
- Guest list
- Lock status

### Releasing a home claim

**Break the Home Deed block.** The region and group permissions are automatically removed.

---

## Part 5 — Group Permissions (Admin Tool for Custom Regions)

Moderators and above can create named groups and protect arbitrary cuboid regions in the world. This is the admin-level equivalent of what Home Deed does automatically for players.

### Step 1 — Create a group

```
/perm create <groupname>
```

### Step 2 — Add players to the group

```
/perm <playername> group add <groupname>
/perm <playername> group del <groupname>
```

### Step 3 — Select a cuboid region in-world

Stand at one corner of the area you want to protect and press **F6** to set Corner A (your current position).  
Walk to the opposite corner and press **F7** to set Corner B.

### Step 4 — Assign the cuboid to the group

```
/perm region set <groupname> [optional label]
```

This protects the selected box — only players in `<groupname>` can place or break blocks inside it.

### Listing and managing regions

```
/perm region list            — Show all protected regions with their index, label, group, and coordinates
/perm del <groupname>        — Delete a group and all its regions
```

Regions and groups are saved to `saves/groups.dat` and `saves/regions.dat` and persist across server restarts.

---

## Part 6 — Guild Territory (Guild-Level Claiming)

Guilds can claim land through two mechanisms.

### Territory Obelisk (capture point)

- Right-click an **uncaptured** obelisk to begin a **30-second channel**.
- You must stay still for the full 30 seconds. Moving cancels it.
- On success the obelisk is registered to your guild.
- Right-click a **captured** obelisk you already own to see status.
- Use `/territory` (or `/tc`) to list all captured obelisks and which guilds hold them.

### Territory Gate (guild-placed barrier)

- Craft or obtain a **Territory Gate Item** from your guild inventory.
- Hold it and right-click a solid surface to place the gate above it.
- The gate **physically blocks** any player who is not a member of the guild that placed it. Non-members are pushed back when they walk into it.
- Only the placing guild's members can pass through freely.

### Trade Post (supply chain node)

- Place a **Trade Post** block.
- Right-click it to register it to your guild (first interaction only).
- Subsequent right-clicks open the Guild HQ trade panel, letting your guild anchor a supply chain node at that location.
- If you are not in a guild, the block asks you to join one first.

---

## Part 7 — Summary of What Protects What

| Mechanism | Who sets it | What is protected | Who can bypass |
|---|---|---|---|
| **Player role (Member+)** | Server admin via `/promote` | All blocks with no ACL | Owner and higher roles |
| **Block ACL (whitelist/blacklist)** | Automatic on deed/billboard/etc. | Individual blocks | Block owner, whitelisted players, Admins |
| **Home Deed region** | Any player | Enclosed build volume | Home owner + guests (`/home invite`) |
| **GroupPerms cuboid** | Moderator+ via `/perm region set` | Any admin-defined box | Members of the assigned group |
| **Territory Gate** | Guild member | Physical passage through a door | Guild members only |
| **Territory Obelisk** | Guild (30s channel) | Marks territory ownership (symbolic) | Any guild can attempt re-capture |
| **Home lock** | Home owner via `/home lock` | Entry into home region | Home owner + invited guests |