# Getting Started

**Version:** 2.0.6

## Installation

1. Stop the server.
2. Put `KyuubiSoftShops-2.0.6.jar` into the server's `mods/` folder. When you update, remove the old `KyuubiSoftShops-*.jar` first.
3. Make sure an economy is available (see below).
4. Start the server. The plugin creates its data folder `mods/kyuubisoft_shops/` and fills it with the default files.

### Economy

Everything that costs or pays gold needs an economy. The plugin looks for one in this order:

1. **KyuubiSoft Core**: its external economy bridge.
2. **VaultUnlocked** (`TheNewEconomy:VaultUnlocked`) with a provider registered there, for example Ecotale.

Providers that register with VaultUnlocked after Shops has loaded are picked up by four more checks at 2, 5, 10 and 20 seconds after the start. Without an economy the plugin still runs, but purchases, sales, rentals, paid listings and opening shops are refused with an "economy offline" message.

The currency name in the windows comes from the economy (fallback "Gold").

:::note[From 2.0.7 (not released yet)]
- **Economy found later.** When the economy starts after these checks, the next shop action finds it (at most one check every 5 seconds; the log says `Economy provider attached when a shop needed it`). Trading no longer stays off until the next restart.
- **Economy gone.** When the economy behind KyuubiSoft Core is switched off while the server runs, shops say the economy is unavailable instead of failing the payment.
- **Your currency's name.** Prices, balances and shop messages show the economy's own name. With [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/), the server currency of KyuubiSoft Core 2.10.0, it appears in each player's language with the right form ("1 Crown", "5 Crowns"). When the economy has no name, `economy.currencyName` from `config.json` is used ("Gold" by default), so these servers see no change.
- **Reasons.** With Kronen every shop payment names its reason in the Kronen history, for example "Bought at Mira's Forge", "Player shop founded · …" or "Directory listing for 3 days · …".
:::

### Optional plugins

