# Permissions

**Version:** 2.6.6

KyuubiSoft Bank checks five fixed permission nodes with Hytale's permission system. Rank pages and the feature permissions in `config.json` use nodes you choose yourself. Command syntax is on the [Commands](./commands) page.

---

## Permission nodes

| Permission | Default | Gates |
|------------|---------|-------|
| `ks.bank.user.open` | allowed | `/ksbank open` (your own bank); also needed for `/ksbank open --player=<name>` |
| `ks.bank.user.page` | allowed | `/ksbank page <page>` |
| `ks.bank.user.upgrade` | allowed | `/ksbank upgrade` |
| `ks.bank.user.history` | allowed | `/ksbank history` |
| `ks.bank.admin` | not granted | `/ksbank admin`, `give`, `adminupgrade`, `reset`, `log`, `reload`, `/ksbank open --player=<name>`, every change in the admin panel and the showcase admin citizen |

**How the defaults work:**

- The four `ks.bank.user.*` nodes are checked as "allowed unless set". Every player can use the player commands; to block one, set the node to `false` for a player or group. A blocked player gets "No permission.".
- **`ks.bank.admin` is the only admin node.** Grant it to your staff; a wildcard such as `*` covers it too. Without it, `/ksbank open --player=<name>` answers "No permission!" and the other admin commands cannot be run at all.
- The console may run every console-capable command (`give`, `adminupgrade`, `reset`, `log`, `reload`).
- `/kslang` has no permission.

### Kronen nodes (from 2.7.0, not released yet)

While the bank shows or carries the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/), these nodes apply as well. They are the same as with KyuubiSoft Core.

| Permission | Default | Gates |
|------------|---------|-------|
| `ks.kronen.user.balance` | allowed | `/kskronen`, `/kskronen history` |
| `ks.kronen.user.pay` | allowed | `/kskronen pay` and **Send** in the Account tab while Kronen is the money (in addition to the `transfer` feature permission) |
| `ks.kronen.admin` | not granted | `/kskronenadmin`, the **Crowns** button in `/ksbank admin` and every action in the Kronen admin window |

---

## What the nodes do not cover

- **Bank NPCs.** A citizen with banking switched on opens the bank for every player; `ks.bank.user.open` only gates the command.
- **The bank window.** Storing and taking items, sorting and the history have no permission check. Buying pages, transfers, payouts as coins and coin deposits can be limited with the [feature permissions](#feature-permissions-in-configjson); how many pages a player may buy is controlled by [rank pages](#rank-pages).

### The admin panel and the showcase citizen

- The admin panel is opened with `/ksbank admin` (needs `ks.bank.admin`) or, with KyuubiSoft Core 2.8.0 or newer, with its tile in the `/ksadmin` hub (the hub needs Core's `ks.admin`, the tile `ks.bank.admin`; showcase visitors get the panel read-only). Every action that changes something (saves, resets, page changes, **Open Bank**, reload, world groups) checks `ks.bank.admin` again, in addition to Core's showcase guard.
- A KyuubiSoft Core citizen with the ID `showcase_bankadmin` opens the admin panel only for players with `ks.bank.admin`, or, while Core's showcase mode is on, as a read-only panel for visitors (every change answers "Blocked: Showcase mode"). Everyone else gets a "no permission" message in their own language.
- A citizen with the ID `showcase_bank` opens the normal bank of the interacting player.

---

## Feature permissions in `config.json`

The `permissions` section of `config.json` has four entries, each with a `permission` node and a `lockedMessage`:

| Entry | Locks |
|-------|-------|
| `upgrade` | Buying pages, in the Pages tab and with `/ksbank upgrade` |
| `transfer` | Sending money in the Account tab |
| `withdraw` | Withdrawing balance as coins |
| `deposit` | Turning coins into balance: **Deposit all coins** and dropping a coin onto the vault (the coin is then stored as a normal item) |

- An empty `permission` (the default for all four) allows everyone.
- With a node set, a player without it cannot use the feature and sees the `lockedMessage`, or when it is empty "You are not allowed to buy bank pages." (pages) or "You are not allowed to do this" (Account tab).
- The nodes are checked like rank pages: through LuckPerms when it is installed, otherwise through Hytale's own permission system.

```json
"permissions": {
  "upgrade": { "permission": "bank.vip", "lockedMessage": "Unlock bank upgrades at VIP rank!" }
}
```

Details on [Configuration](./configuration#permissions).

---

## Rank pages

`permissions.rankPages` in `config.json` (or the **Ranks** section of the [admin panel](./admin-panel#ranks)) maps a permission node to the number of pages a player with that node may own through purchases. The node names are free text; `bank.pages.5` is only a convention.

```json
"permissions": {
  "rankPages": {
    "bank.pages.3": 3,
    "bank.pages.5": 5,
    "bank.pages.10": 10
  }
}
```

**How the limit is worked out:**

1. `rankPages` is empty (the default): every player may buy up to `maxPages`.
2. `rankPages` has entries: the player gets the **highest** value of all nodes they have. Players without any matching node get `defaultPages`, so they cannot buy pages.
3. Rank values are **not** capped by `maxPages`: a rank with 10 pages allows 10 even when `maxPages` is 5. Each page still needs a price in the cost list to be buyable.

The Pages tab shows pages above the player's limit as "Higher rank needed".

**Where the nodes are checked:** through the LuckPerms API when LuckPerms is installed. Without LuckPerms (or when the LuckPerms check fails), Hytale's own permission system is asked, and a node counts only when the player really has it.

Admin grants (`/ksbank adminupgrade`, **+ Add Page** in the admin panel) ignore rank pages and stop at `maxPages`.

---

## LuckPerms examples

### Staff gets the admin tools

```
/lp group admin permission set ks.bank.admin true
```

### Rank pages

```
/lp group default permission set bank.pages.3 true
/lp group vip permission set bank.pages.5 true
/lp group premium permission set bank.pages.10 true
```

With the `rankPages` example above, default players can own 3 pages, VIPs 5 and premium players 10 (as long as the cost list has prices for them).

### Take a command away from a group

```
/lp group guest permission set ks.bank.user.upgrade false
/lp group guest permission set ks.bank.user.history false
```

Guests can still buy pages in the Pages tab and see the History tab; only the commands are blocked. To stop page purchases everywhere, use the `upgrade` [feature permission](#feature-permissions-in-configjson).

---

## Permission hierarchy example

```
Admin
  ks.bank.admin
  bank.pages.10

VIP
  bank.pages.5

Default
  bank.pages.3
  (ks.bank.user.* are allowed without setup)
```

## Note for older setups

- Up to 2.6.0 the admin commands also checked the old node `bank.admin`, so admins needed `ks.bank.admin` **and** `bank.admin`, and `/ksbank open --player=<name>` only checked `bank.admin`. Since 2.6.1 only `ks.bank.admin` is used; `bank.admin` can be removed.
- Up to 2.6.0 the feature permissions were not checked and rank pages without LuckPerms counted every node as granted.