# UI Pages

**Version:** 2.0.0 (not released yet)

Players use one window with six tabs, small notices at the top of the screen and the glowing border. Admins have a window of their own. Everything appears in the player's language and uses the KyuubiSoft "Goldfiligran" look. A few parts carry a **NEW** badge.

| Window | How to open it |
|--------|----------------|
| [Claims window](#the-claims-window) | `/ksclaim` (also `/claim`, `/claims`), or a showcase NPC |
| [Notices](#notices) | They appear by themselves |
| [Border](#the-border) | **Show border** in the window, `/ksclaim border`, or entering a claim with **Border when entering** on |
| [Admin window](#the-admin-window) | `/ksclaimadmin`, or the Claims tile in the `/ksadmin` hub (with KyuubiSoft Core) |

---

## The claims window

### Header and tabs

- **Claims** and a line that says where you stand: `You stand on Mira's Farm · /ksclaim`, `You are in the server zone Spawn · /ksclaim` or `You stand on free land · /ksclaim`.
- The tabs **Map**, **Claims**, **Rights**, **Zones**, **Settings** and **Log**. The window opens on **Map**.
- Next to the tabs a short note: the map size (`19 × 15 chunks`), how many claims you see (`3 claims · 2 own`), the claim the tab shows, or how many actions were refused this week.
- **Rights**, **Zones** and **Settings** work on one claim. With more than one claim, **‹** and **›** switch between them.
- A status line shows the result of the last click, green when it worked and red when not.
- Without any claim, these three tabs show **No claim yet** with a **To the map** button.

### The left column

**Here** describes the chunk you stand on:

- Its name with a coloured chip: **Your land**, **You may enter**, **Guild land**, **Foreign land**, **Banned**, **Server zone** or **Free land**, plus the zone if there is one.
- Facts: **Belongs to**, **Your role** (or **Chunk**), **Claim** (chunks and people), **Your rights** (`all`, `none`, one or two names, or `5 of 12`) and **Fighting here**. On free land and in server zones: **Chunk**, **World**, **Claimable** and **Fighting here**.

**Your quota** shows how many chunks you use of your quota, a bar, `Claims: 2 of 5`, and with growth switched on when the next chunks come.

Buttons:

| Button | What it does |
|--------|--------------|
| **Show border** | The border of the claim you stand in glows for 10 seconds. The window closes so you can see it |
| **Set home here** | Sets the home of the claim you stand in, where you stand. Only with the right to manage it |
| **Travel home** / **Home: ...** | Travels to the home of the chosen claim. Grey with the reason when it cannot: **No claim yet**, **No home set**, **Home travel locked**, **On the way …** or `8 s left` |

### Map

The map shows 19 × 15 chunks around you. **Centre** brings it back to you after **On the map** moved it to a claim.

**Legend:** **Your land**, **Zone in your land**, **You may enter** (land where you have a role), **Foreign land**, **Guild land**, **Server zone**, the selection, **You** and **Home**.

**Terrain** (marked **NEW**, legend line `Terrain from the world map · 4 × 4 per chunk`): each chunk shows the ground of the world map as 4 × 4 colour squares. The state of the chunk lies on top as a light tint in the legend colour with a thin ring, so the terrain stays visible.

- The colours come from the world map images the server already has. Chunks whose colours are not known yet stay dark grey and fill in a moment later, without the window being opened again. Claims never loads a chunk just for the map.
- No terrain in instance worlds, in worlds without a world map, or when the admin switched it off with `display.mapTerrain` in `config.json`. Then the map is flat: every chunk in its legend colour.

Three modes:

| Mode | Click on | Button |
|------|----------|--------|
| **Claim** | free chunks | **Claim** |
| **Release** | chunks of your own claims | **Release** |
| **Pick zone** | chunks of a claim you manage | **Create zone** |

- A click selects a chunk, a second click takes it out. **Clear** empties the selection. Up to 64 chunks at once.
- In **Release** and **Pick zone** the selection stays inside one claim. A click in another claim starts a new selection there.
- The panel under the map says what will happen, before you click:
  - Claim: `Then 9 of 25 used.`, `A new claim is made.`, `“Mira's Farm” grows.`, `Touches several of your claims – you choose which one grows.`, the distance to keep to foreign land and the price.
  - Release: `The chunks become free, blocks stay. “Mira's Farm” keeps 10 chunks.` and the refund. Choosing every chunk asks whether to dissolve the claim.
  - Pick zone: `Zone in “Mira's Farm” · you name it in the next step.`
- Clicks that cannot work tell you why: `This chunk is not free.`, `Nobody can claim land in this world.`, `Nothing to pick here in this mode.` or `At most 64 chunks at once.`

After claiming, a notice **Claimed** shows `9 chunks for Mira's Farm` and the new size.

### Claims

A list of your claims, the claims where you have a role and guild land you may use. Each row shows the name, your role (or the guild label), the world, the middle of the claim (`around 1030 / -300`), the number of zones, the owner, chunks and people.

The chosen claim gets a bar with a note (`You manage this claim`, `You may help manage it, but not dissolve it`, `Your role here: Trusted` or `Access through Guild land`) and these buttons:

| Button | What it does |
|--------|--------------|
| **Travel** | Travels to the home (only when the claim has one and you may use it) |
| **On the map** | Opens the map centred on the claim |
| **Rights** | Opens the **Rights** tab of the claim |
| **Dissolve** | Owner only: asks, then dissolves the claim |
| **Leave** | With a role: asks, then gives up your role |

### Rights

**Who may what** is the rights table of the claim: one row per right, one column each for **Visitor**, **Trusted** and **Co-owner**.

- `A click switches a right`. Dimmed ticks are inherited from a role to the left and cannot be clicked.
- Only the owner changes the **Co-owner** column and the **Manage people and settings** row. Players who may not manage see `View only: you may not manage`.

**People** lists everyone with a role, co-owners first, with a dot that shows who is online:

- **Add player** and **Add** give a player the role Trusted, **Ban** bans them.
- A click on the role switches between **Trusted** and **Co-owner** (owner only). **×** takes the role away.

**Banned** lists the banned players with `may not enter · for 3 days`. **Lift** lifts the ban.

On guild land the note reads `Banned players are pushed back. For guild land the guild ranks apply as well.`

### Zones

- The list of zones of the claim with their chunks and the rules they change. **New zone from selection** takes the chunks picked in the mode **Pick zone**, or switches the map to that mode.
- A mini map of 7 × 5 chunks shows where the chosen zone lies.
- The rules table: one row per right, one column each for **Visitor** and **Trusted**. A click switches **like the claim** › **allowed** › **forbidden** › **like the claim**. A Trusted cell shows **inherited** where visitors already may.
- **Rename** and **Delete** (asks first; the chunks stay part of the claim).

See [Rights and Roles](./rights-and-roles#zones).

### Settings

| Part | Content |
|------|---------|
| **Claim** | **Name** and **Greeting on entering**, each with **Save**. Players who may not manage see the text only |
| **What may happen here** | **Fights between players**, **Explosions damage blocks**, **Fire only with the build right**, **Flying for trusted people**, **Keep inventory on death**. Switches the server has not allowed are grey: **Not released by the server** |
| **Home** | Where the home is, **Set here** and **Remove** |
| **Display** | **Border when entering** and **Greeting at the top** |
| At the end | Owner: **Hand over** and **Dissolve claim**. With a role: **Leave claim** |

**Hand over** asks for a player name. The player must be online and accept with `/ksclaim accept` within 5 minutes.

### Log

The last 30 days of every claim you manage, newest first, up to 80 lines. The filters are **All**, **Refused** and **Changes**.

Each line says what happened (`Tom tried to open a container (missing right)`, `Mira is now Trusted`, `3 chunks claimed · now 12 chunks`), the claim, who did it, how often (`4×`) and when.

### Dialogs

| Dialog | When |
|--------|------|
| **Which claim should grow?** | The selection touches several of your claims. `Claims never merge on their own.` |
| **Dissolve claim?** | **Dissolve**, **Dissolve claim** or releasing every chunk. Blocks stay, the log stays 30 days |
| **Leave claim?** | **Leave** or **Leave claim** |
| **Hand over** | **Hand over**, with a player field and **Offer** |
| **New zone** | **Create zone**, with the zone name |
| **Rename zone** / **Delete zone?** | **Rename** / **Delete** on the **Zones** tab |

---

## Notices

Notices are small cards at the top centre of the screen. One shows at a time, the others wait. With KyuubiSoft Core installed, a card takes a row of Core's shared card row, so it never covers the cards of other KyuubiSoft mods. If the card cannot be shown, the notice becomes one chat line.

| Notice | When |
|--------|------|
| **Claim** · `PvP on` / `PvP off` · name · greeting or `belongs to Mira` | Entering a claim with **Greeting at the top** on. On guild land the label of the guild replaces **Claim** |
| **Server zone** · name · greeting or `Nobody can claim land here.` | Entering a server zone |
| **Free land** · **No man's land** · `You can claim land here · /ksclaim` | Stepping onto free land |
| **Protected** · right · claim · `You lack the right “Open containers”. Ask Mira.` | Something was refused |
| **Protected** · `PvP off` · `Players cannot hurt each other here.` | A hit on a player was stopped |
| **Explosion stopped** · `The blocks in the claim stayed where they were.` | An explosion was stopped in your claim while you were within 96 blocks of it |
| **No entry** · `You are banned from this claim and were pushed back to its edge.` | A banned player walked in. In a closed server zone: `Nobody may enter this server zone. You were pushed back.` |
| **Claimed** | Chunks were claimed in the window |
| **Border** · `12 chunks` · `The edges glow for 10 seconds` | **Show border** or `/ksclaim border` |
| **Travelling home** · countdown · `Don't move – it starts in a moment` | A home trip starts |
| **Trip cancelled** · `You moved.`, `You were hurt.`, `The home is gone.` ... | A home trip was cancelled |
| **Flying** · `You can fly in this claim.` / `Flying ends here – no fall damage for 10 seconds.` | Entering or leaving a claim where you may fly |
| **New role** · `You are now Trusted` | Someone gave you a role |
| **Claim offered** · `Mira offers it to you · /ksclaim accept · 5 min` | Someone offers you a claim |
| **Handed over** · `now belongs to Tom` | Your offer was accepted |
| **Quota grew** · `+5 chunks from play time` | Growth with play time |
| **Abandoned claim?** | At login, inside the warning time of abandoned claims |

- The notice for entering shows at most every 10 seconds per claim (`display.enterToastCooldownSeconds`).
- A refusal also sends one chat line: `Protected · Mira's Farm belongs to Mira. You lack “Open containers”.` Refusal messages come at most every 3 seconds per player (`protection.denyCooldownSeconds`). Admins can switch them off with **Message on a refusal**.
- While the session bypass is on, `Protection bypass on` stays next to the compass.

---

## The border

Golden light pillars stand on the outer edges of the claim, every 8 blocks and at the corners, within 64 blocks of you. They glow for 10 seconds (`display.borderSeconds`). Only you see them; other players see nothing.

- **Show border** (left column of the window) and `/ksclaim border` show the claim you stand in, also a claim of someone else.
- With **Border when entering** on, the border glows for everyone who walks in.

---

## The admin window

`/ksclaimadmin` opens the window (needs `ks.claims.admin`). On the left are four pages and the note `Admins with ks.claims.admin.bypass ignore the protection. Every change is written to the claim's log.` Numbers are live. The window closes when the admin node is taken away.

### Overview

- Five tiles: **Claims**, **Chunks**, **People with a claim**, **Server zones** and **Blocked · 7 days**.
- **Recently blocked and changed**: the latest refusals and changes of all claims and server zones. A click opens the claim or server zone.
- **At a glance**: **Largest claim**, **Abandoned 60+ days**, **Guild land**, **Worlds with claims**, **Most blocked · 7 days**, **Claims expire** (`never` or `after 30 days`) and **Economy** (`on · 100 per chunk`).
- After taking over an older Claims version: `At this start 42 claims and 2 server zones were taken over from Claims 1.x (1 conflicts, see migration-report.txt).`

### Claims

- **Search** by claim, owner or world, and the filters **All**, **Abandoned** (claims without activity for 60 days, longest first), **Guild land** and **Large** (largest first).
- The chosen claim: `belongs to Mira · Main world · last active 3 days ago`, the facts **Chunks**, **Quota**, **People** (with banned), **Zones**, **Blocked · 7 days** and **Claimed**, and its people.

Under **Step in**:

| Button | What it does |
|--------|--------------|
| **Travel there** | To the claim home, or to the middle of the claim |
| **Show border** | Lets the border glow for you. Only near the claim: `Travel there first.` |
| **Change owner** | A list of players to search, with online and last seen. The claim changes owner at once, the old owner keeps no role |
| **Change quota** | Sets the **Bonus chunks** of the owner |
| **Release chunks** | Opens the admin map: click chunks of the claim. The claim must not fall into two parts, the last chunk stays |
| **Log** | The log of the claim with the filters **All**, **Blocked** and **Changes** |
| **Lift a ban** | A list of the banned players |
| **Make server zone** | Dissolves the claim and makes a server zone of its chunks, with a name you give |
| **Dissolve claim** | Asks, then dissolves the claim. Blocks stay, the log stays 30 days |

### Server zones

- The list of server zones with their chunks and world, and **New zone from a map selection**.
- The chosen zone: its chunks, world and who created it when, **Greeting on entering** with **Save**, and **Rules in ...**: **Enter**, **Build and break**, **Open containers**, **Doors and gates**, **Use benches**, **Fights between players** and **Explosions damage blocks**. A click switches a rule at once.
- **Rename**, **Change area**, **Travel there** and **Delete zone** (asks first; the chunks become free land).

### The admin map

The admin map shows 19 × 13 chunks around you, a server zone or a claim. **‹ West**, **North**, **South**, **East ›** move it, **Middle** brings it back. Every chunk is a button.

| Mode | Click on | Button |
|------|----------|--------|
| New server zone | free chunks (claimed land stays with its owner) | **Create zone**, with the zone name |
| Change area | chunks of the zone to take them out, free chunks to add them | **Save area** |
| Release chunks | chunks of the claim | **Release** |

### Rules and protection

| Group | Content |
|-------|---------|
| **Quota and distance** | **Starting quota**, **Growth**, **Growth step**, **At most**, **Claims per player**, **Distance to foreign land** |
| **Abandoned claims** | **Abandoned after**, **Warning before**, **List "Abandoned" from** |
| **Economy** | **Claiming costs money**, and under **Prices**: **Price per chunk**, **Refund**, **Buying quota** |
| **Worlds** | Every loaded world: a click switches between `claiming allowed` and `claiming locked`. **Lock world** adds a world by name. `Instance worlds (dungeons) · never` |
| **Protection for every claim** | **Stop explosions**, **Creatures break nothing**, **Prevent attaching**, **Protect what is below**, **Workbenches ask the claim**, **Only people with rights light fires**, **Message on a refusal**, **Allow flying in claims**, **Allow keeping the inventory** |
| **Messages and home** | **Refusal message**, **Entering note**, **Border shows**, **Home warmup**, **Home cooldown** |
| **Exceptions** | Words for blocks everybody may use (**Use**) or break (**Break**), added and removed one by one |

Switches and world rows save at once. Each group of numbers has its own **Save** button, and a number out of range is refused with its allowed range. Every change is written to `config.json`. See [Configuration](./configuration) for what each value does.