# 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](./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

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.

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

:::note
Without Core the first start writes a commented copy from the jar (`defaults/config.json`) instead. It holds exactly these values plus `_..._info` lines that explain the sections; the notes only stand outside the lists, so the file loads as it is. Without Core, later updates do not add new fields to the file; missing fields use their defaults.
:::

---

## Pages

### `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`

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

### `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`

| 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](https://wiki.kyuubisoft.com/hytale/core/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 `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](./permissions#rank-pages).

:::note[From 2.7.0 (not released yet): prices in Kronen]
While the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) is on, `defaultCosts` are paid in Kronen and shown as "250 Crowns" (with the default list: 250 / 500 / 1000 / 2500 for pages 2 to 5). Change `defaultCosts` if you want other prices before you switch Kronen on. Kronen has its own settings file, `mods/kyuubisoft_kronen/config.json`; nothing about the currency is set in the bank's `config.json`.
:::

```json
"upgrade": {
  "defaultCurrencyName": "Gold",
  "defaultCosts": [0, 250, 500, 1000, 2500],
  "providerCosts": {
    "Ecotale": [0, 500, 1000, 2000, 5000]
  },
  "providerDisplayNames": {
    "Ecotale": "Ecotale Coins"
  }
}
```

---

## `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#rank-pages).

```json
"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`

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`

| Type | Default |
|------|---------|
| Map provider to (map item ID to value) | `{}` |

```json
"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`.

### `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`

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.

```json
"shopInfo": {
  "enabled": true,
  "buttonText": "Want more pages?",
  "chatMessage": "Visit our shop for more bank pages!",
  "link": "https://store.example.com/bank"
}
```

---

## `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 |

```json
"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.

---

## `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 |

```json
"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.

:::note
Items that are already in a bank when you add a matching entry stay there and can still be taken out. Moving them inside the vault by dragging may be refused by the game.
:::

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`

| 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

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

---

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

---

## Reload

`/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](#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

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

---

## Data files

| Path | Content |
|------|---------|
| `players/<uuid>.json` | One player's bank: pages, page count, sort and view setting. Format on [API Reference](./api-reference#player-bank-file) |
| `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](#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>.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.