Skip to main content

FAQ & Troubleshooting

Common questions and solutions for the Shop System.

Frequently Asked Questions​

How do I create a new shop?​

There are two ways:

  1. Admin Panel -- Run /ksadmin, open Shop Admin, and click Add Shop. See the Admin Panel guide.
  2. JSON File -- Create a new .json file in configs/kyuubisoft_core/shops/ and run /ksadmin reload.

How do players open a shop?​

  • Via command: /ksshop open <shopId>
  • Via NPC: Set "shopId": "your_shop" on a citizen in citizens.json. Players press F on the NPC to open the shop.
  • Via dialog macro: Use a dialog command to run /ksshop open your_shop when a player selects a dialog choice.

Can I use physical items as currency?​

Yes. Set the shop's currencyId to item:<ItemId>. For example:

"currencyId": "item:Ingredient_Bar_Gold"

The system automatically counts and deducts items from the player's inventory. No additional setup is needed. See Currencies for details.

How does daily rotation work?​

Set "dailyShopSize" to a number greater than zero in the shop settings. The system selects that many items from the full catalog each day using weighted random selection. The rotation is deterministic per player -- the same player sees the same daily shop on the same day.

"settings": {
  "dailyShopSize": 6,
  "itemsPerPage": 9
}

Items with higher weight values appear more frequently in the rotation.

Can players sell items?​

Yes, if sell mode is enabled on the shop. Set "sellEnabled": true in the shop config:

{
  "sellEnabled": true,
  "sellPricePercent": 50,
  "sellCurrencyId": null
}

Players can sell via:

  • /ksshop sell <shopId>
  • NPC interaction if "sellShopId" is set on the citizen

How is the sell price calculated?​

The sell price is determined by this priority chain:

  1. Per-item sellPrice -- If set on a catalog item, this value is used directly.
  2. Explicit sellItems list -- If the item appears in the shop's sellItems array, that price is used.
  3. Percentage of buy price -- Falls back to sellPricePercent of the item's buy cost (default: 50%).

Items not in the catalog and not in the sellItems list cannot be sold.

Can I restrict who buys specific items?​

Yes. Set a permission field on the shop item:

{
  "itemId": "Weapon_Sword_Legendary",
  "cost": 100,
  "permission": "shop.vip"
}

Only players with shop.vip can purchase this item.

Can a shop execute commands instead of giving items?​

Yes. Set a command field on the shop item:

{
  "itemId": "xp_boost_100",
  "name": "100 XP Boost",
  "cost": 10,
  "command": "/ksadmin addxp {player} 100",
  "commandRunAsServer": true
}

The {player} and {PlayerName} placeholders are replaced with the buyer's username. Set commandRunAsServer to true to run the command as the console, or false to run it as the player.

Troubleshooting​

Shop does not open​

Symptoms: Running /ksshop open <shopId> shows "Shop not found" or "Currency not available."

Solutions:

  1. Check the shop ID -- Run /ksshop list to see all registered shops. The ID must match exactly (case-sensitive).
  2. Check the currency provider -- If the shop uses quest_tokens but the Quest mod is not installed, the currency provider is not registered and the shop cannot open.
  3. Check the JSON syntax -- Invalid JSON in the shop file prevents loading. Check the server console for parse errors on startup.
  4. Reload after changes -- Run /ksadmin reload after editing shop files.

"Currency not available" error​

Cause: The currency provider for the shop's currencyId is not registered.

Currency IDRequired Mod
quest_tokensQuest System
achievement_pointsAchievement System
item:<ItemId>Core (auto-detected, always available)

Solution: Install the required mod, or change the shop's currencyId to an item-based currency like item:Ingredient_Bar_Gold.

Purchase fails silently​

Possible causes:

  1. Insufficient funds -- The player does not have enough currency.
  2. Inventory full -- The item cannot be placed in the player's inventory. Currency is refunded automatically.
  3. Purchase limit reached -- The player has hit the maxPurchases limit for this item today. Limits reset daily.
  4. Missing permission -- The item requires a permission the player does not have.

Sell mode not working​

  1. Check sellEnabled -- Must be true in the shop config.
  2. Check sell whitelist -- If sellWhitelist is set, only items in the list can be sold.
  3. Check sell blacklist -- Items in sellBlacklist can never be sold.
  4. Command items -- Items with a command field are never sellable.
  5. Item not in catalog -- Items that are not in the shop's catalog or sellItems list cannot be sold.

Daily shop shows different items than expected​

This is by design. Daily rotation is deterministic per player, meaning different players see different daily shops. The rotation uses a seed based on the player's UUID and the current date.

If you want all players to see the same items, set dailyShopSize to 0 for a fixed catalog.

Custom shop file not loaded​

  1. Check the filename -- Custom override files must be named custom_<shopId>.json inside the custom/ folder.
  2. Check JSON validity -- Invalid JSON prevents loading. Check the server console for errors.
  3. Reload -- Run /ksadmin reload after adding custom files.

NPC shop does not open on interaction​

  1. Check shopId -- The citizen must have "shopId": "your_shop_id" set in its config.
  2. Check fKeyInteractionEnabled -- Must be true for the interaction prompt to appear.
  3. Quest profile conflict -- If the Quest mod has an NPC profile for this citizen, it intercepts the interaction. Remove the quest profile or use a dialog macro to open the shop.