Skip to content

Configuration

Version: 2.0.6

The main file is:

mods/kyuubisoft_shops/config.json

It 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 writes config.json and is active at once (except where noted).
  • By hand: edit the file, then /kssa reload or 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": {
"playerShops": true,
"adminShops": true,
"directory": true,
"ratings": true,
"notifications": true,
"shopOfTheWeek": false,
"rentSystem": false,
"claimsIntegration": true
}
FieldDefaultEffectAdmin window
playerShopstruefalse: nobody can open new player shops (license and /ksshop create); existing shops keep workingGeneral: “Allow player shops”
adminShopstruefalse: /kssa createadmin is refused. Template files in admin-shops/ still load-
directorytruefalse: /ksshop browse is refused. The other ways into the market (/ksshop myshops, rentalstations, the shop window’s back button) still open itGeneral: “Market active”
ratingstrueTogether with ratings.enabled: false hides the Reviews tab and refuses new ratings in the shop windowGeneral: “Ratings” (sets both)
notificationstrueno effect (see notifications.enabled)-
shopOfTheWeekfalseRuns a daily task (first run 10 minutes after the start): ends expired features and, with featured.autoFeatureTopRated, features the best shops. restart-
rentSystemfalseno effect (the legacy rent is rent.enabled; rental stands are rentalStations)-
claimsIntegrationtrueOnly used together with playerShops.requireClaim-

"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
}
FieldDefaultEffectAdmin window
maxShopsPerPlayer3Shops 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.NGeneral: “Shops per player” (1-100)
maxItemsPerShop45Different offers per shop (1-45). Raised with ks.shop.limit.items.N, never above 45-
creationCost500Gold paid when a shop opens (license or /ksshop create). /ksshop delete pays half of the current value backGeneral: “Opening cost”
requireClaimfalseWith 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-
allowNpcCustomizationtrueWhen 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 / nameMaxLength3 / 24Length of shop names (license, /ksshop create, rename, editor, /kssa createadmin). Names are unique across all shops, not case-sensitiveGeneral: “Name at least” / “Name at most” (1-64)
descriptionMaxLength100Length of the shop descriptionGeneral: “Description at most” (0-500)
maxTagsPerShop5no effect-
listingEnabledtruetrue: 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 unlistedGeneral: “Market listing costs gold”
listingPricePerDay100Gold per listing dayGeneral: “Listing per day”
listingMinDays / listingMaxDays1 / 30Days per purchase; more days are added to a running listingGeneral: “Listing at least” / “Listing at most” (1-365)
listingFreeDaysOnCreate7Free listing days for the first shop a player ever opens (remembered per player in the database, also after deleting the shop). 0 = noneGeneral: “Free days for the first shop”
allowBuybackWithdrawfalsetrue: 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": {
"unlimitedStock": true,
"allowBuyAndSell": true,
"defaultNpcSkin": ""
}
FieldDefaultEffect
unlimitedStocktrueOffers 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
allowBuyAndSelltrueno effect
defaultNpcSkin""no effect; use npc.defaultSkinUsername, npcSkinUsername in a template or the merchant look in the editor

"economy": {
"provider": "auto",
"currencyName": "Gold",
"currencySymbol": "",
"maxPrice": 1000000,
"minPrice": 1
}
FieldDefaultEffectAdmin 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 / maxPrice1 / 1000000Allowed price per piece in the editor (sale and buyback). The minimum is at least 1. A new offer starts at 10, moved into this rangeEconomy: “Minimum price” / “Maximum price”

"tax": {
"enabled": false,
"buyTaxPercent": 5.0,
"sellTaxPercent": 5.0,
"showTaxInPrice": true,
"taxRecipient": "server"
}
FieldDefaultEffectAdmin window
enabledfalseSwitches both taxes onEconomy: “Collect taxes”
buyTaxPercent5.0Paid by the buyer on top of the price. The seller gets the full priceEconomy: “Tax on purchases” (0-100)
sellTaxPercent5.0Taken from what a player receives when selling to a shop. The shop’s till still pays the full priceEconomy: “Tax on sales to shops” (0-100)
showTaxInPricetrueno 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": {
"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": {
"enabled": true,
"minStars": 1,
"maxStars": 5,
"allowComments": true,
"commentMaxLength": 100,
"cooldownMinutes": 60
}
FieldDefaultEffectAdmin window
enabledtrueSee features.ratingsGeneral: “Ratings”
minStars / maxStars1 / 5Accepted rating range (kept within 1-5)-
allowCommentstruefalse: ratings are diamonds only, the comment field is hiddenGeneral: “Comments with ratings”
commentMaxLength100Longer comments are cutGeneral: “Comment at most” (0-500)
cooldownMinutes60How long a player waits before changing their rating of the same shop. 0 = any timeGeneral: “Wait between ratings”

