# FAQ & Troubleshooting

# FAQ & Troubleshooting

Common questions and solutions for Core's NPC shops.

## Frequently Asked Questions

### How do I create a new shop?

There are two ways:

1. **Shop editor** — Run `/ksadmin`, open the tile **NPC Shops** and click **+ New shop**. Start from a preset, a shipped shop or a copy. See [Shop Editor](https://wiki.kyuubisoft.com/hytale/shop-system/admin-panel/).
2. **JSON file** — Create a new `.json` file in `mods/kyuubisoft_core/shops/` and run `/ksadmin reload`.

### How do players open a shop?

- **Via command:** `/ksnpcshop open <shopId>` (or `/ksnpcshop sell <shopId>` for the "Sell" tab)
- **Via NPC:** Link the NPC in the shop editor, or set `"shopId": "your_shop"` on a citizen. Players press **F** on the NPC to open the shop.
- **Via dialog:** Use the dialog action **Open shop**, or a dialog command `ksnpcshop open your_shop`. Dialog answers that open a shop are tagged "Opens shop" for the player.

`openVia` decides which of these ways work for a shop (`any`, `npc` or `command`).

### Why does `/ksshop` open something else?

`/ksshop` belongs to the [Player Shops](https://wiki.kyuubisoft.com/hytale/player-shops/) mod when it is installed. Core's NPC shops use `/ksnpcshop`. Update old dialogs, signs and commands that still call `ksshop open` for NPC shops.

### Can I use physical items as currency?

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

```json
"currencyId": "item:Ingredient_Bar_Gold"
```

The shop counts and removes the items from the player's inventory. See [Currencies](https://wiki.kyuubisoft.com/hytale/shop-system/currencies/). For the server's money use `"currencyId": "economy"` (needs an economy plugin, for example through VaultUnlocked).

### How does daily rotation work?

Set `"dailyShopSize"` to a number greater than zero. Each player gets their own pick of that many entries every day, drawn by `weight` and renewed at midnight (server time).

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

### Can players buy several at once?

Yes, with `"allowBuyMultiple": true` in the shop settings (or "Buy several at once" in the editor). Players then get a quantity stepper; the maximum is the daily limit, what they can afford and what fits into their inventory. Command entries are always bought one at a time.

### Can players sell items?

Yes, if selling is enabled on the shop:

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

Players can sell via:
- `/ksnpcshop sell <shopId>`
- the "Sell" tab of the shop window
- NPC interaction if `"sellShopId"` is set on the citizen

The "Sell" tab shows the price per piece, today's sell limit and a "Sell all" button.

### How is the sell price calculated?

The price per piece follows this order:

1. **Per-entry `sellPrice`** — if set on a catalog entry.
2. **Explicit `sellItems` list** — if the item is listed there.
3. **Percentage of the buy price** — `sellPricePercent` of the entry's price, divided by its quantity (default: 50%).

Items that are neither in the catalog nor in `sellItems` cannot be sold.

### Can I hide an entry without deleting it?

Yes. Switch it off in the editor, or set `"enabled": false` on the entry. It is no longer sold, rotated or bought back, and you can switch it on again later.

### Can I restrict who buys specific items?

Yes. Set a `permission` field on the entry (the entry shows as locked for everyone else), or on the whole shop (players without it cannot open the shop):

```json
{
  "itemId": "Weapon_Sword_Adamantite",
  "cost": 100,
  "permission": "shop.vip"
}
```

### Can a shop execute commands instead of giving items?

Yes. Set a `command` field on the entry:

```json
{
  "itemId": "xp_boost_100",
  "displayName": "100 XP Boost",
  "cost": 10,
  "command": "ksadmin addxp {player} 100",
  "commandRunAsServer": true
}
```

`{player}` and `{PlayerName}` become the buyer's name, `{uuid}` their UUID. `commandRunAsServer: true` runs the command as the console, `false` as the buyer. In the shop editor, console entries need `ks.core.admin.dialog.console` — see [Permissions](https://wiki.kyuubisoft.com/hytale/shop-system/permissions/).

---

## Troubleshooting

### Shop does not open

**Symptoms:** `/ksnpcshop open <shopId>` shows "There is no shop with the id …", "This shop can only be opened at its NPC" or "You don't have permission to access this shop."

**Solutions:**

1. **Check the shop ID** — Run `/ksnpcshop list`. The ID must match exactly.
2. **Check `openVia`** — `npc` shops only open at their NPC, `command` shops only by command.
3. **Check the shop's `permission`** — Players without it cannot open the shop.
4. **Check the command permission** — If an admin denied `ks.core.shop.user.use` (or `ks.shop.user.use` while the Core node is unset), the shop commands answer "You may not use the shop commands."
5. **Check the JSON syntax** — Invalid JSON prevents loading. Check the server console for errors.
6. **Reload after changes** — Run `/ksadmin reload` after editing shop files.

### "Currency not available" / nothing can be bought

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

| Currency ID | Required |
|---|---|
| `quest_tokens` | Quest System |
| `achievement_points` | Achievement System |
| `season_tokens` | Season Pass |
| `economy` | An economy plugin (e.g. through VaultUnlocked) |
| `item:<ItemId>` | Core (always available) |

**Solution:** Install the required mod or plugin, or change the shop's `currencyId`. The shop editor marks unknown currencies as an error.

### Purchase is refused

The shop window and the status line tell the player why:

1. **Not enough currency** — "Not enough … — … missing".
2. **Inventory full** — The purchase is refused before paying: "Your inventory is full — nothing was charged."
3. **Purchase limit reached** — "Sold out today"; limits reset daily.
4. **Missing permission** — The entry shows as locked.
5. **Command entry not available** — The command does not exist or the buyer may not use it; nothing is charged. If it fails while running, the price is refunded.

### 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 entries** — are never sellable.
5. **Item not in catalog** — Items that are not in the shop's catalog or `sellItems` list cannot be sold.
6. **Damaged or modified items** — are listed as "not sellable" when the shop cannot take them.

### Daily shop shows different items than expected

This is by design: every player gets their own daily pick. If you want all players to see the same entries, set `dailyShopSize` to `0` for a fixed catalog.

### A deleted shipped shop came back / does not come back

Since Core 2.9.0, shipped shops you delete or rename in the editor are listed in `shops/.removed_defaults` and are not extracted again. To restore one, remove its line from that file and restart or reload.

### Custom shop file not loaded

1. **Check the file name** — 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 the link** — In the shop editor (Settings → NPCs) or the citizen's `"shopId"`.
2. **Check `openVia`** — A `command` shop does not open at its NPC.
3. **Check `fKeyInteractionEnabled`** — Must be `true` for the interaction prompt to appear.
4. **NPC with a dialog** — If the NPC has a dialog, the shop opens through a dialog answer, not directly. The editor points this out.
5. **Quest profile** — If the Quest mod has an NPC profile for this citizen, the quest dialog comes first. Add a dialog answer that opens the shop.

### Shop opened from a dialog ignores clicks

**Symptoms:** A shop opened by the dialog action **Open shop** (or a command on the last answer) is visible, but no button works until the player presses Esc.

**Cause:** Before Core 2.9.6, the dialog closed first and the shop opened right after. On a server with ping, the late answer to that close removed the new shop on the server.

**Solution:** Update Core. The dialog window now stays until the shop is open (at most 5 seconds) and only closes if nothing replaced it.