Skip to content

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).


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

TypeDefaultMinimum
Integer10

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.

TypeDefaultMinimum
Integer51, 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 maxPages rows, or more when the player’s rank or page count is higher (at most 50).
TypeDefaultMinimum
Integer451

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.


FieldTypeDefaultUsed for
defaultCostsInteger 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
defaultCurrencyNameString"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
providerCostsMap provider to integer list{}A separate price list per economy provider. Adds the “Pay with” choice to the Pages tab
providerDisplayNamesMap 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
enabledBooleantruefalse = 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
providerString""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 providerCosts is not empty. A provider without its own list uses defaultCosts. “Default” in “Pay with” means defaultCosts, paid with the default economy.
  • /ksbank upgrade always uses defaultCosts and the default economy.
  • A price of 0 is 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"
}
}

FieldTypeDefaultUsed for
rankPagesMap 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
}
}

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.

TypeDefault
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.
  • Ecotale is managed automatically. On every start and reload the bank reads the enabled coins and their values from EcotaleCoins and replaces the whole Ecotale list with them. Coins disabled in EcotaleCoins disappear, changed values are taken over. If EcotaleCoins is not installed, the Ecotale list is emptied. Do not put your own coins under Ecotale.
TypeDefault
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.


The optional button at the bottom of the Pages tab.

FieldTypeDefaultMeaning
enabledBooleanfalseShow the button
buttonTextString"Want more pages?"Button label; empty uses the translated “Want more pages?”
chatMessageString"Visit our shop for more bank pages!"Text sent to the player’s chat on click
linkString""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"
}

FieldTypeDefaultMeaning
enabledBooleanfalseUse separate banks per world group
separateWorldsMap 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. arena matches PvP_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 defaultPages pages 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 upgrade and 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.

FieldTypeDefaultOptions
restrictionModeString"blacklist""blacklist": listed items are refused. "whitelist": only listed items are allowed
restrictedItemsString 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.


TypeDefault
Integer100

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.

pageCosts, currency and upgrade.provider are read and written but have no effect. Prices come from upgrade.defaultCosts and upgrade.providerCosts.


Invalid values are corrected when the file is loaded:

FieldCorrection
defaultPages below 00
maxPages below 15
maxPages below defaultPagesset to defaultPages
slotsPerPage below 145
historyMaxEntries below 0100
restrictionMode missing"blacklist"
restrictedItems, coinItems, coinProviders missingempty
upgrade missingdefaults
upgrade.defaultCosts missing[0, 250, 500, 1000, 2500]
upgrade.defaultCurrencyName missing"Gold" (2.7.0: "")
upgrade.providerCosts, upgrade.providerDisplayNames missingempty
permissions, shopInfo, worldBanking missingdefaults

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 reload answers “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.json and keeps the old file as config.json.unreadable-<time> (<time> = its last change in milliseconds).

/ksbank reload and the Reload button of the admin panel:

  • read config.json again (with Core: merge new default fields first),
  • recompile the restriction list,
  • rebuild the Ecotale coin 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.


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 to en-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 in Server/Languages/<lang>/bank.lang (keys bank.Bank_History.name, …), in all 9 languages.

PathContent
players/<uuid>.jsonOne player’s bank: pages, page count, sort and view setting. Format on API Reference
players/<uuid>.json.bakThe 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>.jsonWorld group banks
bank.dbSQLite history of all players (table bank_transactions)
../kslang/prefs.jsonLanguage 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>.json cannot 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 give and 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.