# UI Pages

**Version:** 2.0.6

This page describes the player windows. The admin window is on [Admin Panel](./admin-panel), the rental stands tab in depth on [Rental Stands](./rentals). Command syntax is on [Commands](./commands).

:::note
The pictures on this page are design previews of the in-game windows. The layout matches the plugin's windows; names, values and icons are examples. The 2.0.0 windows have not been tested in game yet.
:::

## Overview

| Window | How to open it |
|--------|----------------|
| [Market](#market) | `/ksshop browse`, `/ksshop myshops`, `/ksshop myrentals`, `/ksshop rentalstations`, **F** on a free rental stand, **< Market** in a shop window |
| [Shop window](#shop-window) | **F** on someone else's merchant, `/ksshop visit <shop>`, a shop card or **To the shop** in the market |
| [Shop editor](#shop-editor) | **F** on your own merchant, `/ksshop edit`, **Manage** in the market, `/kssa editadmin` and **Edit offers** in the admin window for server shops |
| [Mailbox](#mailbox) | **F** on a Mailbox block; `/ksshop notifications` (view only) |
| [License dialog](#license-dialog) | Right-click with a Shop Business License |

**F on a merchant** decides by who you are: a free rental stand opens the market on that stand; the owner of a player shop gets the editor (or the shop window when someone else has the editor open); everybody else gets the shop window. A closed shop only answers its owner; others get "This shop is currently closed." in chat.

The market, the shop window, the editor and the mailbox show your wallet in the header and a status line for the result of your last action (green for success, red for problems).

---

## Market

The market window has four tabs with counts: **Shops**, **Offers**, **Rental stands** (hidden when rental stands are switched off) and **My shops**. The subtitle shows how many shops are open and how many offers are available.

### Shops tab

![Market, Shops tab with filters and shop cards](../../../../assets/player-shops/shops-market.png)
*The Shops tab: filters on the left, one card per listed shop with rating, owner, distance and its first items.*

**Filter panel** (shared with the Offers tab):

- **Search**: shop name, owner name or any item ID the shop has ("iron" finds `Weapon_Sword_Iron`).
- **Type**: All, Server, Player.
- **Category**: All categories or one of Weapons, Armor, Tools, Resources, Potions, Food, Building, Misc, each with its number of shops.
- **Sort**: one button that cycles Best rating, Newest first, Name A-Z, Most sales (by total revenue), Cheapest price. "Best rating" lists featured shops first.
- **Minimum rating**: All, 3+, 4+, 4.5+.

**Shop cards** (3 per row, at most 60; the info line says when more match):

- Icon (the shop's market icon, or its first offer), name, "by [owner]" or "Server shop".
- Up to two chips: Featured, Rental shop, Your shop, the category. When the card has too little room, the second chip is shortened with "…" or left out.
- Rating diamonds with "4.6 (23)" or "No ratings yet".
- Distance in blocks ("40 m away") in your world, otherwise the shop's world name.
- Up to five items it sells, "+N" for more, or "Nothing for sale yet".

Click a card to open the shop window.

**Which shops are listed:** open shops that are not packed up. Server shops always; player shops while their market listing runs (permanent listings included). Free rental stands are not shops and never show here.

### Offers tab

![Market, Offers tab with the buy panel](../../../../assets/player-shops/shops-market-offers.png)
*The Offers tab: every item for sale in one list, the selected offer on the right with quantity, total and balance after.*

One row per item a listed shop sells (at most 120 rows): icon, name, stock (green, amber at 10 or less, red at 2 or less, "Unlimited stock" or "Sold out"), shop, seller and price. Your own shops are left out. Sold-out offers come last and cannot be picked. The order is cheapest first, unless the sort is Name A-Z or Best rating.

The **buy panel** on the right shows the picked offer: rarity, shop, seller, price per piece and stock, then:

- **Quantity** with **-**, **+** and **Max**. Max is the lowest of the stock, one stack (64) and what your wallet pays for, tax included.
- **Total** ("Total incl. 5% tax" when a buy tax is on) and **Balance after**.
- **Buy · [total]**, or a disabled button saying why ("Sold out", "Not enough Gold").
- **To the shop** opens that shop's window.
- A hint where purchases go: "Purchases wait for you in your mailbox." or, with `mailbox.deliverPurchasesToInventory`, "Purchases go into your inventory; what does not fit waits in your mailbox."

A purchase is refused with "This offer just changed." when the owner changed the item or its price after the list was shown.

### Rental stands tab

Lists every rental stand of the server with filters All / Free / Auction / Rented, the stand details on the right, bidding, renting and the live countdown. The tab refreshes every second while it is open. See [Rental Stands](./rentals) for pictures and every detail.

### My shops tab

![Market, My shops tab](../../../../assets/player-shops/shops-my-shops.png)
*My shops: tiles at the top, one row per own shop, a rented stand with its extend and end controls.*

**Tiles:** Shops (the shops that count toward your limit, of your limit), Rental stands (rented of your limit), Revenue · 7 days, New sales (unread sale notifications waiting in your mailbox's Sales tab).

**One row per shop** (packed shops last):

- Icon, name and chips: Open or Closed, plus Rental shop or the listing state ("Listed until Oct 26", "Always listed", "Not listed"); packed shops show "Packed up".
- A line with category, location (or the stand name), distance and "listed for free" for rental shops.
- **Manage** opens the editor (not for packed shops).
- Figures: Offers, Revenue total, Last 7 days, Till, Rating.
- **Shops on a rented stand** get a rental block: "Rental · [stand]", time left and:
  - fixed-price stands: days **-** / **+** (up to `extendMaxDays`) and **Extend · [cost]**;
  - auction stands: "Won at auction - it cannot be extended.";
  - **End rental**, then a confirmation that names the refund for the days left. See [Rental Stands](./rentals#ending-a-rental).
- **Packed shops**: "Use your shop license to set it up again somewhere new."

At the bottom a card points to the license ("Craft a Shop Business License at the carpentry bench ...") or, at your limit, "Shop limit reached".

---

## Shop window

A shop for its customers. The header shows the shop's icon and name, "by [owner]" or "Server shop", the category, the rental time left for shops on a rented stand, the description in quotes, the rating diamonds with "4.6 · 23 ratings", and your wallet. **< Market** opens the market; **X** closes the window.

Tabs: **Buy** (offers for sale), **Sell** (offers the shop buys) and **Reviews** (hidden when ratings are off), each with a count. A search field filters the item cards by item ID, with underscores read as spaces ("iron sword" finds `Weapon_Sword_Iron`).

### Buy tab

![Shop window, Buy tab](../../../../assets/player-shops/shops-shop-buy.png)
*Buying: item cards on the left, the picked item with price, stock, quantity and total on the right.*

- **Cards** (5 per row, in the owner's slot order, what you can buy first): icon, name, price and stock ("Stock 12", "Unlimited", "Sold out"). The tooltip repeats price and stock. Sold-out cards are dimmed and cannot be picked.
- **Detail**: rarity and category, **Price** per piece, **Stock**, and **Buys back for** when the shop also buys the item ("The shop also buys this item back - see the Sell tab.").
- **Quantity** with **-**, **+** and **Max**: at most the stock and one stack (64); Max also respects your wallet.
- **Total**, a **Tax** line when a buy tax is on, **Balance after**.
- **Buy for [total]**, or a disabled button: "This is your own shop", "The shop is closed", "Economy offline", "Sold out", "Not enough money".
- The footer says where the items go (mailbox, or inventory with the rest mailed). The status line confirms "Bought 3x Bread - it is in your mailbox." (or inventory, or split).

### Sell tab

![Shop window, Sell tab](../../../../assets/player-shops/shops-shop-sell.png)
*Selling to a shop: every limit is listed and the one that decides the maximum is highlighted.*

- **Cards** show what the shop pays and "You have N" or "Not in inventory". Items you do not carry are dimmed and cannot be picked.
- **Detail**: **Pays** per piece and four limits:
  - **You have**: matching items in your hotbar and storage. Only undamaged items with exactly the offer's enchantments and metadata count.
  - **Room in the shop**: how many more it takes before reaching the owner's "stop buying at stock" value.
  - **Buy limit left**: the offer's remaining buyback quota.
  - **Till covers**: how many pieces the shop's till can pay for ("no limit" for server shops, which the server pays).
- The limit that decides the maximum is shown in amber with a note ("Limited by Till covers: 4 of your 20."). An empty till says "The shop's till is empty - it cannot buy right now."
- **Quantity** (at most 64), **Proceeds**, a **Tax** line when a sell tax is on, **Balance after**.
- **Sell for [proceeds]**. The money goes straight to your wallet.

When the quota is used up, the shop stops buying that item until the owner switches buyback on again.

### Reviews tab

![Shop window, Reviews tab](../../../../assets/player-shops/shops-shop-reviews.png)
*Reviews: the average and its distribution, your own rating form and the list of reviews.*

- **Summary**: average, "23 ratings · 9 with text" and a bar per diamond count.
- **Your rating**: pick 1 to 5 diamonds (Poor, Fair, Good, Very good, Excellent) and an optional comment (up to `ratings.commentMaxLength` characters, hidden when comments are off). **Submit rating**, or **Update rating** when you rated before.
- You cannot rate your own shop, and after rating you can change it again after `ratings.cooldownMinutes` ("You can change it again in 42 min.").
- **Reviews**: newest first, with name, diamonds, age and comment. Your own review is marked "You" and highlighted.

One rating per player and shop. The shop's average and count update at once.

---

## Shop editor

The owner's window ("Manage shop"). It opens for the owner of a player shop and, through `/kssa editadmin` or the admin window, for server shops. Only one person can edit a shop at a time; others get "This shop is currently being edited by another session."

- **Header**: shop name, "Manage shop · [category] · Location x, y, z", the **Open / Closed** switch ("applies at once") and your wallet.
- **Left**: the shop grid "In the shop" (9 x 5 = 45 slots, "12 / 45" with your offer limit), and your inventory and hotbar below it.
- **Right**: the tabs **Offer**, **Shop**, **Till** and **History**.
- **Footer**: "Everything saved" or the number of unsaved changes, **Discard** and **Save**.

**What applies when:**

- **At once:** moving items (stock), open / closed, merchant look, name tag, market listing, till deposit and withdraw, pack-up.
- **On Save:** prices and limits of the offers, name, description, category and market icon. Invalid entries are marked red and are not saved ("Saved - 2 offers still have entries marked red."). Closing the window discards unsaved changes with a chat note.

If the shop is packed up, deleted or its rental ends while the editor is open, the editor closes with "This shop was packed up or closed down meanwhile".

### Moving items

| Action | Result |
|--------|--------|
| Drag a stack from your inventory onto the shop grid | Adds it to the shop. Right-drag moves part of a stack |
| Click a stack in your inventory | Moves the whole stack into the shop |
| Drag an offer from the shop grid into your inventory | Takes up to one stack out |
| Drag an offer onto another shop slot | Moves it there (swaps with the offer in that slot) |
| Click an offer in the shop grid | Selects it on the Offer tab |

- One offer per item ID: adding more of an item joins its offer. A stack with other enchantments or metadata than the existing offer is refused ("Another version of this item is already in the shop.").
- Refused: damaged items ("Damaged items cannot be sold - repair it first."), blacklisted items, unknown items, a full grid, more different items than your offer limit. Inventory stacks the shop would refuse are dimmed.
- A new offer starts with a price of 10 (moved into the server's price range) and is **not live** until you save its price. Its slot tooltip says "Not live yet - set a price and save".
- An offer without stock that the shop does not buy back disappears when you take the last items out.
- Offers with unlimited stock (server shop templates) cannot be taken out.
- Items dragged into a server shop have the dragged amount as stock; only templates give unlimited stock.

### Offer tab

![Shop editor, Offer tab](../../../../assets/player-shops/shops-editor-offer.png)
*The Offer tab: sale and buyback for the selected offer, its limits and the customer preview.*

For the selected offer ("12 in the shop · slot 4"):

- **Sell to customers**: switch and price per piece.
- **Buy from customers**: switch and the price the shop pays ("you pay from the shop till"). Switching it on without a price suggests half the sale price.
  - **Stop buying at stock**: the shop stops buying when its stock reaches this number. Empty = no limit.
  - **Buy at most in total**: a buyback quota; every sale to the shop lowers it, at 0 the shop stops buying the item. Empty = no limit.
- **What customers see**: a preview line ("Buy for 25 Gold · Stock 12 · Buys for 10 Gold").
- The allowed price range ("Prices from 1 to 1,000,000 Gold.").
- **Take out of the shop** (one stack back to your inventory) or **Remove offer** when no stock is left.

### Shop tab

![Shop editor, Shop tab](../../../../assets/player-shops/shops-editor-shop.png)
*The Shop tab: name, description, category, market icon, merchant look, name tag, listing and pack-up.*

| Setting | What it does |
|---------|--------------|
| **Name** | `nameMinLength` to `nameMaxLength` characters, unique. The name plate follows after Save |
| **Description** | Up to `descriptionMaxLength` characters, shown in the shop window header |
| **Category** | One of the eight categories; also used by the market filters |
| **Icon in the market** | Up to 20 picks: the current one, the shop's own items, then a fixed set of common items. Clicking the chosen icon again switches back to "automatic (first offer)" |
| **Merchant** | A player name whose skin the merchant wears, then **Apply** (applies at once, the merchant reappears). Empty = default look (the owner's skin for player shops) |
| **Name tag above the merchant** | Shows or hides the name plate |
| **Market listing** | Status ("listed · 5 d 3 h left", "listed permanently", "not listed", "rental stand"), days **-** / **+** and **Extend · [cost]** ("Extend · free" with `ks.shop.list.free`). Hidden when listings are switched off and for server shops |
| **Pack up the shop** | Player shops only, not shops on rental stands. See below |

**Packing up** asks for confirmation and lists what happens (while the question is open, a click next to it does nothing): the offers and items go to your mailbox, the till as well, the merchant disappears and the shop leaves the market, and you get a shop license back. The listing's end date does not move, so listing days keep running out while the shop is packed. Open changes are saved first (all entries must be valid). The license you get back is bound to this shop: using it offers to set this shop up again. Name, rating, settings and history stay.

### Till tab

![Shop editor, Till tab](../../../../assets/player-shops/shops-editor-till.png)
*The Till tab: the shop's buyback money and the shop's figures.*

- **Shop till**: the gold that pays for buybacks. "When it is empty, your shop stops buying."
- **Amount** with **Deposit** (from your wallet) and **Withdraw** (only when `playerShops.allowBuybackWithdraw` is on).
- Figures: Revenue total, Today, Last 7 days, Sales total, Buybacks (7 days), Rating. They are read from the last 2,000 transactions of the shop ("2000+" when more exist).

Sale earnings do not go into the till; they go to your mailbox.

### History tab

The newest 50 transactions of the shop with filters **All**, **Sales** (customers bought) and **Buybacks** (customers sold to the shop): who, what, amount and age.

---

## Mailbox

Every purchase that is not delivered to the inventory, every sale earning, and everything returned from packed-up shops, ended rentals and deleted shops waits here. Every Mailbox block on the server shows the same mailbox.

- **At a Mailbox block** (**F**, the door opens): "Purchases, earnings and returned stock". You can claim.
- **By command** (`/ksshop notifications`): "View only · claim at a mailbox". The claim buttons are disabled.

### Claim tab

![Mailbox, Claim tab](../../../../assets/player-shops/shops-mailbox.png)
*The Claim tab: what waits, one row per mail, Claim all or one at a time.*

- Summary: "2 packages · 3 payments worth 1,940 Gold" and your free inventory slots.
- One row per mail: items or gold, where it comes from ("Bought at Mirabel's Forge", "Steve bought at Food Corner", "Earnings from Food Corner · 7 sales", "Stock of Food Corner (packed up)", "Funds of Plaza (rental ended)", "Rental refund · Plaza") and its age.
- A warning on rows that do not fit: "No room in inventory" or "Only 20 of 64 fit".
- **Claim** per row and **Claim all**. Gold goes to your wallet; items go into your inventory as far as they fit, the rest stays in the mailbox. Nothing is dropped on the ground.

Mails from a delete (your own, an admin's or unpaid rent) and items returned after a failed purchase show as "Bought at [shop]".

### Sales tab

![Mailbox, Sales tab](../../../../assets/player-shops/shops-mailbox-sales.png)
*The Sales tab: sales made while you were offline.*

Lists the sales of your shops that happened **while you were offline** (one line per sale: buyer, items, shop, time, amount), newest first, up to 50. The header shows the new ones since your last visit and their total; **Mark all read** clears the badge. The earnings themselves are on the Claim tab. Notices of the legacy rent system ("A shop was closed: the rent could not be paid.") appear here too.

Hidden when `notifications.enabled` is `false`.

---

## License dialog

![License dialog for a new shop](../../../../assets/player-shops/shops-license.png)
*Using the Shop Business License: open a new shop or set up a packed one, with costs and listing info.*

Right-click with the **Shop Business License** (needs `ks.shop.user.create`). The license is only used up when the shop is placed.

**Options** at the top:

- **Open a new shop**: "500 Gold · shop 2 of 3", or "Limit reached · 3 of 3 shops".
- One entry per packed shop: **Set up "[name]" here** ("free · name, rating and settings stay"). A license that is bound to a packed shop selects that shop first; at your shop limit the dialog starts on your first packed shop.

**New shop:**

- **Name** (default "[your name]'s Shop", shortened to fit and numbered when taken), with a counter and "At least 3 characters." / "At most 24 characters." / "Another shop already has this name.".
- **Category** (eight choices) and **Description** (optional).
- Facts: **Cost**, **Balance after** (or how much is missing), **Your shops** ("1 of 3 → 2 of 3"), **Market listing** ("always listed", "7 days free (first shop)" or "bookable later · 100 Gold per day").
- **Open · 500 Gold** (or **Open shop** when free). Disabled with "Limit reached", "Check name" or "Not enough money".

**Packed shop:** Cost none, Stays: name, rating, settings, Stock: in your mailbox, and the listing state ("listed · 3 d left" or "paused - renew in the shop menu"). **Set up here**.

The merchant appears at your position, facing your direction. Chat confirms: "[name] is open! Talk to your trader with F to stock items and set prices." For a packed shop the stock is still in your mailbox; fetch it and restock with **F**.

---

## Language

The language choice is shared by all KyuubiSoft mods. `/kslang` alone answers in chat with your current language, the available codes and how to change it; `/kslang de-DE` sets a language, `/kslang auto` goes back to your client language. The shop windows and chat messages follow it; see [Configuration](./configuration#localization).