# Admin Panel

**Version:** 2.0.6 · **Permission:** `ks.shop.admin`

All admin tools of the shop system live in one window, **Shop Admin**, in the KyuubiSoft Goldfiligran look. Its texts follow the admin's language (all 9 bundled languages).

:::note
The pictures on this page are design previews of the in-game window. Names and values are examples.
:::

## Opening the window

| Command | Opens on |
|---------|----------|
| `/kssa admin` | All shops |
| `/kssa log <player>` | Transactions, searching for that player |
| **Shop Admin** tile in KyuubiSoft Core's `/ksadmin` hub (Core 2.8.0 or newer) | All shops. The hub itself needs Core's `ks.admin`; the tile still needs `ks.shop.admin` and otherwise answers with a "no permission" message |

The window is for players only. Every click checks `ks.shop.admin` again; without it the status line says "You lack the permission ks.shop.admin." and nothing changes.

### Showcase servers

On a server that runs KyuubiSoft Core's showcase mode, the showcase key also opens this window. A visitor who is not a real admin can open it, switch sections, search and look at everything. Saving, **Reload**, adding to the blacklist, opening, closing, featuring, deleting or editing a shop and every change to a rental stand answer that the server is read-only. The **Transactions** section shows "Player data is hidden". When the showcase switches its `allowShopTrade` option off, buying and selling answer "This shop is closed." for its visitors. A normal server is not affected.

## Layout

- **Header:** "Shop Admin", a subtitle like "12 shops · 4 rental stands · Economy: Gold" ("none found" without an economy), the status line for the result of your last action (green or red), **Reload** and the close button.
- **Navigation (left)** with a count next to most entries:
  - **Settings:** General, Economy & taxes, Rental stands
  - **Management:** All shops, Rental stands, Transactions
  - **Tools:** Statistics, Blacklist
- **Reload** does the same as `/kssa reload`: config, languages and the market index are read again. Typed but unsaved settings are reset.

Numbers accept your language's separators: `1.000`, `1,000` and `1000` are the same; decimals take a dot or a comma.

---

## Settings

Three forms: **General**, **Economy and taxes**, **Rental stands**. Every row has a label, a hint and a field with its unit, or an On/Off switch. Switches and fields are only staged; **Save** at the bottom writes all of them to `config.json` ("Saved to config.json and active right away."). Invalid input is refused with the field name ("Shops per player: allowed is 1 to 100.", "... is not a number.", "Name at least must not be above Name at most.") and nothing of that form is saved.

### General

| Section | Row | Config field |
|---------|-----|--------------|
| Player shops | Allow player shops | `features.playerShops` |
| | Shops per player (1-100) | `playerShops.maxShopsPerPlayer` |
| | Opening cost | `playerShops.creationCost` |
| | Name at least / Name at most (1-64 characters) | `playerShops.nameMinLength` / `nameMaxLength` |
| | Description at most (0-500 characters) | `playerShops.descriptionMaxLength` |
| | Owners may withdraw the buyback till | `playerShops.allowBuybackWithdraw` |
| Market | Market active | `features.directory` |
| | Market listing costs gold | `playerShops.listingEnabled` |
| | Listing per day | `playerShops.listingPricePerDay` |
| | Listing at least / at most (1-365 days) | `playerShops.listingMinDays` / `listingMaxDays` |
| | Free days for the first shop (0-365) | `playerShops.listingFreeDaysOnCreate` |
| Ratings | Ratings | `features.ratings` and `ratings.enabled` together |
| | Comments with ratings | `ratings.allowComments` |
| | Comment at most (0-500 characters) | `ratings.commentMaxLength` |
| | Wait between ratings (minutes) | `ratings.cooldownMinutes` |

### Economy and taxes

