Configuration
Version: 2.6.6
The bank is configured in mods/kyuubisoft_bank/config.json. Most fields can also be changed in game in the admin panel, which writes the same file. After editing the file by hand, run /ksbank reload (or press Reload in the admin panel).
The default file
Section titled “The default file”With KyuubiSoft Core installed, the first start writes this file from the plugin’s built-in defaults. On every later start and reload, Core adds fields that are missing (for example after an update) and keeps your values.
{ "defaultPages": 1, "maxPages": 5, "slotsPerPage": 45, "pageCosts": [0, 250, 500, 1000, 2500], "currency": "gold", "restrictionMode": "blacklist", "restrictedItems": [], "historyMaxEntries": 100, "upgrade": { "enabled": true, "provider": "", "defaultCurrencyName": "Gold", "providerCosts": {}, "providerDisplayNames": {}, "defaultCosts": [0, 250, 500, 1000, 2500] }, "permissions": { "upgrade": { "permission": "", "lockedMessage": "Unlock bank upgrades at VIP rank!" }, "transfer": { "permission": "", "lockedMessage": "" }, "withdraw": { "permission": "", "lockedMessage": "" }, "deposit": { "permission": "", "lockedMessage": "" }, "rankPages": {} }, "coinProviders": {}, "shopInfo": { "enabled": false, "buttonText": "Want more pages?", "chatMessage": "Visit our shop for more bank pages!", "link": "" }, "worldBanking": { "enabled": false, "separateWorlds": {} }, "coinItems": {}}defaultPages
Section titled “defaultPages”| Type | Default | Minimum |
|---|---|---|
| Integer | 1 | 0 |
Pages a player owns when their bank is created. With 0, a new bank has no page: the vault shows a lock and the player unlocks the first page in the Pages tab (page 1 costs defaultCosts[0], 0 = free). Also the page count after /ksbank reset.
maxPages
Section titled “maxPages”| Type | Default | Minimum |
|---|---|---|
| Integer | 5 | 1, and at least defaultPages |
- Without rank pages: the number of pages a player can buy up to.
- Always: the limit for admin grants (
/ksbank adminupgrade, + Add Page). - The Pages tab lists
maxPagesrows, or more when the player’s rank or page count is higher (at most 50).
slotsPerPage
Section titled “slotsPerPage”| Type | Default | Minimum |
|---|---|---|
| Integer | 45 | 1 |
Slots per page. The vault grid has 9 slots per row, so multiples of 9 fill whole rows.
Changing the value on a running server keeps every item. Saved pages are fitted to the new slot count the next time a bank opens (or gets an item through /ksbank give or the API):
- Raised: the pages grow; every item keeps its slot.
- Lowered: items from the cut-off slots move to the first free slots of the player’s pages. Items without a free slot wait in the player’s file (
overflow) and come back as soon as there is room. While items wait, the player gets “N item(s) did not fit into your bank after its size changed. Free up slots and open the bank again to get them back.” and the log names the bank.
Open bank windows keep their old layout until they are closed.
Page prices: upgrade
Section titled “Page prices: upgrade”| Field | Type | Default | Used for |
|---|---|---|---|
defaultCosts | Integer list | [0, 250, 500, 1000, 2500] | Price of each page. Index 0 = page 1, index 1 = page 2, … A page beyond the end of the list has no price and cannot be bought (“Not for sale”); admins can still grant it |
defaultCurrencyName | String | "Gold" (2.7.0: "") | Currency word in the price label when no economy provider is selected. From 2.7.0 (not released yet) the default is empty: the bank then shows the name of the server currency Kronen or the name the economy reports. A name of your own still wins; the old default "Gold" counts as empty |
providerCosts | Map provider to integer list | {} | A separate price list per economy provider. Adds the “Pay with” choice to the Pages tab |
providerDisplayNames | Map provider to string | {} | Currency word for a provider, for example "Ecotale": "Ecotale Coins": shown under the balance in the Account tab and in the page prices |
enabled | Boolean | true | false = players cannot buy pages: the Pages tab has no Buy button (pages within the player’s limit read “Not for sale”) and /ksbank upgrade answers “Bank pages cannot be bought on this server.” Admins still grant pages |
provider | String | "" | Not used |
With the default list a player who owns page 1 pays 250 for page 2, 500 for page 3, 1000 for page 4 and 2500 for page 5. defaultCosts[0] only matters for banks that start without a page.
Which list and which money:
- In the Pages tab the price list follows the selected economy provider: the currency of the Account tab, or the “Pay with” choice when
providerCostsis not empty. A provider without its own list usesdefaultCosts. “Default” in “Pay with” meansdefaultCosts, paid with the default economy. /ksbank upgradealways usesdefaultCostsand the default economy.- A price of
0is free. Without an economy every page is free, whatever the list says.
The currency word under the balance and in page prices of a provider is, in this order: the provider’s entry in providerDisplayNames, the currency name the economy reports (for example VaultUnlocked’s plural currency name), and only as a last resort the provider name.
To stop page purchases, set enabled to false. To sell pages only to some players, use permissions.upgrade or rank pages.
"upgrade": { "defaultCurrencyName": "Gold", "defaultCosts": [0, 250, 500, 1000, 2500], "providerCosts": { "Ecotale": [0, 500, 1000, 2000, 5000] }, "providerDisplayNames": { "Ecotale": "Ecotale Coins" }}permissions
Section titled “permissions”| Field | Type | Default | Used for |
|---|---|---|---|
rankPages | Map permission to integer | {} | Pages a player may own through purchases, per permission node; highest match wins |
upgrade | { "permission", "lockedMessage" } | permission "", message "Unlock bank upgrades at VIP rank!" | Buying pages (Pages tab and /ksbank upgrade) |
transfer | { "permission", "lockedMessage" } | both "" | Sending money (Account tab) |
withdraw | { "permission", "lockedMessage" } | both "" | Withdrawing balance as coins |
deposit | { "permission", "lockedMessage" } | both "" | Turning coins into balance: Deposit all coins and dropping a coin onto the vault |
Feature permissions (upgrade, transfer, withdraw, deposit):
- An empty
permission(the default) allows everyone. - With a node set, a player without that node cannot use the feature. They see the
lockedMessage, or when it is empty “You are not allowed to buy bank pages.” (pages, in chat) or “You are not allowed to do this” (Account tab, in the status line). - Without
deposit, a coin dropped onto the vault is stored as a normal item. - Storing and taking items is never affected.
- The nodes are checked through LuckPerms when it is installed, otherwise through Hytale’s own permission system, the same way as rank pages.
How rank pages are resolved is explained on Permissions.
"permissions": { "upgrade": { "permission": "bank.vip", "lockedMessage": "Unlock bank upgrades at VIP rank!" }, "transfer": { "permission": "", "lockedMessage": "" }, "withdraw": { "permission": "", "lockedMessage": "" }, "deposit": { "permission": "", "lockedMessage": "" }, "rankPages": { "bank.pages.3": 3, "bank.pages.5": 5, "bank.pages.10": 10 }}Coins: coinProviders and coinItems
Section titled “Coins: coinProviders and coinItems”Coin items turn into balance when they are deposited (dragged onto the vault or “Deposit all coins”) and are paid out by “Withdraw as coins”. Both need an economy.
coinProviders
Section titled “coinProviders”| Type | Default |
|---|---|
| Map provider to (map item ID to value) | {} |
"coinProviders": { "Ecotale": { "Coin_Copper": 1, "Coin_Gold": 1000 }, "MyEconomy": { "MyMod_Token": 500 }}- The outer key must be the economy provider name as VaultUnlocked reports it. The Account tab looks up the coins of the selected currency by this name; if there is no entry, it falls back to
coinItems. The active provider name is shown as “Economy Provider” in the General section of the admin panel. - The value is the amount of money one coin is worth.
Ecotaleis managed automatically. On every start and reload the bank reads the enabled coins and their values from EcotaleCoins and replaces the wholeEcotalelist with them. Coins disabled in EcotaleCoins disappear, changed values are taken over. If EcotaleCoins is not installed, theEcotalelist is emptied. Do not put your own coins underEcotale.
coinItems (legacy)
Section titled “coinItems (legacy)”| Type | Default |
|---|---|
| Map item ID to value | {} |
A flat coin list from older versions. It is used for a currency that has no entry in coinProviders, and appears as “Default” in the Coins section of the admin panel. On load, the six old built-in entries (Coin_Copper 1, Coin_Iron 10, Coin_Cobalt 100, Coin_Gold 1000, Coin_Adamantite 10000, Coin_Mithril 100000) are removed when they still have exactly these values; changed values are kept. New setups should use coinProviders.
shopInfo
Section titled “shopInfo”The optional button at the bottom of the Pages tab.
| Field | Type | Default | Meaning |
|---|---|---|---|
enabled | Boolean | false | Show the button |
buttonText | String | "Want more pages?" | Button label; empty uses the translated “Want more pages?” |
chatMessage | String | "Visit our shop for more bank pages!" | Text sent to the player’s chat on click |
link | String | "" | Clickable link added after the message. Empty = message only |
With a link the chat line reads >>> Visit our shop for more bank pages! https://... and the link can be clicked.
"shopInfo": { "enabled": true, "buttonText": "Want more pages?", "chatMessage": "Visit our shop for more bank pages!", "link": "https://store.example.com/bank"}worldBanking
Section titled “worldBanking”| Field | Type | Default | Meaning |
|---|---|---|---|
enabled | Boolean | false | Use separate banks per world group |
separateWorlds | Map group to list of strings | {} | Group name and the world name parts that belong to it |
"worldBanking": { "enabled": true, "separateWorlds": { "pvp": ["arena", "battleground"], "creative": ["creative"] }}- A world belongs to a group when its name contains one of the group’s entries, ignoring upper and lower case.
arenamatchesPvP_Arena_Kx8hs9d. The first matching group wins. - Worlds that match no group use the normal bank, so existing banks stay where they are.
- Each group has its own pages, contents, page count and view settings, stored in
worlds/<group>/players/<uuid>.json. Use group names that are valid folder names. - A player gets a new, empty group bank with
defaultPagespages the first time they open the bank in that group’s worlds. - The history is shared: the History tab lists the entries of all groups.
/ksbank upgradeand admin commands with a UUID always act on the normal bank.- Switching world banking off shows everyone their normal bank again; the group files stay on disk.
restrictionMode and restrictedItems
Section titled “restrictionMode and restrictedItems”| Field | Type | Default | Options |
|---|---|---|---|
restrictionMode | String | "blacklist" | "blacklist": listed items are refused. "whitelist": only listed items are allowed |
restrictedItems | String list | [] | Item IDs |
"restrictionMode": "blacklist","restrictedItems": ["Quest_Item_Key", "Lootbag_Common"]- An empty list allows everything, in both modes.
- Entries are full item IDs or patterns with
*, which stands for any run of characters:Quest_*,*_Key,Ore_*_Raw. Every other character is literal. Upper and lower case do not matter. - The list is checked for every way into the bank: clicking an item in the inventory, drag and drop (both directions of a swap) and the game’s own container moves. A refused item stays in the inventory and the status line says “This item cannot be stored in the bank”.
- The mode can only be changed in this file; the admin panel shows it and edits the list.
On a server that runs KyuubiSoft Core’s showcase mode, visitors also cannot store the showcase’s test items, whatever this list says: pet eggs (Pet_Egg_*), battle items (Battle_*), mount horns (Mount_Horn_*), lootbags (*_Lootbag*), pet scrolls (Pet_*_Scroll), dungeon maps (KS_Dungeon_Map_*) and map stones (KS_Map_Stone_*). They get the usual “This item cannot be stored in the bank”. A normal server is not affected.
History: historyMaxEntries
Section titled “History: historyMaxEntries”| Type | Default |
|---|---|
| Integer | 100 |
How many history entries a player sees: their newest historyMaxEntries entries, in the History tab (count, pages, search) and in /ksbank history. 0 = no limit.
The database keeps every entry; nothing is deleted. The History section of the admin panel lists all of them, and /ksbank log (30 newest) is not limited by this value either.
Unused fields
Section titled “Unused fields”pageCosts, currency and upgrade.provider are read and written but have no effect. Prices come from upgrade.defaultCosts and upgrade.providerCosts.
Validation
Section titled “Validation”Invalid values are corrected when the file is loaded:
| Field | Correction |
|---|---|
defaultPages below 0 | 0 |
maxPages below 1 | 5 |
maxPages below defaultPages | set to defaultPages |
slotsPerPage below 1 | 45 |
historyMaxEntries below 0 | 100 |
restrictionMode missing | "blacklist" |
restrictedItems, coinItems, coinProviders missing | empty |
upgrade missing | defaults |
upgrade.defaultCosts missing | [0, 250, 500, 1000, 2500] |
upgrade.defaultCurrencyName missing | "Gold" (2.7.0: "") |
upgrade.providerCosts, upgrade.providerDisplayNames missing | empty |
permissions, shopInfo, worldBanking missing | defaults |
A file that cannot be read (broken JSON, a text where a number is expected) is never changed, with or without Core:
- The log shows a SEVERE line with the reason:
config.json cannot be read (...). Using the built-in defaults. The file was not changed: fix it and run /ksbank reload. - At server start the bank runs on its built-in defaults. On a reload it keeps the settings it had loaded before.
/ksbank reloadanswers “Error loading config: …” with the reason.- If you save something in the admin panel while the file is unreadable, the panel writes the current settings to
config.jsonand keeps the old file asconfig.json.unreadable-<time>(<time>= its last change in milliseconds).
Reload
Section titled “Reload”/ksbank reload and the Reload button of the admin panel:
- read
config.jsonagain (with Core: merge new default fields first), - recompile the restriction list,
- rebuild the
Ecotalecoin list from EcotaleCoins.
When config.json cannot be read, the reload changes nothing (see Validation). /ksbank reload and the Reload button of the admin panel then answer “Error loading config: …” with the reason.
Language files are not reloaded; restart the server for edited translations. Open bank windows keep their slot layout until they are closed.
Language files
Section titled “Language files”mods/kyuubisoft_bank/localization/ holds one file per language: en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR.
- Each player sees the language chosen with
/kslang, otherwise the client language. Missing keys fall back toen-US. - The files carry
"_localization_version"(15 in 2.6.6, 17 in 2.7.0). When an update brings a newer version, every older file is renamed to<lang>.json.backup-v<old>and replaced. Copy your own edits from the backup into the new file. - Texts in
config.json(shop button, chat message) are not translated. - The names and descriptions of the bank’s own items (
Bank_Prev,Bank_Next,Bank_Page,Bank_History) are inside the jar inServer/Languages/<lang>/bank.lang(keysbank.Bank_History.name, …), in all 9 languages.
Data files
Section titled “Data files”| Path | Content |
|---|---|
players/<uuid>.json | One player’s bank: pages, page count, sort and view setting. Format on API Reference |
players/<uuid>.json.bak | The previous version, copied before every save |
players/<uuid>.json.unreadable-<time> | A copy of a bank file that could not be read (see below) |
config.json.unreadable-<time> | An unreadable config.json, kept when the admin panel saved over it (see Validation) |
worlds/<group>/players/<uuid>.json | World group banks |
bank.db | SQLite history of all players (table bank_transactions) |
../kslang/prefs.json | Language choices of all players (shared by all KyuubiSoft mods) |
A bank file is written when the window closes (X, Escape, logout), every 60 seconds while the window is open, when the server stops, and after every admin change. Stop the server before you edit a bank file by hand.
Damaged files and pages
- Unreadable bank file: when
players/<uuid>.jsoncannot be loaded (for example after a manual edit with a JSON error), the player gets a new, empty bank. The old file is first copied to<uuid>.json.unreadable-<time>(<time>= its last change in milliseconds), and the log says so. Fix that copy and put it back while the server is stopped. - Unreadable page: a page whose saved data cannot be decoded is never overwritten. Its slots are locked in the window (nothing can be put there), the log names the page, and the player gets “Page N of your bank could not be read. It stays locked and its items are kept - please tell an admin.”
/ksbank giveand the API skip such a page. - Items of removed mods: stacks whose item ID no longer exists are hidden in the window (the client cannot show them) but stay stored in their slot. The player gets “N item(s) from removed mods are kept in your bank but cannot be shown.” Once the mod is back, they show up again.