# Player Shops

**KyuubiSoft Shops lets players run their own shops on a Hytale server. Every shop is a merchant NPC standing in the world. Customers buy from it and sell to it, owners stock it by drag and drop, and a marketplace window lists every shop and every offer on the server. Admins add server shops and rental stands that players rent at a fixed price or win at an auction.**

:::caution[Not tested in game yet]
Version 2.0.0 rebuilt every window. It was built and boot-tested on Hytale 0.7.0, but the new windows have not been tested in game yet.
:::

---

## How a shop works

- **Opening a shop.** A player uses a **Shop Business License** (crafted at the Carpentrybench) where the shop should stand. A dialog asks for name, category and description; the merchant then appears at the player's position, facing the player's direction. The license is only used up when the shop is placed. Opening costs `playerShops.creationCost` gold (500 by default).
- **Stocking it.** Talking to your own merchant with **F** opens the shop editor. You drag stacks from your inventory into the 45-slot shop grid. Stock moves apply at once; prices and shop settings are drafts until you press **Save**.
- **Selling and buying back.** Each offer can sell to customers, buy from customers ("buyback"), or both. Buybacks are paid from the shop's **till**, which the owner fills with gold.
- **Getting paid.** Customers' purchases and the owner's earnings go to the **mailbox** (by default; purchases can also go straight into the inventory, see [Configuration](./configuration)). Players craft and place a Mailbox block and press **F** on it to claim. Every mailbox block shows the same mailbox.
- **Being found.** Server shops are always in the marketplace. A player shop shows there while its **market listing** runs: the first shop a player ever opens gets 7 free days, after that the owner pays `listingPricePerDay` per day. Unlisted shops can still be visited on site.
- **Packing up.** An owner can pack a shop up: stock and till go to the mailbox, the merchant disappears and the owner gets a license back that sets the same shop up again somewhere else (name, rating and settings stay).

---

## Features

### Marketplace

`/ksshop browse` opens the **Market** window with four tabs: **Shops** (shop cards with rating, owner, distance and category, filters and sorting), **Offers** (every item for sale on the server in one list, with direct buying), **Rental stands** (rent or bid, live countdown) and **My shops** (your shops, rentals and earnings). See [UI Pages](./ui-pages).

### Shop window

Customers get a window with **Buy**, **Sell** and **Reviews** tabs. The quantity is limited by stock, wallet and one stack (64); when selling, by what you carry, the room left in the shop, its buyback quota and its till. The limit that applies is highlighted. Reviews take 1 to 5 diamonds and an optional comment.

### Shop editor

Drag and drop between your inventory and the shop grid, tabs **Offer**, **Shop**, **Till** and **History**, merchant look by player name, name tag, market listing and pack-up.

### Rental stands

Admins place stands at fixed spots. A free stand is a merchant whose name plate shows the price (`[100g/day]`) or the current bid (`[AUCTION 500g]`). Players rent it for a number of days or win it at a timed auction with anti-sniping. When the rental ends, stock and till go to the renter's mailbox and the stand is free again. See [Rental Stands](./rentals).

### Server shops

Admin shops without an owner: created in game with `/kssa createadmin` or from JSON templates in `admin-shops/`. Template offers can have unlimited stock; customer money for server shops leaves the economy.

### Admin window

`/kssa admin` opens **Shop Admin** with eight sections: settings for General, Economy and taxes, Rental stands; management of All shops, Rental stands, Transactions; tools Statistics and Blacklist. See [Admin Panel](./admin-panel).

### Safety

Purchases, buybacks, editor moves and saves work under one lock per shop, so stock and the till cannot be spent twice. A failed mailbox or economy step gives back what it took. Damaged items and items with other enchantments or metadata than the offer cannot be sold to a shop.

---

## Windows