| Section | Row | Config field |
|---------|-----|--------------|
| Economy | Currency | shows the detected economy ("Gold (connected)" or "No economy found - nothing can be bought") |
| Prices | Minimum price / Maximum price (per item) | `economy.minPrice` / `maxPrice` |
| Taxes | Collect taxes | `tax.enabled` |
| | Tax on purchases (0-100 %, paid by the buyer on top) | `tax.buyTaxPercent` |
| | Tax on sales to shops (0-100 %, taken from the proceeds) | `tax.sellTaxPercent` |
| Delivery | Purchases straight into the inventory | `mailbox.deliverPurchasesToInventory` |
| | Collect sale earnings in one mail | `mailbox.combineSaleEarnings` |

### Rental stands (settings)

| Section | Row | Config field |
|---------|-----|--------------|
| Rental stands | Rental stands active (takes effect after a restart) | `rentalStations.enabled` |
| | Rented shops are listed for free | `rentalStations.rentalShopsListFree` |
| Defaults for new stands | Price per day | `defaultPricePerDay` |
| | Maximum duration (also the auction winner's days) | `defaultMaxDays` |
| | Minimum bid / Bid step | `defaultMinBid` / `defaultBidIncrement` |
| | Auction duration (1-10080 min) | `defaultAuctionDurationMinutes` |
| Rules | Stands per player | `maxConcurrentRentalsDefault` |
| | A late bid extends by (seconds, 0 = off) | `auctionAntiSnipingSeconds` |
| | "Ending soon" notice (seconds, 0 = off) | `auctionEndingSoonSeconds` |
| | Extend at most (days per extension) | `extendMaxDays` |
| | Refund on early release (percent of the paid days left, fixed price only) | `releaseEarlyGoldRefundFraction` (stored as 0.0-1.0) |
| | Auction without bids: Restart / Let rest / Delete | `onEmptyAuction` |

Switching rental stands on or off saves with "Saved. Switching rental stands on or off takes effect after a restart."

Fields that are not in the window (claims, NPC looks, legacy rent, featured automation, database and others) are described on [Configuration](./configuration).

---

## All shops

![Admin window, All shops](../../../../assets/player-shops/shops-admin-shops.png)
*All shops: the searchable list on the left, the picked shop's facts, status switches and actions on the right.*

**List:**

- Search by name, owner or ID; every word must match ("thar iron" finds Tharok's iron shop).
- Filters **All**, **Player**, **Server**, **Rental** and "12 shops" / "3 of 12 shops".
- 9 rows per page, sorted by name: icon, name, "[owner] · [type] · N offers" and an Open / Closed chip.
- Free rental stands are not listed here ("Free rental stands are under 'Rental stands'.").

**Detail** of the picked shop:

- Icon, name, type chip, Open / Closed chip, "ID 1a2b3c4d · World default" (the first 8 characters of the UUID).
- Facts: Owner, Offers, Total revenue, Shop till, Rating, Opened (date), In the market ("permanently", "until [date]", "not listed"), Location.
- **Status** (applies at once):
  - **Open**: closing keeps the merchant standing, its name plate says `[CLOSED]`.
  - **Featured**: on = at the top of the market for `featured.durationDays` days ("At the top of the market until [date]"), off ends it.
- **Actions:**
  - **Teleport** to the shop. Into another world the window closes.
  - **Edit offers**: server shops only; opens the shop editor (the admin window closes). Refused while someone else edits the shop.
  - **Delete** with a confirmation in the window:
    - server shop: "The server shop and its trader disappear." A template shop deleted in game stays deleted until its file changes. A placeholder shop that an earlier version left behind when a stand was deleted with `onEmptyAuction: DELETE` is listed as a server shop and can be deleted the same way.
    - player shop: "Stock and till go to [owner]'s mailbox."
    - shop on a rented stand: "The rental ends; stock and till go to [owner]'s mailbox." The stand stays and is free again.
    - Refused while the shop's editor is open ("[shop] is being edited right now.").

---

## Rental stands

![Admin window, Rental stands](../../../../assets/player-shops/shops-admin-rentals.png)
*Rental stands: every stand with its state, the stand editor with mode, prices and actions.*

**List:**

- Filters **All**, **Free** (free fixed-price stands and resting auctions), **Auction** (all auction stands), **Rented**, and "4 stands" / "2 of 4 stands".
- 9 rows per page, sorted by name: a state dot, name, a state line ("Free · 100 Gold per day", "Bid 650 Gold · 1 h 20 min left", "Auction resting", "Steve · 3 d 4 h left") and the mode.
- **+ New stand here** creates a fixed-price stand "New stand N" at your position with the config defaults; its merchant appears at once.

**Stand editor** of the picked stand:

- **Name** (1-40 characters), "World default · 120, 64, -38", and the state: "Free - 100 Gold per day", "Auction running - high bid 650 Gold by Steve - ends in 1 h 20 min", "Auction running - no bid yet (minimum 500 Gold) - ends in ...", "Auction resting - nobody bid. Restart it so bidding works again.", "Rented to Steve - 3 d 4 h left".
- **Mode:** Fixed price / Auction. The mode can only change while nobody rents the stand ("The mode can only change while the stand is free.") and no bid is open ("The auction has bids - the mode cannot change now."). Fixed to Auction starts the first round at once; Auction to Fixed ends the current round and clears its bid history.
- Fields for fixed price: **Price per day**, **Maximum duration** ("In one go, extending is possible"). For auction: **Minimum bid**, **Bid step**, **Rental days for the winner**, **Auction duration** (minutes).
- **Save** applies name and values; the free stand's name plate follows at once. A running rental keeps its end date; a new price per day applies to its next extension.
- **Restart auction** (only on a resting auction) starts a new round.
- **End rental** (only while rented), with a confirmation: stock and till go to the renter's mailbox, the renter is told, the stand is free again.
- **Teleport** to the stand.
- **Delete** with a confirmation; a running rental is ended first. The stand and its merchant are removed.

Details on renting and auctions: [Rental Stands](./rentals).

---

## Transactions

The newest 500 purchases and sales of all shops, loaded in the background when you open the section (opening it again after more than 30 seconds loads them again). Columns: Time, Customer, Shop, Item, Qty, Price, Tax. Sales to a shop (buybacks) are marked "Sold". 12 rows per page.

The search field takes player, shop or item; every word must match and parts of names are enough. `/kssa log <player>` opens the window here with the name already in the search.

---

## Statistics

Live figures, refreshed when you open the section or press **Refresh**:

| Tile | Shows |
|------|-------|
| Shops | All shops, split into player, server and rental |
| Total revenue | Sum of all shops' revenue since the start |
| Transactions today | Count today, yesterday's count below |
| Rented stands | Rented of all stands, free stands below |
| Taxes | Collected in total ("Taxes are off" when taxes are switched off) |
| Open mailboxes | Mails not collected yet |
| Best shop | The shop with the highest revenue |
| Best seller | The item sold most in the last 30 days and its quantity |
| Active auctions | Running auctions, the one with the highest bid below |

---

## Blacklist

Items on the blacklist cannot be put into a shop in the editor. Offers that already exist stay until their owner takes them out.

- Type an item ID (for example `Weapon_Sword_Mithril`) and press **Add**. Unknown IDs are refused ("... does not exist in the game."), duplicates too.
- 10 rows per page with icon, item name and ID; **Remove** allows an item again.
- Changes are saved to `itemBlacklist` in `config.json` at once. `/kssa blacklist add|remove|list` does the same in chat.

---

## Common workflows

### Close a shop that breaks the rules

1. `/kssa admin` → **All shops**, search the shop.
2. Switch **Open** off. The merchant stays, customers can no longer trade.
3. Or **Delete** it: the owner gets stock and till in the mailbox.

### Feature a shop for a week

**All shops** → pick the shop → switch **Featured** on (length: `featured.durationDays`). Or `/kssa feature <shopId>`.

### Run an auction on a free stand

**Rental stands** → pick the stand → Mode **Auction** → set minimum bid, step, rental days and duration → **Save**. The first round starts at once.

### Check a player's trades

`/kssa log <player>`, or **Transactions** and type the name.

### Stuck or missing merchants

`/kssa respawnnpcs` in the affected world despawns and respawns the merchants of every shop there (player shops, rented and free stands, server shops; packed shops are skipped) and removes leftover copies.