Getting Started

Getting Started

1. Dependencies

Required for shop transactions to work:

• VaultUnlocked (TheNewEconomy:VaultUnlocked) - economy API
• An economy provider that registers with VaultUnlocked. Recommended: Ecotale (Ecotale:Ecotale)

If neither is installed, the plugin runs but shops cannot perform transactions - log will say No economy provider detected.

2. Install

1. Drop KyuubiSoftShops-1.0.0.jar into <server>/mods/
2. Start the server
3. The plugin extracts:
   • <server>/mods/kyuubisoft_shops/config.json
   • <server>/mods/kyuubisoft_shops/shops.db
   • <server>/mods/kyuubisoft_shops/localization/<lang>.json (9 files)

3. Verify the boot log

After [KyuubiSoft Shops] Setting up KS-Shops... you should see:

[KyuubiSoft Shops] Config loaded: ...
[KyuubiSoft Shops] Database initialized (sqlite)
[KyuubiSoft Shops] Economy via VaultUnlocked direct (Ecotale)
   ^ or "No economy provider detected (yet) ..." followed by
     "Economy provider attached on retry" within 20s
[KyuubiSoft Shops] Loaded N shops (N admin, N player)
[KyuubiSoft Shops] Loaded N rental slot(s)
[KyuubiSoft Shops] KS-Shops ready. N shops loaded.

If Economy provider attached on retry does not appear, your provider mod is not registering with VaultUnlocked - check its log. The plugin retries detection 4 times during early boot at +2s, +5s, +10s, +20s.

4. Grant base permissions

LuckPerms ignores the plugin’s default = true and answers false to any unset permission. You must grant the user permissions explicitly:

lp group default permission set ks.shop.user.create true
lp group default permission set ks.shop.user.edit true
lp group default permission set ks.shop.user.browse true
lp group default permission set ks.shop.user.collect true
lp group default permission set ks.shop.user.rate true
lp group default permission set ks.shop.user.delete true
lp group default permission set ks.rental.rent true
lp group default permission set ks.rental.bid true

For admins:

lp user <YourName> permission set ks.shop.admin true

⚠️ Avoid wildcards like ks.shop.* or * - they trip the plugin’s wildcard sentinel and OPs would silently inherit permanent listings, infinite max-shops etc. See Permissions for the deeper explanation.

5. First test

In-game with your admin account:

/kssa createadmin TestAdminShop
   -> NPC spawns at your position with a category icon
/kssa editadmin
   -> drag-and-drop editor opens
   -> drag bread, set buy price 5g, save
F-key the NPC
   -> browse view opens with the bread item in slot 0

With a non-admin alt account:

F-key the NPC
   -> browse view opens
   -> click bread, confirm 1, click BUY
   -> chat: "Bought 1x Bread for 5 Gold"
   -> bread appears in inventory, 5g deducted

6. Set up your first rental slot

/kssa createrental MarketSlot1 100 7
   ^ displayName, pricePerDay, maxDays
   -> vacant-shell NPC spawns at your position
   -> nameplate reads: "MarketSlot1 [100g/day]"

A non-admin player F-keying the slot now sees the rent-confirm dialog (slider 1..7 days, total cost). Confirming creates a renter shop at the slot position.

7. Skin setup (optional)

Player shops auto-use the owner’s username as their NPC skin. For admin shops, set:

"adminShops": {
  "defaultNpcSkin": "Notch"
}

or per-shop via the Settings tab in the editor (NPC Skin field + Apply Skin button).

If you don’t want any custom skins, leave both blank - NPCs use the default model.

---

Common first-run issues

Symptom	Likely cause	Fix
Unknown command: /ksshop	Player joined before the plugin was loaded	Reload client (Hytale caches the command list per session)
No economy provider detected after 20s	Provider mod not registering	Check the provider’s log; verify it’s a VaultUnlocked-compatible mod
Du hast keine Berechtigung dafür on /ksshop create	LuckPerms default-deny	Grant ks.shop.user.create explicitly (see step 4)
NPC has no skin (default grey model)	Owner-name lookup failed	Set npc.defaultSkinUsername to a real Hytale username, or wait for the retry to fire
Slot in shop browse is misaligned	Owner placed item in editor slot 10	Working as intended - slot positions are preserved; clicking still finds the item

For more, see FAQ.