# Getting Started

**Version:** 2.6.6

## 1. Install the plugin

1. Stop the server.
2. Put `KyuubiSoftBank-2.6.6.jar` into the server's `mods/` folder. When you update, remove the old `KyuubiSoftBank-*.jar` first.
3. Recommended: **KyuubiSoft Core**. The bank and its commands work without it, but bank NPCs, the economy and config updates need Core (see [Requirements](https://wiki.kyuubisoft.com/hytale/bank/#requirements)).
4. Optional: VaultUnlocked with an economy plugin (Account tab and paid pages), EcotaleCoins (coin values), LuckPerms (rank pages).
5. Start the server.

```
mods/
  KyuubiSoftBank-2.6.6.jar
  KyuubiSoftCore-<version>.jar
```

---

## 2. Files after the first start

```
mods/
  kyuubisoft_bank/
    config.json            main configuration
    bank.db                SQLite database with the bank history
    localization/          en-US.json, de-DE.json, es-ES.json, fr-FR.json, it-IT.json,
                           pl-PL.json, pt-BR.json, ru-RU.json, tr-TR.json
    players/
      <uuid>.json          bank contents of one player (created at the first join)
      <uuid>.json.bak      previous version, written before every save
      <uuid>.json.unreadable-<time>   only when a bank file could not be read: a copy of it
    worlds/
      <group>/players/<uuid>.json   only with world banking: one bank per world group
  kslang/                  language choice shared by all KyuubiSoft mods
```

With KyuubiSoft Core installed, the first `config.json` is written from the plugin's built-in defaults (see [Configuration](./configuration#the-default-file)). On later starts Core adds fields that are new in an update and keeps your values.

Without Core the first start writes the same defaults from a commented copy in the jar (`_..._info` lines explain the sections). Later updates do not add new fields to the file then; fields that are missing use their defaults. If `config.json` cannot be read, see [Configuration](./configuration#validation).

---

## 3. Check the console

A healthy start prints lines like these:

```
[KyuubiSoft Bank] Setting up Bank System...
[KyuubiSoft Bank] Config loaded: 5 max pages, 45 slots/page, 0 coin types, blacklist mode with 0 items
[KyuubiSoft Bank] Loaded language: en-US (274 keys)
[KyuubiSoft Bank] [Bank] Database initialized: mods\kyuubisoft_bank\bank.db
[KyuubiSoft Bank] Bank System ready.
```

The warning `Skipping pack at kyuubisoft_bank: missing or invalid manifest.json` is harmless: Hytale checks every folder in `mods/` for an asset pack, and the data folder is none.

"coin types" only counts the legacy `coinItems` map; coins in `coinProviders` and auto-detected EcotaleCoins are not included in that number.

---

## 4. Basic configuration

Open `mods/kyuubisoft_bank/config.json` or use the [admin panel](./admin-panel) (`/ksbank admin`). The defaults:

| Setting | Default | Meaning |
|---------|---------|---------|
| `defaultPages` | `1` | Pages every new player starts with. `0` = no page; the player unlocks the first one |
| `maxPages` | `5` | Pages a player can buy when no rank pages are set; also the limit for admin grants |
| `slotsPerPage` | `45` | Slots per page (9 per row). Best decided before players use the bank, see the note below |
| `upgrade.defaultCosts` | `[0, 250, 500, 1000, 2500]` | Price of page 1, 2, 3, ... (index 0 = page 1). Pages without a price cannot be bought |
| `permissions.rankPages` | `{}` | Permission node to max buyable pages. Empty = everyone can buy up to `maxPages` |
| `restrictionMode` / `restrictedItems` | `blacklist` / `[]` | Items that must not go into the bank |

With the defaults a new player owns page 1 and can buy pages 2 to 5 for 250, 500, 1000 and 2500.

:::note
`slotsPerPage` can be changed later without losing items: saved pages are fitted the next time a bank opens. After a decrease, items from cut-off slots move to free slots, and items without a free slot wait in the player's file until there is room (the player gets a chat message). See [Configuration](./configuration#slotsperpage).
:::

After editing the file, reload it without a restart:

```
/ksbank reload
```

---

## 5. Set up a bank NPC

Bank NPCs are citizens of KyuubiSoft Core.

1. Create a citizen with the Core citizen tools (see [Citizens](https://wiki.kyuubisoft.com/hytale/citizens/)).
2. In the citizen editor set **BANK** to **Yes**, or set `"bankingEnabled": true` for the citizen in Core's `citizens.json`.
3. A player who interacts with the citizen gets their own bank window.

Every bank NPC opens the bank of the interacting player, so you can place as many as you like. With world banking on, the bank of the world group the player stands in is opened.

---

## 6. Economy (optional)

The **Account** tab and paid pages need an economy:

1. Install KyuubiSoft Core, VaultUnlocked and an economy plugin that registers with it (for example Ecotale). The bank reaches the economy through Core.
2. Restart and open `/ksbank admin`. The **General** section shows the active **Economy Provider**; "Not available" means Core found no economy.
3. For coin deposits and payouts, the coin items need values. EcotaleCoins are detected automatically (provider `Ecotale`); for other coins add them in the **Coins** section. The provider name of a coin list must match the economy provider name.

Without an economy the bank still works as storage: the Account tab is hidden and every page is unlocked for free.

:::tip[From 2.7.0 (not released yet): the server currency Kronen]
Bank 2.7.0 brings KyuubiSoft's own server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) ("Crowns" in English), with or without KyuubiSoft Core and without any other plugin. It is off by default. To use it, open the Kronen admin window (`/kskronenadmin`, the **Crowns** button in `/ksbank admin` while the bank carries the currency, or the **Crowns** tile in `/ksadmin` with Core 2.10.0) and switch it on in its **Settings** area. From then on the Account tab shows the balance and transfers, and pages cost the prices of `upgrade.defaultCosts` in Kronen. When another economy is installed, Kronen steps back and the bank uses that economy.
:::

---

## 7. Test it

1. Run `/ksbank open` (or use your bank NPC). The bank window opens. New players start in the **Scroll** view; switch to **Pages** below the vault to see one page at a time.
2. Click an item in your inventory: it moves into the first free slot of the vault (of the shown page in the Pages view). Click it in the vault to take it back.
3. Open the **History** tab: both moves are listed under "Today".
4. Open the **Pages** tab and press **Buy** on page 2. The window is redrawn in place and shows the new page.
5. Close the window with **X** or Escape and open it again; everything is still there.

---

## 8. Admin quick reference

```
/ksbank admin                              admin panel
/ksbank open --player=<name>               open a player's bank
/ksbank give <player> <item> --amount=<n>  put an item into a player's bank
/ksbank adminupgrade <player> --pages=<n>  add pages for free
/ksbank reset <player>                     empty a bank and reset its pages
/ksbank log <player>                       30 newest history entries in chat
/ksbank reload                             reload config.json
```

Admins need `ks.bank.admin`, see [Permissions](./permissions).

---

## Updating from 2.6.0

- Admins only need `ks.bank.admin`; the old `bank.admin` is no longer used. Grant `ks.bank.admin` to everyone who had `bank.admin`.
- Settings that had no effect before now work. Check them in `config.json`: `upgrade.enabled` (`false` stops page purchases), the feature permissions `permissions.upgrade`, `transfer`, `withdraw` and `deposit` (a node set there now locks the feature), and `historyMaxEntries` (players now see only their newest 100 entries by default; `0` = no limit).
- Restriction patterns with `*` now match and matching ignores case, so `restrictedItems` may block more than before. Items already in a bank stay there and can be taken out.
- Rank pages without LuckPerms now use Hytale's own permission system. Before, every player got the highest rank value.
- The language files in `localization/` are replaced by version 15 on the first start (also when you update from 2.6.1 to 2.6.3); your old files are kept as `<lang>.json.backup-v<old>`.
- Servers without Core that still have the unedited `config.json` written by 2.6.0 (a template with a text note inside the `Ecotale` coin list) get it replaced on the first start: the old file is kept as `config.json.old-template-<time>`, the current default file is written, and the bank runs with the same built-in values as before. An edited copy of that file is left alone; it is logged as unreadable (SEVERE) and the bank runs on its built-in defaults until you fix it.

---

## Next steps

- [Commands](./commands) for the full syntax
- [Configuration](./configuration) for every field
- [UI Pages](./ui-pages) for what players see