# Claims: Basics

Create, resize, subdivide and abandon claims. Plus tools, the border display, claim-block economy and automatic expiration.

## Tools

| Tool | Config key | Default | Purpose |
|---|---|---|---|
| Golden shovel | `Claims.ModificationTool` | `GOLDEN_SHOVEL` | Create, resize, subdivide claims |
| Stick | `Claims.InvestigationTool` | `STICK` | Show the claim at a block; sneak+click shows all nearby |
| Bone | `Claims.SubdivisionVisualizationTool` | `BONE` | Click shows the subdivision at the block, sneak+click all nearby subdivisions |

> **Tip:** Every tool interaction rechecks permissions and trust on each click, nothing is cached. The position is resolved server-side from the real target block.

## Create a claim (two-click flow)

Mode `BASIC` (default for everyone):

1. **First click** with the shovel: the position is stored and a diamond-block marker appears (visible only to you).
2. **Second click** on a different X/Z position: the server forms the rectangle, validates it and saves on success. The border is visualised.

Sneak+right-click cancels an open first click. The marker disappears on the second click, on cancel, mode switch, putting the shovel away, teleport or logout.

> **Tip:** Click the corner of an existing claim first and it automatically starts a **resize** instead of a new claim. The marker is then a redstone block instead of a diamond block.

Before creating, the server checks: world claimable (`Claims.WorldModes` not `Disabled`, not inside a global world claim), minimum size, overlap, claim limit and available claim blocks.

## Geometry

```yaml
Claims:
  MinimumWidth: 5          # minimum side length of a top-level claim
  MinimumArea: 25          # minimum area (width × length)
  # Height: claims ALWAYS span the full world build height. The three keys
  # below are only honoured by the automatic chest claim (below); manually
  # created/resized claims ignore them.
  ExtendIntoGroundDistance: 5
  MaximumDepth: 0          # currently no effect (GP compatibility)
  MinimumY: -2147483648    # chest claim only; -2147483648 = no limit
  MinimumYOverrides: {}    # per world: worldName: minimumY
```

Invalid values are corrected on load (`MinimumWidth < 1` → `5`, `MinimumArea` at least `MinimumWidth²`). Subdivisions are exempt from the minimums and go down to 1×1.

> **Warning:** `MinimumY` only applies to the automatic chest claim. Hand-made claims always reach top to bottom, even in the Nether.

## Resize

No separate command: click a visible claim corner with the shovel (mode `BASIC`, `SUBDIVIDE` or `ADMIN`) and it is treated as a resize (redstone-block marker). The second click drags the corner, the opposite one stays fixed. The new rectangle is fully validated; in `BASIC` also against available claim blocks.

Who may drag foreign corners: owner or `MANAGE` trust; `SUBDIVIDE` only subdivisions; admins with `coreengineclaim.adminclaims` anywhere.

> **Tip:** Each corner is drawn as a small L shape (corner block plus one arm each way). Clicking the corner block or an arm snaps to the real corner.

## Subdivisions

Sub-areas inside a top-level claim with their own trust list (room, shop, team plot). Commands belong to `coreengineclaim.claims` (default `true`).

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| Subdivide mode | `/claim subdivide` (`sc`) | `coreengineclaim.claim.subdivide` | true | Shovel into subdivision mode; again = back to `BASIC` |
| Toggle inheritance | `/claim restrictsubclaim` (`rsc`) | `coreengineclaim.claim.restrictsubclaim` | true | Trust inheritance from the parent on/off (while standing in it) |

In `SUBDIVIDE` mode the same two-click flow; the first click picks the parent claim. The subdivision must lie fully inside the parent and must not overlap siblings. It inherits the owner, costs no claim blocks of its own and follows the parent on transfer and deletion.

`/claim restrictsubclaim`: **off** (default) = missing trust falls back to the parent; **on** = only its own trust list counts.

```yaml
Claims:
  MaximumSubdivisionsPerClaim: 100   # 0 or negative = unlimited
```