| Plugin | What Shops uses it for |
|--------|------------------------|
| KyuubiSoft Core | Economy bridge (preferred), merging new default fields into `config.json`, the showcase-mode write guard |
| KyuubiSoft Claims | Claim check when `playerShops.requireClaim` is on (see [Configuration](./configuration#playershops)) |
| VaultUnlocked | Economy when Core is not installed |

---

## Files after the first start

```
mods/
  KyuubiSoftShops-2.0.6.jar
  kyuubisoft_shops/
    config.json                  main configuration
    shops.db                     SQLite database (shops, offers, mailbox, ratings, rentals ...)
    localization/                en-US, de-DE, fr-FR, es-ES, pt-BR, ru-RU, pl-PL, tr-TR, it-IT (.json)
    admin-shops/
      example_blacksmith.json    example server shop template ("enabled": false)
      .applied.json              which template versions were applied (do not edit)
    npc-roles/
      Shop_Keeper_Role.json      merchant NPC role (rewritten on every start)
    skin-cache.json              cached merchant skins (created when the first skin is fetched)
    .legacy_balances_migrated    markers of one-time migrations (do not delete)
    .shops_npc_migration_done
    .shops_npc_role_v2_done
  kslang/                        language choice shared by all KyuubiSoft mods
```

With `database.type` set to `mysql` the tables live in your MySQL database instead of `shops.db`.

### Boot log

A healthy start prints lines like these:

```
[KyuubiSoft Shops] Setting up KS-Shops...
[KyuubiSoft Shops] Config loaded: playerShops=true, adminShops=true, tax=false, rent=false, categories=8
[KyuubiSoft Shops] [Shops] Loaded 9 language(s)
[KyuubiSoft Shops] Database initialized (sqlite)
[KyuubiSoft Shops] Economy via VaultUnlocked direct (Ecotale)
[KyuubiSoft Shops] Loaded 12 shops (3 admin, 9 player)
[KyuubiSoft Shops] Loaded 4 rental slot(s)
[KyuubiSoft Shops] KS-Shops ready. 12 shops loaded.
```

`No economy provider detected (yet) - shop transactions disabled` is normal when the provider registers late; `Economy provider attached on retry` follows within 20 seconds. If it never follows, check the provider's own log.

---

## Your first shop (as a player)

1. **Craft a Mailbox** at the Carpentrybench (4 Oak Planks + 1 Iron Bar) and place it. Everything you buy and earn arrives there.
2. **Craft a Shop Business License** at the Carpentrybench (8 Oak Planks + 2 Iron Bars + 2 Gold Bars + 1 Medium Leather). It stacks to 1 and is not dropped on death.
3. **Stand where the shop should be** and right-click with the license. The license dialog opens: pick a name (the default is "[your name]'s Shop"), a category and an optional description, check the cost and press **Open**. Your merchant appears at your position and faces your direction; the license is used up.
4. **Press F on your merchant.** The shop editor opens. Drag stacks from your inventory into the shop grid (or click a stack to move it in). Each new offer starts with a price of 10 and is not for sale yet.
5. **Set prices** on the **Offer** tab: "Sell to customers" with a price per piece, and if you want, "Buy from customers" with a buyback price. Press **Save**. The offer is now live.
6. **Fill the till** on the **Till** tab if your shop buys items back: buybacks are paid from it.
7. **Get listed.** Your first shop ever gets 7 free days in the market. Later shops are listed on the **Shop** tab under "Market listing" (100 gold per day by default) or with `/ksshop list <days>`.
8. **Collect** at your mailbox: sale earnings arrive there as money mails.

`/ksshop help` prints a short version of these steps in game.

:::tip
`/ksshop create <name>` also opens a shop at your position, without a license (same cost, limits and name rules, no category or description). Both use the permission `ks.shop.user.create`, so the command cannot be switched off on its own.
:::

---

## A first test (as an admin)

```
/kssa createadmin Test Market
   -> a server shop with its merchant at your position
/kssa editadmin
   -> the shop editor for the nearest server shop: drag bread in, set a price, Save
F on the merchant with a second account
   -> the shop window opens on Buy; buy one bread
   -> chat: "1x Bread sent to your mailbox."
F on a placed Mailbox block with that account
   -> claim the bread
```

A first rental stand:

```
/kssa createrental Plaza 100 7
   -> fixed-price stand "Plaza", 100 gold per day, at most 7 days
   -> its merchant's name plate reads "Plaza [100g/day]"
F on that merchant with a player account
   -> the market opens on Rental stands with Plaza selected
```

Or use the admin window: `/kssa admin`, section **Rental stands**, **+ New stand here**. See [Rental Stands](./rentals).

---

## Permissions in short

All player nodes (`ks.shop.user.*`, `ks.rental.rent`, `ks.rental.bid`) are checked as "allowed unless set", so players can use the shops out of the box. Give `ks.shop.admin` to staff:

```
/lp user <name> permission set ks.shop.admin true
```

If your permission plugin answers "no" for nodes that are not set, grant the player nodes explicitly. Details and rank examples are on [Permissions](./permissions).

---

## Upgrading from 1.x

- **New windows.** All old windows (shop browser, directory, rating page, old editor, notifications page, the four rental pages, old admin page) were replaced by the market, the shop window, the editor, the mailbox and the Shop Admin window. Commands that opened them now open the new windows (for example `/ksshop myrentals` opens the market on My shops).
- **Languages.** Localization version 32 (30 in 2.0.0, 31 in 2.0.2). Files in `localization/` with an older version (also those of 2.0.0 to 2.0.2) are saved as `<lang>.json.backup-v<old>` and replaced by the new defaults. Copy your own changes back by hand.
- **Server shop templates.** Templates are now applied once per file version (see [Configuration](./configuration#server-shop-templates)). On the first 2.0.0 start no version is recorded yet, so every enabled template rewrites its shop from the file once. The example blacksmith only ships disabled on new servers; an existing `example_blacksmith.json` without `"enabled"` stays active. Set `"enabled": false` (or delete the file) and delete the shop in game to get rid of it.
- **Data.** The database is migrated automatically. Shop balances from versions before the mailbox are moved to the owners' mailboxes once (marker file `.legacy_balances_migrated`).
- **Config.** New fields since 1.x: `playerShops.allowBuybackWithdraw`, `mailbox.deliverPurchasesToInventory`, `mailbox.combineSaleEarnings`, `rentalStations.rentalShopsCountTowardShopLimit`. With KyuubiSoft Core installed they are merged into your `config.json`; without Core they use their defaults (old behaviour) until the file is saved by the admin window.