# UI Pages

**Version:** 1.0.0

Players use the **guild window** (`/ksguild`) and the **lock window** (`/ksguild lock`). Admins use the **admin window** (`/ksguild admin`). All windows use the KyuubiSoft "Goldfiligran" look and come in 9 languages.

:::note
The pictures on this page are design previews of the windows; names, values and items are examples. The windows have not been tested in game yet.
:::

## Overview

| Window | How to open it | Notes |
|--------|----------------|-------|
| [Guild window](#guild-window) | `/ksguild` (also `/guild`, `/gilde`) | Needs `ks.guilds.user.open` (allowed by default) |
| [Lock window](#lock-window) | Look at a chest or door and type `/ksguild lock`, or click a row on the **Locks** tab | Only for blocks you may lock or change |
| [Cards](#cards-at-the-top-of-the-screen) | Appear by themselves | Without the card display, the same notice comes as one chat line |
| [Admin window](#admin-window) | `/ksguild admin`, or the **Guilds** tile in the `/ksadmin` hub | Needs `ks.guilds.admin` |

---

## Guild window

The header shows **Guild** and a line like "The Night Watch [NW] · your rank: Leader · /ksguild". **X** closes the window.

**Side panel** (left, on every tab while you are in a guild):

- The crest, the guild name, the tag and the joining mode.
- The level with an experience bar.
- **Leader**, **Members** ("12 / 25 · 4 online"), **Storage** ("3 of 6 pages"), **Locks** (guild locks used / limit) and **Guild home**.
- The **Announcement** with author and time. **Edit** opens a box for up to 200 characters, with **Save** and **Remove**; it needs the rank right **Write the announcement**.
- **To the guild home** starts the trip. When that is not possible the button says why, for example "Guild home from level 2", "No guild home set", "Your rank does not travel", "Travelling · 3 s left" or "Next trip in ...".
- **Invite** and **All guilds**.

**Tabs** while you are in a guild: **Members**, **Level**, **Storage**, **Ranks**, **Locks**, **Guild land** (only with KyuubiSoft Claims 2.0) and **Settings**. The chronicle and the list of all guilds open through buttons.

Without a guild the window has two tabs: **Found a guild** and **All guilds**.

### Members

![Members](../../../../assets/guilds/guilds-members.png)
*The guild window: members with rank and online state, open join requests and invitations, and the actions for the chosen member.*

- Filters **All**, **Online** and **Leadership** with their counts, a name search and **Invite**.
- **Open:** join requests ("wants to join · 40 min ago") with **Accept** and **Decline**, and running invitations ("invited by Kyuubi · expires in 7 min") with **Withdraw**. Accepting and declining needs **Accept join requests**, withdrawing needs **Invite members**.
- **Member list:** name (with **You** for yourself), rank, "Online · <world>" or when the member was last seen, and since when they are in the guild.
- **Selected member:** a bar at the bottom with **Promote to <rank>**, **Demote**, **Hand over the lead** and **Remove**, as far as your rank allows. For yourself it shows **Leave the guild**. Removing, leaving and handing over ask once more before they happen.

**Invite** opens a box: type a name, or pick someone under **Online without a guild**, then **Invite**.

### Level

![Level](../../../../assets/guilds/guilds-level.png)
*Level and build-up: experience towards the next level, the material the guild hands in, what the next level brings and this week's top contributors.*

- **Level bar:** "6,600 experience to level 5" and the total. Below it your own day: "You added 340 of 500 experience today", or "Your experience counts from <time> – 24 hours after joining" for new members.
- **Build-up for level N:** each material with handed in / needed, **DONE** when complete. **Hand in from inventory** takes only what is still missing from your inventory. Levels without material say "Level N only needs experience."
- **Level N brings:** the new member slots, storage page, guild locks, guild home, rank, colours, crests, frame or hall of fame.
- A row of diamonds for levels 1 to 10.
- **This week:** the members who earned the most experience this week.
- **Recently:** the latest chronicle entries and **Whole chronicle**.

With the level system off the tab says "The level system is off – fixed limits apply."

### Storage

![Storage](../../../../assets/guilds/guilds-storage.png)
*The shared guild storage with its pages, your inventory below, your rights and the log of who put in or took out what.*

- **Page tabs:** one per page. Pages that come later show their level: "Page 4 · from level 5".
- **The page** (36 slots) and **Your inventory · hotbar** below it. Click or drag to put in and take out; one click moves the whole stack.
- **Your rights:** for example "Putting in is allowed. Taking out: 40 of 64 items left today." or "Look only."
- **Log:** "Mira took 16 Iron Ingot · 10 min ago · page 1", kept for 30 days.

Only one person at a time can change a page. Others see "Aldric has page 2 open right now. You can look; changes are possible once Aldric is done." The page frees up when that person closes the window, switches the page, changes the world or leaves. Items that do not fit into your inventory when you take them out drop on the ground next to you.

### Ranks

![Ranks](../../../../assets/guilds/guilds-ranks.png)
*Ranks: rename them and set what each rank may do. The leader always has every right.*

- One name field per rank with the number of people in it. Empty fields use the default name; at most 16 characters. **Save names** stores them.
- A grid of rights with a checkbox per rank. Clicking a box changes the right at once.
- Only the leader changes names and rights; everyone else sees the grid read-only.
- The Veteran column appears from level 6.

### Locks

![Locks](../../../../assets/guilds/guilds-locks.png)
*All guild locks and your private ones. Click a row to change who may open it.*

- **Tiles:** guild locks used / limit, your private locks used / limit, and how many attempts the locks fended off this week.
- **Filters:** **All**, **Containers**, **Doors and gates**, **Private**.
- **Rows:** block, **GUILD** or **PRIVATE**, world and position, who may open it ("from Member", "you + Mira") and who set it when.
- Click a row to open the [lock window](#lock-window) for that lock, wherever it is.
- **Lock automatically** at the bottom switches your automatic locking.

### Guild land

Only shown when KyuubiSoft Claims 2.0 is connected.

- **Tiles:** areas, chunks, and from which rank members may build.
- **Rows:** claim name and size, where it is, who handed it over, "Build from <rank>" and "Chests and doors from <rank>". An area that no longer exists in Claims shows **Area gone**.
- **Edit** (needs **Manage guild land**) sets **Build from rank** and **Chests and doors from rank**.
- To add land, stand in your own claim and type `/ksguild land add`.

### Settings

![Settings](../../../../assets/guilds/guilds-settings.png)
*Settings: name, tag, colour, coat of arms, joining, damage between members and the guild home, plus your own auto-lock and guild chat.*

**Guild** (only the leader changes these):

- **Name** and **Tag** with **Save**.
- **Colour** and **Coat of arms**. Colours and crests of higher levels are greyed out.
- **Joining:** **Open**, **On request** or **Invite only**.
- **No damage between members** ("Arrows do not hit guild members either"). Shows "Switched off on this server" when the admin forbids it.
- **Guild home** and, from level 7, **Second guild home**: where it is and who set it, with **Remove** and **Set here** (needs **Set the guild home**).

**Only for you:**

- **Lock new chests and doors:** **Not automatically**, **For me** or **For the guild** (members from rank Member).
- **Write in the guild chat:** while on, your normal chat goes to the guild. `/gc` switches it too.

At the bottom: **Hand over the lead** and **Disband the guild** for the leader, **Leave the guild** for everyone else, each with a confirmation.

### Chronicle

The last 100 events of the guild: founding, joins and leaves, rank changes, new leaders, announcements, level-ups, renames, guild homes, guild land, guild locks and admin changes. Every member can read it. Open it with **Whole chronicle** on the **Level** tab.

### All guilds

![All guilds](../../../../assets/guilds/guilds-all-guilds.png)
*All guilds on the server, ranked by level, with buttons to join, send a request or accept an invitation.*

- A search for name or tag, and "7 guilds · sorted by level".
- Each row: crest, name, tag, place in the ranking, level, members and how many are online. Your own guild is marked **Your guild**; guilds with the hall of fame stand out.
- Buttons, depending on the guild and on you: **Join** (open guilds), **Send request**, **Withdraw request**, **Accept invitation** or **Full**.

### Found a guild

![Found a guild](../../../../assets/guilds/guilds-found.png)
*Without a guild: found your own with a preview of tag and coat of arms, or accept an invitation.*

- **Left:** "Not in a guild yet", your **Invitations** with **Accept** and **Decline**, and your sent requests with **Withdraw**.
- **Name and tag** with a live check ("Name and tag are still free"), **Colour**, **Coat of arms** and **Joining**.
- **How it looks:** the crest, the chat line "[SL] Wren: Hello everyone!" and the tag above the head ("Above the head only with KyuubiSoft Nameplates").
- The price line: "Free · the admin can set a founding fee", or "Founding costs <amount>".
- **Found the guild.** You take the rank Leader. Name and tag can be changed later.

---

## Lock window

![Lock window](../../../../assets/guilds/guilds-lock-window.png)
*Locking a chest with /ksguild lock: for yourself or for the guild from a chosen rank, plus extra players.*

The title is **Add a lock**, **Change the lock** or **Lock** (look only), with the block, its world and position.

- **Who owns the lock:** **Only me** ("plus extra players") or your guild ("the guild · from a rank"). The guild choice is greyed out without a guild ("You are not in a guild") or without the rank right ("Your rank does not lock for the guild").
- **Opens from rank** (guild locks): Novice, Member, Veteran (from level 6), Officer, Leader. The line below says who that is: "Open for Member, Officer, Leader. Admins always get in."
- **Also allow:** single players by name, with **Add**.
- **What is protected:** opening, carrying, breaking and explosions, plus who may break it. "The block below stays too, and nobody can place a chest or door right next to it. Fire can still burn wood."
- **Count:** "Counts as a guild lock: 8 of 150 · big chests count once" or "Counts as one of your private locks: 3 of 50".
- Buttons: **Cancel** and **Lock** for a new lock; **Save**, **Unlock** and **Back** for an existing one.

"Admins always get in" means players with `ks.guilds.admin.bypass`, see [Permissions](./permissions).

---

## Cards at the top of the screen

Guild notices appear as cards at the top centre, one after another. With KyuubiSoft Core installed they take a row of Core's shared card row, so they do not cover the cards of other KyuubiSoft mods. When the card display is not available for a player, the same notice comes as one chat line.

| Card | When |
|------|------|
| **Invitation** | You are invited, with the minutes left. Open invitations show again when you log in |
| **Join request** | Someone wants to join (for members who may accept requests) |
| **New member** | Someone joined your guild |
| **Welcome** | You joined a guild |
| **No longer in the guild** | You were removed; also at your next login if you were offline |
| **New rank** | You were promoted, demoted or made leader |
| **New guild level** | The guild reached a level, with the new limits |
| **Material handed in** | Your hand-in, with how far the build-up is |
| **Guild founded** | You founded a guild |
| **Guild disbanded** | Your guild was disbanded; also at your next login |
| **Trip to the guild home** | During the warm-up, with a live countdown |
| **Trip cancelled** | You moved, took damage, left the world, or the home is gone |
| **Locked** | You tried to open a lock you have no access to. A chat line names the owner and the rank |
| **Bench locked** | A workbench has a locked chest in reach that you may not open |
| **Not allowed to break** | You tried to break a locked block, or the block under one |
| **Not here** | You tried to place a chest, door or bench too close to a foreign lock |
| **Locked automatically** | Your automatic locking locked a block you placed |

"Locked" messages come at most once every 3 seconds per player and lock (`locks.denyMessageSeconds`).

**Chat:** the guild tag stands in front of every member's name in the chat, in the guild colour. Guild chat lines read "Guild › Mira: text". Level-ups are announced in the guild chat, and a new guild is announced to everyone online.

---

## Admin window

![Admin window](../../../../assets/guilds/guilds-admin.png)
*The admin overview: numbers for the whole server, recent guild events and which optional mods are connected.*

The admin window has six sections on the left. Changes apply at once and are written to the guild's chronicle. Every click checks `ks.guilds.admin` again.

### Overview

- **Tiles:** guilds, members in total, locks, highest level (with the guild's tag) and attempts blocked by locks in the last 7 days.
- **Recently on the server:** foundings, joins, full guilds, new leaders, level-ups, disbanded guilds, new locks, guild land and refused names.
- **Connected:** each optional mod and what it adds right now. Claims shows "Guild land" only while the guild land link really runs; with an older Claims it says "installed · guild land not connected yet". VoiceHub shows "installed · voice channel switched off" when `integration.voiceChannel` is off.

### Guilds

- A search for guild, tag or member, and the list of all guilds.
- The selected guild: founded when and by whom, level and experience, members / slots, guild locks, guild land areas and last activity, plus its members.
- **Step in:**

| Button | What it does |
|--------|--------------|
| **Rename** | New name; the guild gets a chronicle entry |
| **Change tag** | New tag |
| **Set leader** | Pick the new leader; the old one becomes Officer |
| **Remove member** | Pick a member to remove. Private locks stay with the person, guild locks with the guild |
| **Show locks** | Opens the **Locks** section filtered to this guild |
| **Delete guild home** | Pick a home to delete |
| **Set level** | Any level from 1 to the highest. The experience is raised to the threshold, the build-up starts fresh |
| **View storage** | Opens the guild storage, look only. **To the admin panel** leads back |
| **Disband guild** | Disbands the guild even when its storage is not empty: guild locks go to the last leader, guild land becomes normal land again and the storage goes to `lager/archive/<id>.json` |

### Levels

- Switches **Level system** and **Level bonuses**.
- The level table with experience, build material, slots, storage pages, locks and what each level adds. Click a row to edit it: experience, slots, storage pages, guild locks, the experience bonus from this level and the build materials, picked from a searchable item list.
- **Experience for the guild:** the values for creature, boss, ore, quest, achievement and play time.
- **Against farming:** daily limit per member, after how many hours new members count, and the play time interval.

### Rules

- **Guilds:** shortest and longest guild name and tag, how long an invitation lasts, the founding fee.
- **Without the level system:** members, guild locks, storage pages and guild homes per guild.
- **Combat and guild home:** "Allow protection from own people" and "Guild home". **Trip to the guild home:** warm-up and cooldown.
- **Locks:** containers lockable, doors and gates lockable, protect from explosions, protect the base and neighbours, benches ask the lock, allow locking on placing. **Limits for locks:** private locks per person, expire after, seconds between two "locked" notices.
- **Guild storage · taking out per day:** one field per rank (-1 = no limit) and how many days the log keeps.
- **Connections:** "Guild voice channel" for VoiceHub.

See [Configuration](./configuration) for every value.

### Locks

- A search for guild, person or world, and the filters **All**, **Guild**, **Private** and **Abandoned** (no visit of the owner, or no activity of the guild, for over 60 days).
- Each lock with owner, place, access, who set it and when it was last opened.
- **Travel** teleports you to the lock. **Remove** (click again on **Sure?**) removes it; the block stays where it is.
- **Remove the lock in view** removes the lock of the block you look at.
- **Remove all of one person** removes every private lock of one player.

### Names

- **Forbidden words:** names, tags and announcements with these words are refused. Add and remove words.
- **Reserved tags:** tags no guild can take.
- **Check:** test a name and a tag the same way as founding does.