Content

# Player Housing System

## Overview

Any player can claim a region of the world as their personal home by placing a **HomeDeed** block inside an enclosed structure. The system automatically detects the interior volume, registers it as a protected region, and assigns the player ownership. Decorating the interior upgrades the home's title.

---

## Claiming a Home

1. **Build an enclosed structure** — walls, floor, and ceiling with no open gaps. Maximum claimable interior volume is **8,000 blocks** (roughly 20×20×20). Minimum is **8 blocks** (must actually be enclosed).
2. **Craft a HomeDeed** — planks surrounding a gold ingot in the crafting grid (yields 1 deed).
3. **Place the HomeDeed** inside the structure (at floor level or above). On placement the game BFS-floods the interior air volume to find the bounding box.
   - If the scan succeeds: the region is registered and a notification confirms the home title.
   - If the scan fails (too open, too small): the deed is placed as a decorative block but no region is claimed — you'll need to close any gaps first.

**One home per player.** Placing a new deed removes the previous claim automatically.

---

## Home Titles (Decorating Score)

The title upgrades as you furnish the interior. Each *unique* decorative block type found inside the region counts as +1 point:

| Points | Title   |
|--------|---------|
| 0–3    | Shack   |
| 4–7    | Cottage |
| 8–11   | Manor   |
| 12+    | Estate  |

**Counted block types:** Bed, Bookshelf, Chair, Table, Crafting Table, Furnace, Chest, Guild Table, Iron Bars, Torch, Copper Torch (and their unique variants).

The score is recalculated live every time you place a block inside your region — a notification appears when the title changes.

---

## Commands

| Command | Description |
|---------|-------------|
| `/home` | Teleport to your home spawn point |
| `/home invite <player>` | Grant a player guest access (they can build inside) |
| `/home kick <player>` | Revoke a player's guest access |
| `/home lock` | Lock your home — non-guests are ejected on entry |
| `/home unlock` | Unlock your home — anyone can enter freely |
| `/home info` | Show your home's current decorating score and title |

---

## Protection

### Build Protection
The claimed region is registered in **GroupPerms** as a cuboid region named `home_<username>`. Only the owner and invited guests can place or break blocks inside. Outsiders get the message:
> *"This area is protected. Ask the owner to /home invite you."*

This applies regardless of whether the home is locked or unlocked.

### Lock / Entry Restriction
When `/home lock` is active, the game checks player position **twice per second**. If a non-guest steps inside the region AABB:
- They are immediately teleported **2 blocks outside** the region corner.
- They receive the notification: *"[owner]'s home is locked. You cannot enter."*

Guests (added via `/home invite`) bypass the lock — they can always enter.
The owner is always exempt.

### Breaking the Deed
Breaking the **HomeDeed** block releases the home claim:
- The GroupPerms region is removed.
- The `g_homes` entry is deleted.
- All guests lose their access.

---

## Foundation Block (Block Physics Integration)

If you use the **Foundation** block (crafted from 3×Stone + 3×Iron Ore) as part of your home's floor or walls, any blocks resting on or near it are **anchored** and will never collapse due to the block physics system. Without Foundation, structural blocks (Stone, Wood, Planks, etc.) that lose floor/wall support after a neighbouring block is removed will shake for 0.3 seconds then fall.

---

## Technical Notes

- Region data is stored in `g_homes` (key = owner username) and `GroupPerms`.
- The enclosed volume scan is a BFS from 1 block above the deed position, flooding through Air and Water only — solid blocks form the walls.
- `HomeData` fields: `deedPos`, `regionLo/Hi`, `spawnPos`, `groupName`, `regionIdx`, `locked`.
- Lock ejection runs in the main game loop at a 0.5s interval to avoid per-frame overhead.