# Bank

**KyuubiSoft Bank gives every player a personal vault that keeps items across sessions. Players open it at a bank NPC or with a command, buy more pages, search and sort what they stored and see every deposit and withdrawal. On servers with an economy the same window also holds the player's account: coins in and out, and money transfers to other players.**

---

## Coming with 2.7.0: Kronen

:::caution[Not released yet]
Bank 2.7.0 is not released yet and has not been tested in game. The rest of this wiki describes the released version 2.6.6 unless a section says 2.7.0.
:::

- **A server currency without KyuubiSoft Core.** The bank can carry [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/), KyuubiSoft's own server currency ("Crowns" in English), when Core is not installed: balances, `/kskronen`, `/kskronen pay`, `/kskronen history` and the Kronen admin window work with the bank alone. With Core 2.10.0 installed, Core carries the currency and the bank shows it. Both use the data folder `mods/kyuubisoft_kronen/`, so nothing is lost when Core is added or removed. Kronen is **off by default**; while it is off the bank behaves as before and writes nothing for it (the folder `mods/kyuubisoft_kronen/` does not exist until Kronen is switched on).
- **New account tab:** the balance with the coin, the last four bookings with where they came from, and a transfer with person, amount, reason and a confirmation line. See [UI Pages](./ui-pages#the-account-tab-from-270).
- **Transfers to people who are offline, with a reason**, with every economy. Both people get a history entry. Only an exact name is paid; with several offline people of the same name the right one has to be online. With Kronen, one transfer per second per person.
- **Reasons in your language:** bookings in the account tab and the history show where they came from and why in the reader's language ("Claims" · "2 chunks bought", "Bank" · "Page 3 unlocked").
- **History filter "Crowns"** and **page prices in the server currency** ("250 Crowns").
- **Admins:** a **Crowns** button in `/ksbank admin` opens the Kronen admin window while the bank carries the currency.
- **Fixes:** switched-off economies are no longer offered, and prices no longer show a fixed "Gold" (`upgrade.defaultCurrencyName` is empty by default).

---

## How the bank works

- Every player has their own bank. It has one or more **pages** with 45 slots each (9 per row, configurable). New players start with `defaultPages` pages (1 by default).
- Players open the bank at a **bank NPC** (a KyuubiSoft Core citizen with banking switched on), with `/ksbank open` or with `/ksbank page <number>`.
- The **bank window** shows the vault, the player's inventory and a side panel with the tabs **Account**, **History** and **Pages**. Items move with a click or by drag and drop.
- More pages are bought in the **Pages** tab or with `/ksbank upgrade`. The price of each page comes from `config.json`; rank pages can limit how many pages a player may buy.
- The bank contents are stored per player in `players/<uuid>.json`. Item deposits and withdrawals, coin deposits and money transfers are written to the SQLite database `bank.db`.
- A bank can only be open once at a time. The window saves when it closes and every 60 seconds while it stays open.

---

## Features

### The bank window

- One window in the KyuubiSoft "Goldfiligran" look: the vault on the left, the side panel on the right, a "Used" meter in the header.
- **Search** dims every item whose ID or name (in the player's game language or `/kslang` language) does not match. **Sort** by name, rarity or amount (click again to switch sorting off). Sorting only changes the display; the items stay in their slots.
- **Pages view** shows one page at a time with a pager (one diamond per page); **Scroll view** shows all pages in one scrolling grid. Both settings are saved per player.
- Every item shows a rarity ring (common to legendary) instead of the vanilla quality background, in the vault, the storage and the hotbar.
- **Click** moves a whole stack between vault and inventory; **drag and drop** swaps two slots between any of the three grids.

### Pages

- The **Pages** tab lists every page the player owns or could get: owned, the next page with a **Buy** button, later pages, pages that need a higher rank and pages without a price.
- Prices per page: `upgrade.defaultCosts`, or one price list per economy provider (`upgrade.providerCosts`) with a "Pay with" choice.
- **Rank pages** (`permissions.rankPages`): a permission node grants a maximum number of buyable pages; the highest match wins.
- Page sales can be switched off (`upgrade.enabled`) or limited to a permission node (`permissions.upgrade`); admins can always grant pages.
- An optional **shop info button** ("Want more pages?") sends a chat message with a clickable link, for example to your web shop.
- A server can start players with **no page at all** (`defaultPages: 0`): the vault then shows a lock and the player unlocks the first page in the Pages tab.

### Economy account

- Needs KyuubiSoft Core and an economy that registers with **VaultUnlocked** (for example Ecotale). Without an economy the Account tab is hidden. From 2.7.0 (not released yet) the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) also counts, with or without Core.
- Shows the balance, with a currency dropdown when more than one economy provider is registered.
- **Deposit coins:** drag coin items onto the vault or press "Deposit all coins"; their value is credited to the balance.
- **Withdraw as coins:** pays an amount out as coin items, either the best mix ("Auto (optimal)") or one chosen coin first. A remainder below the smallest coin stays in the account.
- **Transfer** money to another online player. From 2.7.0 (not released yet) also to players who are offline, with an optional reason.
- Transfers, payouts as coins and coin deposits can each be limited to a permission node (`permissions` in `config.json`).
- Coin values come from `coinProviders` in `config.json`; EcotaleCoins are detected automatically.

### History

- The **History** tab lists the player's bank history: 10 entries per page, grouped by day (Today, Yesterday, date), with item icon, rarity ring, item name and a green (in) or red (out) amount.
- Search field and filter pills **All / Deposited / Withdrawn**.
- Players see their newest `historyMaxEntries` entries (100 by default); `/ksbank history` prints the 20 newest in chat. Admins see the full history of an online player in the admin panel, and of any player with `/ksbank log`.

### Item restrictions

- A **blacklist** (default) blocks the listed item IDs, a **whitelist** only allows them. Patterns with `*` (`Quest_*`, `*_Key`) work; upper and lower case do not matter.
- Clicks, drag and drop and the game's own container moves into the bank are all checked. See [Configuration](./configuration#restrictionmode-and-restricteditems).

### World banking

- Optional separate banks per **world group**. A group lists parts of world names; a world whose name contains one of them uses that group's bank. All other worlds share the normal bank.
- Each group has its own pages and contents (`worlds/<group>/players/<uuid>.json`).

### Bank NPCs

- Any KyuubiSoft Core citizen with **Bank: Yes** (`bankingEnabled`) opens the bank when a player interacts with it. See [Getting Started](./getting-started#5-set-up-a-bank-npc).

### Admin panel

- `/ksbank admin` opens one window with eight sections: **General, Economy, Ranks, Coins, Restrict** (configuration) and **Players, History, Worlds** (management).
- Change page counts and prices, rank pages, coins, restrictions and world groups without editing files; look up an online player's bank, open it, add or remove pages, reset it and read their history.
- Admins can also open any bank with `/ksbank open --player=<name>`; the owner's money, pages and settings cannot be changed from there.

### Languages

- 9 languages: en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR.
- Each player picks their language with `/kslang` (shared by all KyuubiSoft mods); otherwise the client language is used.

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing the plugin, the files it creates, a bank NPC, a first test |
| [Commands](./commands) | Every player and admin command with syntax |
| [Permissions](./permissions) | Permission nodes, rank pages, LuckPerms examples |
| [Configuration](./configuration) | Every field of `config.json`, data files, languages |
| [UI Pages](./ui-pages) | The bank window: vault, Account, History and Pages tabs |
| [Admin Panel](./admin-panel) | The eight sections of `/ksbank admin` |
| [API Reference](./api-reference) | Events, `addItemOrDrop` and data formats for developers |
| [FAQ & Troubleshooting](./faq) | Common questions, known issues and fixes |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Product** | KyuubiSoft Item Economy Bank ([BuiltByBit](https://builtbybit.com/resources/kyuubisoft-item-economy-bank.98747/)) |
| **Plugin** | KyuubiSoft Bank (manifest `kyuubisoft:bank`) |
| **Version** | 2.6.6 (2026-11-09) |
| **Jar** | `KyuubiSoftBank-2.6.6.jar` |
| **Player commands** | `/ksbank open`, `/ksbank page <page>`, `/ksbank upgrade`, `/ksbank history` (alias `/banker`), `/kslang` |
| **Admin commands** | `/ksbank admin`, `/ksbank open --player=<name>`, `/ksbank give`, `/ksbank adminupgrade`, `/ksbank reset`, `/ksbank log`, `/ksbank reload` |
| **From 2.7.0 (not released yet)** | `/kskronen`, `/kskronen pay`, `/kskronen history`, `/kskronenadmin` while the bank carries [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/); data in `mods/kyuubisoft_kronen/` |
| **Data folder** | `mods/kyuubisoft_bank/` |
| **Config** | `mods/kyuubisoft_bank/config.json` |
| **Bank contents** | `players/<uuid>.json` (backup `<uuid>.json.bak`); world groups in `worlds/<group>/players/<uuid>.json` |
| **History** | `mods/kyuubisoft_bank/bank.db` (SQLite) |
| **Localization** | `mods/kyuubisoft_bank/localization/<lang>.json` (9 languages) |
| **Required** | nothing else (see Requirements) |
| **Optional** | KyuubiSoft Core (bank NPCs, economy, config updates, a tile in the `/ksadmin` hub; recommended), VaultUnlocked with an economy plugin (Account tab, paid pages), EcotaleCoins (coin values), LuckPerms (rank pages) |

---

## Requirements

- Hytale server 0.7.x (built against 0.7.0) and Java 25.
- **KyuubiSoft Core (optional, recommended).** The commands work without Core. Core is needed for bank NPCs (they are Core citizens), for the economy (Core finds it) and for merging new default fields into `config.json` on updates.
- **Economy (optional):** KyuubiSoft Core plus VaultUnlocked and an economy plugin that registers with it. Core finds the economy; the bank uses it for the Account tab and for page prices. Without an economy pages are free to unlock (see [FAQ](./faq#why-can-players-unlock-pages-for-free)).
- **EcotaleCoins (optional):** its enabled coins and values are read on every start and reload.
- **LuckPerms (optional):** rank pages and the feature permissions are checked through LuckPerms when it is installed, otherwise through Hytale's own permission system, see [Permissions](./permissions#rank-pages).
- The SQLite driver and the UI textures are inside the jar.