## Stick: inspect a claim

| Action | Result |
|---|---|
| Right-click a block | Claim there or "Wilderness" |
| Right-click into the air | Checks up to 30 blocks ahead, else your own position |
| Sneak+right-click (stick) | All claims within `Claims.NearbyClaimRadius` (default 30) |
| Right-click (bone) | Subdivision at that spot (block or up to 30 blocks ahead), else a hint |
| Sneak+right-click (bone) | All subdivisions within `Claims.SubdivisionNearbyRadius` (default 200) |

A click on wilderness cancels a running display instantly. Cooldowns: `Claims.StickCooldownMillis` (500), `Claims.SubdivisionVisualizationCooldownMillis` (200).

The info actionbar shows more depending on permissions:

| Additional permissions | Default | Extra info |
|---|---|---|
| `coreengineclaim.seeclaimsize` | false | Exact width/length/area |
| `coreengineclaim.seeinactivity` | false | Days since the owner's last activity |
| `coreengineclaim.seeblockhistory` | false | CoreProtect block history at the spot (if installed) |
| `coreengineclaim.visualizenearbyclaims` | true | Sneak+stick shows nearby claims |
| `coreengineclaim.visualizenearbysubdivisions` | true | Sneak+bone shows nearby subdivisions |

## Border display

Pure fake blocks, visible only to you, no client mod needed.

| Claim type | Corner | Edge |
|---|---|---|
| Normal claims | Glowstone | Gold block |
| Subdivisions | Iron block | White wool |
| Admin claims | Glowstone | Pumpkin |

```yaml
Claims:
  VisualizationDurationSeconds: 30       # then automatic revert
  VisualizationAntiCheatCompatMode: false
```

Ends instantly on logout, kick, world change or when a new display replaces it. Corners as L shapes, edges as dotted markers every 6 blocks.

## Auto-claim for new players

When a player places their first chest, a claim forms around it automatically.

```yaml
Claims:
  AutomaticNewPlayerClaimsRadius: 4   # negative = disabled
```

Happens exactly once per account (never reset), only in `Survival`/`SurvivalRequiringClaims` worlds and only if the spot is free. The square forms exactly around the placed block. If claim blocks are short, the difference is credited to the bonus pool, so the auto-claim practically never fails.

> **Tip:** The claim manual can be created any time from a held book via `/claim book`.

## Claim-block economy

Every claim permanently costs its area. Two pools per player: **accrued** (earned, capped) and **bonus** (bought/admin, uncapped).

```yaml
Claims:
  InitialBlocks: 400
  BlocksAccruedPerHour: 100
  MaxAccruedBlocks: 80000
  AccrualIntervalMinutes: 5
  AbandonReturnRatio: 1.0          # < 1.0 subtracts the difference as a penalty
  InitialBlocksByGroup: {}         # e.g. vip: 800
  AccrualPerHourByGroup: {}        # e.g. vip: 150
Economy:
  ClaimBlocksPurchaseCost: 0.0     # <= 0 disables buying
  ClaimBlocksSellValue: 0.0        # <= 0 disables selling
```

Accrual is recomputed every `AccrualIntervalMinutes` and on each login from lifetime playtime and never decreases.

**Rank bonuses** (highest wins):

| Additional permissions | Default | Description |
|---|---|---|
| `coreengineclaim.initialblocks.<n>` | false | Starting blocks directly, e.g. `.800` |
| `coreengineclaim.blocksperhour.<n>` | false | Accrual/hour directly, e.g. `.150` |
| `coreengineclaim.rank.<key>` | false | Tier from `InitialBlocksByGroup`/`AccrualPerHourByGroup` |

**Buy/sell** (children of `coreengineclaim.buysellclaimblocks`, default true):

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| Buy | `/claim blocks buy <amount>` (`buy`, `buyblocks`) | `coreengineclaim.claim.blocks.buy` | true | Buy bonus blocks |
| Sell | `/claim blocks sell <amount>` (`sell`, `sellblocks`) | `coreengineclaim.claim.blocks.sell` | true | Sell bonus blocks |

