Skip to content

Getting Started

Version: 2.0.6

  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.

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”).

PluginWhat Shops uses it for
KyuubiSoft CoreEconomy bridge (preferred), merging new default fields into config.json, the showcase-mode write guard
KyuubiSoft ClaimsClaim check when playerShops.requireClaim is on (see Configuration)
VaultUnlockedEconomy when Core is not installed

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.

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.


  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.


/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.


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.


  • 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). 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.