Each player has one rating per shop; rating again replaces it.


"notifications": {
"enabled": true,
"batchOnLogin": true,
"maxStoredPerPlayer": 50,
"soundEnabled": true
}

A sale notification is stored when someone buys from your shop while you are offline.

FieldDefaultEffect
enabledtruefalse: hides the mailbox’s Sales tab and refuses /ksshop notifications
batchOnLogintrueOn join: “While you were offline: N sale(s), N item(s) sold for X.” plus a hint to /ksshop notifications
maxStoredPerPlayer50Only the newest N notifications per player are kept; the Sales tab shows up to 50
soundEnabledtrueno effect

"npc": {
"defaultEntityId": "NPC_Shopkeeper",
"defaultSkinUsername": "",
"lookAtPlayer": true,
"interactionRange": 5.0,
"showNameplate": true,
"spawnDelaySecondsOnJoin": 3,
"skinRetryDelaySeconds": 5
}
FieldDefaultEffect
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
lookAtPlayertrueMerchants turn their head to nearby players. restart
interactionRange / showNameplate5.0 / trueno effect (name tags are switched per shop in the editor)
spawnDelaySecondsOnJoin3Seconds (0-60) between the first player entering a world and the merchants of that world spawning, so skins apply reliably
skinRetryDelaySeconds5When 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": {
"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": {
"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.

FieldDefaultEffect
enabled / costfalse / 1000no effect (players cannot buy a feature; admins set it)
durationDays7Length of a feature set by the admin window, /kssa feature or the automatic feature
autoFeatureTopRatedfalseWith features.shopOfTheWeek: features the best open player shops once a day
autoFeatureMinRating4.5Minimum average rating (and at least one rating)
autoFeatureMinSales50Minimum total revenue in gold (not the number of sales)
maxFeaturedSlots3The automatic feature only fills up to this many featured shops (admins can feature more by hand)

"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
}
FieldDefaultEffectAdmin window (Rental stands settings)
enabledtruefalse: 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”
rentalShopsListFreetrueA shop on a rented stand is listed in the market for free until the rental ends”Rented shops are listed for free”
rentalShopsCountTowardShopLimittrueShops 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-
defaultPricePerDay100Price per day of new fixed-price stands”Price per day”
defaultMaxDays7Longest rental at once of new fixed-price stands; rental days of the winner of new auction stands”Maximum duration”
defaultMinBid500First bid of new auction stands”Minimum bid”
defaultBidIncrement10Minimum raise over the high bid”Bid step”
defaultAuctionDurationMinutes60Length of an auction round”Auction duration” (1-10080 min)
maxConcurrentRentalsDefault1Stands one player may rent at the same time; more with ks.rental.limit.N”Stands per player”
auctionAntiSnipingSeconds30A bid in the last N seconds extends the auction by N seconds. 0 = off”A late bid extends by”
auctionEndingSoonSeconds60One chat message to all online players when an auction has N seconds left. 0 = off”Ending soon” notice
extendMaxDays7Most days per extension of a fixed-price rental”Extend at most”
releaseEarlyGoldRefundFraction0.0Share (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": {
"deliverPurchasesToInventory": false,
"combineSaleEarnings": false
}
FieldDefaultEffectAdmin window
deliverPurchasesToInventoryfalsetrue: 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”
combineSaleEarningsfalsetrue: the earnings of a shop are added to one open money mail per shop (“Earnings from X · N sales”). false: one money mail per saleEconomy: “Collect sale earnings in one mail”

"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": []

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": [
{ "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.


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"
}
]
}
FieldMeaning
enabledfalse 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
idA UUID, or any text (turned into a fixed UUID). /kssa deleteadmin <id> accepts the text
name, description, categoryShop name, description and one of the eight category IDs
npcSkinUsernamePlayer name whose skin the merchant wears
worldNameWorld of the shop; empty = the server’s default world
posX, posY, posZ, npcRotYPosition and facing of the merchant
items[].buyPriceWhat customers pay per piece (with buyEnabled)
items[].sellPriceWhat the shop pays per piece when customers sell (with sellEnabled); the server pays, there is no till
items[].stock, maxStockOnly used with adminShops.unlimitedStock: false; -1 = unlimited / no cap
items[].dailyBuyLimitBuyback quota: the shop buys at most this many in total, then stops buying the item. 0 = no limit
items[].categoryShown next to the rarity in the shop window’s item detail (the market filters by the shop’s category)
currencyId, items[].dailySellLimitno 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.


  • Language files: mods/kyuubisoft_shops/localization/<lang>.json for en-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 /ksadmin hub, Language tab), otherwise their client language. Missing keys fall back to en-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 reload or 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 search and /kslang (bare /kslang answers in chat with your current language, the available codes and how to change it).