Configuration
Version: 2.0.6
The main file is:
mods/kyuubisoft_shops/config.jsonIt is created from the defaults on the first start. With KyuubiSoft Core installed, new default fields are merged into an existing file on every start; without Core, missing fields simply use their defaults.
Changing settings:
- In game: the Settings sections of the admin window (
/kssa admin, see Admin Panel). A save writesconfig.jsonand is active at once (except where noted). - By hand: edit the file, then
/kssa reloador restart. - A few values are only read at server start; they are marked restart below.
Fields marked no effect are still read from the file but nothing in 2.0.6 uses them.
features
Section titled “features”"features": { "playerShops": true, "adminShops": true, "directory": true, "ratings": true, "notifications": true, "shopOfTheWeek": false, "rentSystem": false, "claimsIntegration": true}| Field | Default | Effect | Admin window |
|---|---|---|---|
playerShops | true | false: nobody can open new player shops (license and /ksshop create); existing shops keep working | General: “Allow player shops” |
adminShops | true | false: /kssa createadmin is refused. Template files in admin-shops/ still load | - |
directory | true | false: /ksshop browse is refused. The other ways into the market (/ksshop myshops, rentalstations, the shop window’s back button) still open it | General: “Market active” |
ratings | true | Together with ratings.enabled: false hides the Reviews tab and refuses new ratings in the shop window | General: “Ratings” (sets both) |
notifications | true | no effect (see notifications.enabled) | - |
shopOfTheWeek | false | Runs a daily task (first run 10 minutes after the start): ends expired features and, with featured.autoFeatureTopRated, features the best shops. restart | - |
rentSystem | false | no effect (the legacy rent is rent.enabled; rental stands are rentalStations) | - |
claimsIntegration | true | Only used together with playerShops.requireClaim | - |
playerShops
Section titled “playerShops”"playerShops": { "maxShopsPerPlayer": 3, "maxItemsPerShop": 45, "creationCost": 500, "requireClaim": false, "allowNpcCustomization": true, "nameMinLength": 3, "nameMaxLength": 24, "descriptionMaxLength": 100, "maxTagsPerShop": 5, "listingEnabled": true, "listingPricePerDay": 100, "listingMinDays": 1, "listingMaxDays": 30, "listingFreeDaysOnCreate": 7, "allowBuybackWithdraw": false}| Field | Default | Effect | Admin window |
|---|---|---|---|
maxShopsPerPlayer | 3 | Shops per player (at least 1). Packed shops count; shops on rented stands count unless rentalStations.rentalShopsCountTowardShopLimit is false. Raised per rank with ks.shop.limit.shops.N | General: “Shops per player” (1-100) |
maxItemsPerShop | 45 | Different offers per shop (1-45). Raised with ks.shop.limit.items.N, never above 45 | - |
creationCost | 500 | Gold paid when a shop opens (license or /ksshop create). /ksshop delete pays half of the current value back | General: “Opening cost” |
requireClaim | false | With features.claimsIntegration and KyuubiSoft Claims installed: opening a shop inside a claim is only allowed for its owner, trusted players, co-owners and guild members who may build there (never banned players). In a Claims server zone only when the zone allows building, or for Claims admins. Free land is always allowed. Setting a packed shop up again is not checked | - |
allowNpcCustomization | true | When a shop has no merchant look set, its merchant wears the owner’s skin. false: the npc.defaultSkinUsername look instead. A look set in the editor is used either way | - |
nameMinLength / nameMaxLength | 3 / 24 | Length of shop names (license, /ksshop create, rename, editor, /kssa createadmin). Names are unique across all shops, not case-sensitive | General: “Name at least” / “Name at most” (1-64) |
descriptionMaxLength | 100 | Length of the shop description | General: “Description at most” (0-500) |
maxTagsPerShop | 5 | no effect | - |
listingEnabled | true | true: player shops show in the market only while their listing runs. false: new player shops are listed forever, buying a listing is refused and the editor hides the listing section. Shops that were already unlisted stay unlisted | General: “Market listing costs gold” |
listingPricePerDay | 100 | Gold per listing day | General: “Listing per day” |
listingMinDays / listingMaxDays | 1 / 30 | Days per purchase; more days are added to a running listing | General: “Listing at least” / “Listing at most” (1-365) |
listingFreeDaysOnCreate | 7 | Free listing days for the first shop a player ever opens (remembered per player in the database, also after deleting the shop). 0 = none | General: “Free days for the first shop” |
allowBuybackWithdraw | false | true: owners can take gold back out of the till (editor, Till tab). false: only packing up returns the till (as before 2.0.0) | General: “Owners may withdraw the buyback till” |
adminShops
Section titled “adminShops”"adminShops": { "unlimitedStock": true, "allowBuyAndSell": true, "defaultNpcSkin": ""}| Field | Default | Effect |
|---|---|---|
unlimitedStock | true | Offers of server shop templates get unlimited stock (stock and maxStock from the file are ignored). Items dragged into a server shop in the editor always have the dragged amount as stock |
allowBuyAndSell | true | no effect |
defaultNpcSkin | "" | no effect; use npc.defaultSkinUsername, npcSkinUsername in a template or the merchant look in the editor |
economy
Section titled “economy”"economy": { "provider": "auto", "currencyName": "Gold", "currencySymbol": "", "maxPrice": 1000000, "minPrice": 1}| Field | Default | Effect | Admin window |
|---|---|---|---|
provider | "auto" | no effect; the economy is always detected (Core first, then VaultUnlocked) | Economy: “Currency” shows what was found |
currencyName / currencySymbol | "Gold" / "" | no effect; the windows use the economy’s currency name (fallback “Gold”). From 2.0.7 (not released yet) currencyName is used when the economy reports no name of its own; currencySymbol stays without effect | - |
minPrice / maxPrice | 1 / 1000000 | Allowed price per piece in the editor (sale and buyback). The minimum is at least 1. A new offer starts at 10, moved into this range | Economy: “Minimum price” / “Maximum price” |
"tax": { "enabled": false, "buyTaxPercent": 5.0, "sellTaxPercent": 5.0, "showTaxInPrice": true, "taxRecipient": "server"}| Field | Default | Effect | Admin window |
|---|---|---|---|
enabled | false | Switches both taxes on | Economy: “Collect taxes” |
buyTaxPercent | 5.0 | Paid by the buyer on top of the price. The seller gets the full price | Economy: “Tax on purchases” (0-100) |
sellTaxPercent | 5.0 | Taken from what a player receives when selling to a shop. The shop’s till still pays the full price | Economy: “Tax on sales to shops” (0-100) |
showTaxInPrice | true | no effect; the windows always show the tax line when a tax is on | |
taxRecipient | "server" | no effect; taxes always leave the economy |
Taxes are rounded to whole gold and added to the shop’s “tax paid” total. /kssa settax <0.0-1.0> sets both percentages at once.
rent (legacy daily rent)
Section titled “rent (legacy daily rent)”"rent": { "enabled": false, "costPerDay": 50.0, "gracePeriodDays": 3, "autoCloseOnExpire": true, "autoDeleteOnUnpaidDays": 7, "rentExemptForNewShopsDays": 7, "rentNotificationBeforeDays": 1, "maxCycleDays": 30}An old system that charges owners a daily rent for every player shop. It is not the rental stands system and not in the admin window.
With enabled: true (restart) an hourly task (first run 5 minutes after the start) handles every player shop older than rentExemptForNewShopsDays: once the rent is more than gracePeriodDays overdue it tries to take costPerDay from the owner; if that fails and autoCloseOnExpire is on, the shop is closed. More than autoDeleteOnUnpaidDays overdue, the shop is deleted (stock and till go to the owner’s mailbox, the merchant is removed). Owners see “A shop was closed / removed …” notices on the mailbox’s Sales tab. rentNotificationBeforeDays and maxCycleDays have no effect.
ratings
Section titled “ratings”"ratings": { "enabled": true, "minStars": 1, "maxStars": 5, "allowComments": true, "commentMaxLength": 100, "cooldownMinutes": 60}| Field | Default | Effect | Admin window |
|---|---|---|---|
enabled | true | See features.ratings | General: “Ratings” |
minStars / maxStars | 1 / 5 | Accepted rating range (kept within 1-5) | - |
allowComments | true | false: ratings are diamonds only, the comment field is hidden | General: “Comments with ratings” |
commentMaxLength | 100 | Longer comments are cut | General: “Comment at most” (0-500) |
cooldownMinutes | 60 | How long a player waits before changing their rating of the same shop. 0 = any time | General: “Wait between ratings” |
Each player has one rating per shop; rating again replaces it.
notifications
Section titled “notifications”"notifications": { "enabled": true, "batchOnLogin": true, "maxStoredPerPlayer": 50, "soundEnabled": true}A sale notification is stored when someone buys from your shop while you are offline.
| Field | Default | Effect |
|---|---|---|
enabled | true | false: hides the mailbox’s Sales tab and refuses /ksshop notifications |
batchOnLogin | true | On join: “While you were offline: N sale(s), N item(s) sold for X.” plus a hint to /ksshop notifications |
maxStoredPerPlayer | 50 | Only the newest N notifications per player are kept; the Sales tab shows up to 50 |
soundEnabled | true | no effect |
"npc": { "defaultEntityId": "NPC_Shopkeeper", "defaultSkinUsername": "", "lookAtPlayer": true, "interactionRange": 5.0, "showNameplate": true, "spawnDelaySecondsOnJoin": 3, "skinRetryDelaySeconds": 5}| Field | Default | Effect |
|---|---|---|
defaultEntityId | "NPC_Shopkeeper" | no effect (merchants use the plugin’s own role Shop_Keeper_Role) |
defaultSkinUsername | "" | Player name whose skin merchants wear when no other look applies (server shops, free rental stands, allowNpcCustomization: false). Empty = default model |
lookAtPlayer | true | Merchants turn their head to nearby players. restart |
interactionRange / showNameplate | 5.0 / true | no effect (name tags are switched per shop in the editor) |
spawnDelaySecondsOnJoin | 3 | Seconds (0-60) between the first player entering a world and the merchants of that world spawning, so skins apply reliably |
skinRetryDelaySeconds | 5 | When a skin lookup fails, it is tried once more after this many seconds (0-60, 0 = no retry) |
Skins are looked up by player name at playerdb.co and cached in skin-cache.json.
directory
Section titled “directory”"directory": { "shopsPerPage": 9, "defaultSortBy": "rating", "showEmptyShops": false, "showClosedShops": false}No effect in 2.0.6. The market shows up to 60 shop cards and 120 offers, sorts by rating first, lists open shops only and also shows shops that sell nothing yet.
featured
Section titled “featured”"featured": { "enabled": false, "cost": 1000, "durationDays": 7, "maxFeaturedSlots": 3, "autoFeatureTopRated": false, "autoFeatureMinRating": 4.5, "autoFeatureMinSales": 50}A featured shop is listed first in the market when sorting by rating and carries a “Featured” chip.
| Field | Default | Effect |
|---|---|---|
enabled / cost | false / 1000 | no effect (players cannot buy a feature; admins set it) |
durationDays | 7 | Length of a feature set by the admin window, /kssa feature or the automatic feature |
autoFeatureTopRated | false | With features.shopOfTheWeek: features the best open player shops once a day |
autoFeatureMinRating | 4.5 | Minimum average rating (and at least one rating) |
autoFeatureMinSales | 50 | Minimum total revenue in gold (not the number of sales) |
maxFeaturedSlots | 3 | The automatic feature only fills up to this many featured shops (admins can feature more by hand) |
rentalStations
Section titled “rentalStations”"rentalStations": { "enabled": true, "defaultPricePerDay": 100, "defaultMaxDays": 7, "defaultMinBid": 500, "defaultBidIncrement": 10, "defaultAuctionDurationMinutes": 60, "maxConcurrentRentalsDefault": 1, "onEmptyAuction": "RESTART", "auctionAntiSnipingSeconds": 30, "auctionEndingSoonSeconds": 60, "extendMaxDays": 7, "releaseEarlyGoldRefundFraction": 0.0, "rentalShopsListFree": true, "rentalShopsCountTowardShopLimit": true}| Field | Default | Effect | Admin window (Rental stands settings) |
|---|---|---|---|
enabled | true | false: the market hides the Rental stands tab. The expiry and countdown tasks only start when it is true at server start. restart | ”Rental stands active” |
rentalShopsListFree | true | A shop on a rented stand is listed in the market for free until the rental ends | ”Rented shops are listed for free” |
rentalShopsCountTowardShopLimit | true | Shops on rented stands count toward playerShops.maxShopsPerPlayer, as before 2.0.0. false: only a player’s own shops (packed ones included) use the shop limit, so a rented stand never blocks opening or receiving a shop. Missing = true | - |
defaultPricePerDay | 100 | Price per day of new fixed-price stands | ”Price per day” |
defaultMaxDays | 7 | Longest rental at once of new fixed-price stands; rental days of the winner of new auction stands | ”Maximum duration” |
defaultMinBid | 500 | First bid of new auction stands | ”Minimum bid” |
defaultBidIncrement | 10 | Minimum raise over the high bid | ”Bid step” |
defaultAuctionDurationMinutes | 60 | Length of an auction round | ”Auction duration” (1-10080 min) |
maxConcurrentRentalsDefault | 1 | Stands one player may rent at the same time; more with ks.rental.limit.N | ”Stands per player” |
auctionAntiSnipingSeconds | 30 | A bid in the last N seconds extends the auction by N seconds. 0 = off | ”A late bid extends by” |
auctionEndingSoonSeconds | 60 | One chat message to all online players when an auction has N seconds left. 0 = off | ”Ending soon” notice |
extendMaxDays | 7 | Most days per extension of a fixed-price rental | ”Extend at most” |
releaseEarlyGoldRefundFraction | 0.0 | Share (0.0-1.0) of the paid days left that is refunded when a fixed-price rental is ended early | ”Refund on early release” (in percent) |
onEmptyAuction | "RESTART" | What happens when an auction ends without bids: RESTART new round, VACANT the auction rests until an admin restarts it, DELETE the stand is deleted together with its placeholder shop and merchant | ”Auction without bids”: Restart / Let rest / Delete |
The default* values only apply to stands created afterwards. Details: Rental Stands.
mailbox
Section titled “mailbox”"mailbox": { "deliverPurchasesToInventory": false, "combineSaleEarnings": false}| Field | Default | Effect | Admin window |
|---|---|---|---|
deliverPurchasesToInventory | false | true: purchases go straight into the buyer’s inventory; only what does not fit is mailed. false: every purchase is mailed (as before 2.0.0) | Economy: “Purchases straight into the inventory” |
combineSaleEarnings | false | true: the earnings of a shop are added to one open money mail per shop (“Earnings from X · N sales”). false: one money mail per sale | Economy: “Collect sale earnings in one mail” |
database
Section titled “database”"database": { "type": "sqlite", "sqlitePath": "shops.db", "mysql": { "host": "localhost", "port": 3306, "database": "hytale", "username": "root", "password": "" }}type is sqlite (file sqlitePath inside the data folder) or mysql (uses the mysql block). restart. The tables are created on the first start; see API Reference.
itemBlacklist
Section titled “itemBlacklist”"itemBlacklist": []Item IDs (for example Weapon_Sword_Mithril, compared without case) that cannot be put into a shop in the editor. Offers that already exist stay until their owner takes them out. Change it with /kssa blacklist, the admin window (Blacklist) or by hand; both in-game ways save the file.
categories
Section titled “categories”"categories": [ { "id": "weapons", "displayName": "Weapons", "icon": "Iron_Sword", "sortOrder": 1 }, ...]No effect in 2.0.6. The eight categories are fixed: weapons, armor, tools, resources, potions, food, building, misc. Their names come from the language files (shop.category.*, shop.ui.editor.cat.*, shop.ui.create.cat.*), the market icons are built in.
Server shop templates
Section titled “Server shop templates”Every *.json file in mods/kyuubisoft_shops/admin-shops/ is one server shop. The folder is created on the first start with the disabled example example_blacksmith.json:
{ "enabled": false, "id": "blacksmith", "name": "Village Blacksmith", "description": "Fine weapons and sturdy armor.", "category": "weapons", "npcSkinUsername": "Blacksmith", "currencyId": "", "worldName": "", "posX": 0, "posY": 0, "posZ": 0, "npcRotY": 0, "items": [ { "itemId": "Weapon_Sword_Iron", "buyPrice": 150, "sellPrice": 75, "stock": -1, "maxStock": -1, "buyEnabled": true, "sellEnabled": true, "dailyBuyLimit": 0, "dailySellLimit": 0, "category": "weapons" } ]}| Field | Meaning |
|---|---|
enabled | false skips the file. Missing = enabled (files from before 2.0.0). Disabling a file does not remove a shop that was already created; delete it in game |
id | A UUID, or any text (turned into a fixed UUID). /kssa deleteadmin <id> accepts the text |
name, description, category | Shop name, description and one of the eight category IDs |
npcSkinUsername | Player name whose skin the merchant wears |
worldName | World of the shop; empty = the server’s default world |
posX, posY, posZ, npcRotY | Position and facing of the merchant |
items[].buyPrice | What customers pay per piece (with buyEnabled) |
items[].sellPrice | What the shop pays per piece when customers sell (with sellEnabled); the server pays, there is no till |
items[].stock, maxStock | Only used with adminShops.unlimitedStock: false; -1 = unlimited / no cap |
items[].dailyBuyLimit | Buyback quota: the shop buys at most this many in total, then stops buying the item. 0 = no limit |
items[].category | Shown next to the rarity in the shop window’s item detail (the market filters by the shop’s category) |
currencyId, items[].dailySellLimit | no effect |
Offers fill the grid in file order. Templates carry no item metadata (enchantments).
When a template is applied: the plugin remembers the content of each file it applied (admin-shops/.applied.json).
- No shop with that id yet: the shop is created.
- The file is new or changed since it was last applied: the existing shop is rewritten from it (offers, name, description, category, look, position).
- The file is unchanged: the shop is left as admins edited it in game.
- The file is unchanged and the shop was deleted in game: it stays deleted until the file changes.
Changed files are applied on the next start. On the first start of 2.0.0 nothing is recorded yet, so every enabled template rewrites its shop once.
Localization
Section titled “Localization”- Language files:
mods/kyuubisoft_shops/localization/<lang>.jsonforen-US,de-DE,fr-FR,es-ES,pt-BR,ru-RU,pl-PL,tr-TR,it-IT. - Each player sees their language from
/kslang(if the server lets players choose), otherwise the server’s default player language (set in KyuubiSoft Core’s/ksadminhub, Language tab), otherwise their client language. Missing keys fall back toen-US. - The files carry
"_localization_version"(32 in 2.0.6). When a file on disk is older, it is saved as<lang>.json.backup-v<old>and replaced by the new default. Your own edits are not merged; copy them over from the backup. - Edits are loaded by
/kssa reloador the admin window’s Reload. - The names and descriptions of the license and the mailbox block are part of the asset pack in the jar (
Server/Languages/<lang>/shops.lang) and cannot be changed in the data folder. - A few texts are not translated: the bound license tooltip (“Shop Token: …”), the free stand name plates (
[100g/day],[AUCTION 500g]),[CLOSED]on name plates and some chat lines of/ksshop history,/ksshop searchand/kslang(bare/kslanganswers in chat with your current language, the available codes and how to change it).