| Window | How to open it |
|--------|----------------|
| **Market** | `/ksshop browse` (Shops tab), `/ksshop myshops` or `/ksshop myrentals` (My shops), `/ksshop rentalstations` (Rental stands), **F** on a free rental stand |
| **Shop window** | **F** on someone else's merchant, `/ksshop visit <shop>`, a shop card in the market |
| **Shop editor** | **F** on your own merchant, `/ksshop edit`, **Manage** in the market's My shops tab |
| **Mailbox** | **F** on a Mailbox block (claim), `/ksshop notifications` (view only) |
| **License dialog** | Right-click with the Shop Business License |
| **Shop Admin** | `/kssa admin`, or its tile in KyuubiSoft Core's `/ksadmin` hub |
| **Language** | `/kslang` (shared by all KyuubiSoft mods) |

The windows use the KyuubiSoft "Goldfiligran" look. Its textures come from the shared KyuubiSoft UI kit inside the jar; the kit is registered once per server and the newest kit version wins, so nothing extra has to be installed.

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing, the files the plugin creates, a first shop, upgrading from 1.x |
| [Commands](./commands) | Every `/ksshop` and `/kssa` command |
| [Permissions](./permissions) | Permission nodes, limits and listing perks |
| [Configuration](./configuration) | Every field of `config.json`, server shop templates, languages |
| [UI Pages](./ui-pages) | Market, shop window, editor, mailbox and license dialog |
| [Rental Stands](./rentals) | Fixed-price rentals and auctions in detail |
| [Admin Panel](./admin-panel) | The Shop Admin window |
| [API Reference](./api-reference) | Events, services and database tables for other plugins |
| [FAQ](./faq) | Common questions and problems |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Plugin** | KyuubiSoft Shops (manifest `kyuubisoft:shops`) |
| **Version** | 2.0.6 (2026-11-09) |
| **Jar** | `KyuubiSoftShops-2.0.6.jar` |
| **Player command** | `/ksshop` (aliases `/shop`, `/market`) |
| **Admin command** | `/ksshopadmin` (alias `/kssa`), permission `ks.shop.admin` |
| **Language command** | `/kslang` (registered by the first KyuubiSoft mod that loads) |
| **Data folder** | `mods/kyuubisoft_shops/` |
| **Config** | `mods/kyuubisoft_shops/config.json` |
| **Server shop templates** | `mods/kyuubisoft_shops/admin-shops/*.json` |
| **Database** | `mods/kyuubisoft_shops/shops.db` (SQLite) or MySQL |
| **Localization** | `mods/kyuubisoft_shops/localization/<lang>.json` (9 languages, version 30) |
| **Items** | Shop Business License (`Shop_NPC_Token`), Mailbox (`Mailbox_Block`) |
| **Economy** | KyuubiSoft Core's economy bridge, or VaultUnlocked with a provider such as Ecotale |
| **Optional** | KyuubiSoft Core, KyuubiSoft Claims, VaultUnlocked |

---

## Requirements

- Hytale server 0.7.x (built against 0.7.0)
- Java 25
- An economy for anything that costs or pays gold: either **KyuubiSoft Core** (its economy bridge is used first) or **VaultUnlocked** (`TheNewEconomy:VaultUnlocked`) with a provider registered there. Without one, the plugin loads, but buying, selling, renting and opening shops are refused. [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/), the server currency of KyuubiSoft Core 2.10.0 (not released yet), counts as such an economy through Core. From Shops 2.0.7 (not released yet) a late economy is found by the next shop action, and the currency's name is shown in each player's language instead of "Gold".
- SQLite and the MySQL driver are inside the jar.

The Player Shops plugin is separate from the NPC shops of KyuubiSoft Core (the [Shop System](https://wiki.kyuubisoft.com/hytale/shop-system/)): it has its own database, commands and windows. This plugin owns `/ksshop`. Core's NPC shops have their own command `/ksnpcshop open|sell|list` since Core 2.9.0; Core also registers `/ksshop`, but on servers with this plugin the player shop command replaces it.