Getting Started
Version: 2.0.6
Installation
Section titled “Installation”- Stop the server.
- Put
KyuubiSoftShops-2.0.6.jarinto the server’smods/folder. When you update, remove the oldKyuubiSoftShops-*.jarfirst. - Make sure an economy is available (see below).
- Start the server. The plugin creates its data folder
mods/kyuubisoft_shops/and fills it with the default files.
Economy
Section titled “Economy”Everything that costs or pays gold needs an economy. The plugin looks for one in this order:
- KyuubiSoft Core: its external economy bridge.
- 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”).
Optional plugins
Section titled “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) |
| VaultUnlocked | Economy when Core is not installed |
Files after the first start
Section titled “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 modsWith database.type set to mysql the tables live in your MySQL database instead of shops.db.
Boot log
Section titled “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)
Section titled “Your first shop (as a player)”- Craft a Mailbox at the Carpentrybench (4 Oak Planks + 1 Iron Bar) and place it. Everything you buy and earn arrives there.
- 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.
- 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.
- 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.
- 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.
- Fill the till on the Till tab if your shop buys items back: buybacks are paid from it.
- 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>. - Collect at your mailbox: sale earnings arrive there as money mails.
/ksshop help prints a short version of these steps in game.
A first test (as an admin)
Section titled “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, SaveF 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 breadA 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 selectedOr use the admin window: /kssa admin, section Rental stands, + New stand here. See Rental Stands.
Permissions in short
Section titled “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 trueIf your permission plugin answers “no” for nodes that are not set, grant the player nodes explicitly. Details and rank examples are on Permissions.
Upgrading from 1.x
Section titled “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 myrentalsopens 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.jsonwithout"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 yourconfig.json; without Core they use their defaults (old behaviour) until the file is saved by the admin window.