Flow: charge money first, then adjust blocks; if step two fails, the money is refunded. Selling cannot push the total below the player's effective starting value.

**Admin** (children of `coreengineclaim.adjustclaimblocks`):

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| Adjust | `/claim admin blocks adjust <player> <delta>` | `coreengineclaim.claim.admin.blocks.*` | false | A player's bonus blocks |
| All online | `/claim admin blocks adjustall <delta>` | `coreengineclaim.claim.admin.blocks.*` | false | Bonus blocks of all online players |
| Set accrued | `/claim admin blocks setaccrued <player> <amount>` | `coreengineclaim.claim.admin.blocks.*` | false | Set earned blocks exactly |

## Manage & abandon

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| Your claims | `/claim list` (`claims`) | `coreengineclaim.claim.list` | true | Paginated overview |
| Abandon | `/claim abandon` (`unclaim`) | `coreengineclaim.claim.abandon` | true | The claim/subdivision you stand in |
| Abandon all | `/claim abandonall` (`unclaimall`) | `coreengineclaim.claim.abandonall` | true | All your top-level claims |
| Manual | `/claim book` (`claimbook`) | `coreengineclaim.claim.book` | true | Turn a held book into the manual |
| Escape a claim | `/claim trapped` | `coreengineclaim.claim.trapped` | true | Teleport to the nearest free, safe spot |

`/claim abandon` asks you to type `abandon`; in a subdivision it only affects that one. `/claim abandonall` then requires your exact own name. With `AbandonReturnRatio < 1.0` the penalty is subtracted from the accrued pool per claim.

`/claim trapped`: only inside a foreign claim without `ACCESS` trust and without combat tag. After 60 s (cancels on movement) it teleports to the nearest free spot, then a 300 s cooldown.

Claims can also be viewed and abandoned in the web interface (`/cweb`, "Claims" category).

## Expiration

```yaml
Claims:
  ChestClaimDays: 7      # Tier 1: auto-claims only, WITH refund
  AllClaimDays: 0        # Tier 2: all top-level claims, NO refund; 0 = off
Advanced:
  ClaimExpirationCheckRate: 60   # minutes; <= 0 = task off
```

For inactive players: Tier 1 refunds the area to the accrued pool, Tier 2 does not. If Tier 1 hits, Tier 2 is skipped that run. Admin claims and subdivisions are never checked directly (subdivisions go with the parent). In `Creative` worlds deletion also triggers Restore Nature.

> **Note:** `Claims.UnusedClaimDays` is a reserved compatibility key with no function. Use `AllClaimDays` or `ChestClaimDays`.

## Full example config

```yaml
Claims:
  InvestigationTool: STICK
  ModificationTool: GOLDEN_SHOVEL
  SubdivisionVisualizationTool: BONE
  StickCooldownMillis: 500
  NearbyClaimRadius: 30
  SubdivisionVisualizationCooldownMillis: 200
  SubdivisionNearbyRadius: 200
  MinimumWidth: 5
  MinimumArea: 25
  MinimumYOverrides:
    world_nether: 127
  AutomaticNewPlayerClaimsRadius: 4
  InitialBlocks: 400
  BlocksAccruedPerHour: 100
  MaxAccruedBlocks: 80000
  AbandonReturnRatio: 1.0
  InitialBlocksByGroup:
    vip: 800
    premium: 1200
  AccrualPerHourByGroup:
    vip: 150
    premium: 200
  ChestClaimDays: 7
  AllClaimDays: 0
  MaximumNumberOfClaimsPerPlayer: 0
  MaximumSubdivisionsPerClaim: 100
  VisualizationDurationSeconds: 30
Economy:
  ClaimBlocksPurchaseCost: 0.0
  ClaimBlocksSellValue: 0.0
Advanced:
  ClaimExpirationCheckRate: 60
```