Configuration

Player Shops Configuration

File location:

<server>/mods/kyuubisoft_shops/config.json

The plugin extracts a default config.json on first load. Edits require a server restart unless you use /kssa reload (only re-applies config + i18n - other in-memory state stays).

`features`

Top-level subsystem toggles.

"features": {
  "playerShops": true,
  "adminShops": true,
  "directory": true,
  "ratings": true,
  "notifications": true,
  "shopOfTheWeek": false,
  "rentSystem": false,
  "claimsIntegration": true
}

Field	Default	Effect
`playerShops`	`true`	Enables `/ksshop create`
`adminShops`	`true`	Enables `/kssa createadmin`
`directory`	`true`	Enables `/ksshop browse`. When `false` the browse page is blocked
`ratings`	`true`	Enables `/ksshop rate`
`notifications`	`true`	Stores per-player notifications for offline events
`shopOfTheWeek`	`false`	Periodic featured-shop rotation (advanced)
`rentSystem`	`false`	Legacy shop-rent (NOT rental stations - those have their own block)
`claimsIntegration`	`true`	Cross-checks Claims permission when creating shops in claimed land

`playerShops`

Limits and creation rules for player-owned shops.

"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
}

Listing block

listingEnabled = false makes every shop forever-listed (legacy behaviour)
listingFreeDaysOnCreate = 7 grants 7 days free directory visibility on the first shop a player ever creates. Persisted in shop_player_flags - delete + recreate cannot reuse the freebie
listingPricePerDay * days is the cost via /ksshop list <days>. Day count clamped to [listingMinDays, listingMaxDays]

`adminShops`

"adminShops": {
  "unlimitedStock": true,
  "allowBuyAndSell": true,
  "defaultNpcSkin": ""
}

Field	Effect
`unlimitedStock`	Admin shops never run out (`stock = -1` semantics)
`allowBuyAndSell`	Admin shops can buy from players AND sell to them
`defaultNpcSkin`	Username for skin if a specific admin shop has no `npcSkinUsername`. Empty = default model

`economy`

Cosmetic only - the actual provider is auto-detected via VaultUnlocked.

"economy": {
  "provider": "auto",
  "currencyName": "Gold",
  "currencySymbol": "",
  "maxPrice": 1000000,
  "minPrice": 1
}

maxPrice / minPrice clamp values entered in the editor.

`tax`

"tax": {
  "enabled": false,
  "buyTaxPercent": 5.0,
  "sellTaxPercent": 5.0,
  "showTaxInPrice": true,
  "taxRecipient": "server"
}

taxRecipient can be "server" (currency vanishes) or a player UUID/name to receive the tax pool.

`ratings`

"ratings": {
  "enabled": true,
  "minStars": 1,
  "maxStars": 5,
  "allowComments": true,
  "commentMaxLength": 100,
  "cooldownMinutes": 60
}

`notifications`

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

`npc`

"npc": {
  "defaultEntityId": "NPC_Shopkeeper",
  "defaultSkinUsername": "",
  "lookAtPlayer": true,
  "interactionRange": 5.0,
  "showNameplate": true,
  "spawnDelaySecondsOnJoin": 3,
  "skinRetryDelaySeconds": 5
}

Field	Effect
`defaultSkinUsername`	Fallback PlayerDB username for admin / un-customised NPCs. Empty = no skin (default model)
`lookAtPlayer`	NPC head turns toward nearest player. Disable for performance on large hubs
`interactionRange`	F-key range in blocks
`spawnDelaySecondsOnJoin`	(0..60) Defers per-world NPC spawn burst by N seconds after first player joins. Gives the client cosmetic subsystem time to initialise so skins apply correctly. Set 0 to disable
`skinRetryDelaySeconds`	(0..60) Retries a failed PlayerDB fetch once after N seconds. Set 0 to disable retries

`directory`

"directory": {
  "shopsPerPage": 9,
  "defaultSortBy": "rating",
  "showEmptyShops": false,
  "showClosedShops": false
}

`featured`

"featured": {
  "enabled": false,
  "cost": 1000,
  "durationDays": 7,
  "maxFeaturedSlots": 3,
  "autoFeatureTopRated": false,
  "autoFeatureMinRating": 4.5,
  "autoFeatureMinSales": 50
}

When autoFeatureTopRated = true, the plugin promotes shops meeting both autoFeatureMinRating and autoFeatureMinSales automatically.

`rentalStations`

The complete rental-station config. See Rentals for behaviour deep-dive.

"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
}

Field	Effect
`onEmptyAuction`	What happens after a no-bid auction round AND after a rental ends. `"RESTART"` = new round, `"VACANT"` = idle until admin re-arms, `"DELETE"` = remove slot entirely
`auctionAntiSnipingSeconds`	A bid in the last N seconds extends the auction by that many seconds. 0 disables
`auctionEndingSoonSeconds`	One-shot world chat broadcast when auction has N seconds left. 0 disables
`extendMaxDays`	Max days a renter can extend by in one `/ksshop myrentals` -> EXTEND call
`releaseEarlyGoldRefundFraction`	0.0 = no refund (commitment cost), 1.0 = full refund. Items always go back
`rentalShopsListFree`	Rental-backed shops auto-listed for the rental window without paying the listing fee

`database`

"database": {
  "type": "sqlite",
  "sqlitePath": "shops.db",
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "database": "hytale",
    "username": "root",
    "password": ""
  }
}

Switch type to "mysql" to use the MySQL block. SQLite uses a file at mods/kyuubisoft_shops/shops.db.

`categories`

Shop category list shown in the editor dropdown + browse filter.

"categories": [
  { "id": "weapons",   "displayName": "Weapons",   "icon": "Iron_Sword",          "sortOrder": 1 },
  { "id": "armor",     "displayName": "Armor",     "icon": "Iron_Chestplate",     "sortOrder": 2 },
  { "id": "tools",     "displayName": "Tools",     "icon": "Iron_Pickaxe",        "sortOrder": 3 },
  { "id": "resources", "displayName": "Resources", "icon": "Ingredient_Bar_Gold", "sortOrder": 4 },
  { "id": "potions",   "displayName": "Potions",   "icon": "Potion_Health",       "sortOrder": 5 },
  { "id": "food",      "displayName": "Food",      "icon": "Apple",               "sortOrder": 6 },
  { "id": "building",  "displayName": "Building",  "icon": "Stone_Brick",         "sortOrder": 7 },
  { "id": "misc",      "displayName": "Misc",      "icon": "Emerald",             "sortOrder": 8 }
]

You can add custom categories - any id here becomes selectable in the editor + a filter chip in browse.

`itemBlacklist`

"itemBlacklist": []

Items in this list cannot be added to any shop. Modified live via /kssa blacklist add <itemId> / remove <itemId> / list - changes persist to this file.