# Permissions

KyuubiSoft Core ships the `/ksadmin` hub, the NPC system and its admin windows, NPC shops, the KS settings window, the web config editor, the dev-export tools and the shared language system. Admin functions sit under `ks.admin` and `ks.admin.*`; citizens have their own `ks.citizen.*` nodes (see [Citizens Permissions](https://wiki.kyuubisoft.com/hytale/citizens/permissions/)).

The server console may run every command.

## Admin Permissions

| Permission | Default | Description |
|---|---|---|
| `ks.admin` | staff only | `/ksadmin` hub, `/ksadmin reload`, `/ksadmin testsound`, "Back to Core" from other mods' admin windows, the NPC shop editor, the showcase admin NPCs. Also accepted for all NPC admin tools. |
| `ks.admin.cleanup` | staff only | `/ksadmin cleanup nametags` |
| `ks.admin.migrate` | staff only | `/ksadmin migrate-storage ...` (JSON to MySQL and back) |
| `ks.admin.xp` | staff only | `/ksadmin addxp`, `removexp` (LevelingCore XP) |
| `ks.admin.editor` | staff only | `/kseditor`, `/kstrusteditor`, `/ksapplyconfig` (web config editor) |
| `ks.admin.dev` | staff only | `/ksdev` (developer data export) |
| `ks.core.admin.dialog.console` | not granted | Add, change or remove anything that runs as the server console. See [Console Commands](#console-commands). |

:::note[Older nodes that are still checked]
A few commands still check an older node in addition when a player runs them in game:

| Command | Also needs |
|---|---|
| `/ksadmin cleanup nametags`, `migrate-storage`, `addxp`, `removexp` | `kyuubisoft.admin` |
| `/kseditor`, `/kstrusteditor`, `/ksapplyconfig` | `kyuubisoft.editor` |
| `/ksdev` | `dev.admin` |

Grant both nodes to staff who use these commands. `/ksadmin` itself and `/ksadmin reload` no longer check `kyuubisoft.admin`, and `ks.admin.reload` is not used any more.
:::

## Player Permissions

| Permission | Default | Description |
|---|---|---|
| `ks.core.user.settings` | granted | `/kssettings` and the KS settings window. Deny it to hide the window. |
| `ks.itemupdate.user.use` | granted | `/ksitemupdate` and the item update window |
| `ks.core.shop.user.use` | not set | Access to Core's NPC shops (`/ksnpcshop`). When an admin sets it (granted or denied), it decides. |
| `ks.shop.user.use` | granted | Used for NPC shops while `ks.core.shop.user.use` is not set (the rule from before 2.8.0) |
| `ks.citizen.user.repair` | granted | `/kscitizen repair` (Hytale's item repair window for the held item) |

`/kslang` has no permission check.

## Kronen Permissions (2.10.0)

Core 2.10.0 (not released yet) adds the server currency [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/). Its nodes are the same when KyuubiSoft Bank carries the currency instead of Core.

| Permission | Default | Description |
|---|---|---|
| `ks.kronen.user.balance` | granted | `/kskronen` (your balance) and `/kskronen history` |
| `ks.kronen.user.pay` | granted | `/kskronen pay <person> <amount> [reason]` and sending money in the bank's account tab |
| `ks.kronen.admin` | staff only | `/kskronenadmin`, the **Crowns** tile in the `/ksadmin` hub (the hub itself needs `ks.admin`), every action in the Kronen admin window, the status line of `/kskronen` and the chat line about other admins' bookings |

## Command Matrix

### `/ksadmin`

| Subcommand | Permission |
|---|---|
| *(hub)* | `ks.admin` |
| `reload` | `ks.admin` |
| `testsound` | `ks.admin` |
| `cleanup nametags` | `ks.admin.cleanup` (+ `kyuubisoft.admin` in game) |
| `migrate-storage file-to-mysql` | `ks.admin.migrate` (+ `kyuubisoft.admin` in game) |
| `migrate-storage mysql-to-file` | `ks.admin.migrate` (+ `kyuubisoft.admin` in game) |
| `addxp <player> <amount>` | `ks.admin.xp` (+ `kyuubisoft.admin` in game) |
| `removexp <player> <amount>` | `ks.admin.xp` (+ `kyuubisoft.admin` in game) |

The subcommands sit under `/ksadmin`, so give staff `ks.admin` as well.

### Hub tiles

The hub needs `ks.admin`. Most mod tiles also check the mod's own admin node, for example `ks.pet.admin`, `ks.bank.admin`, `ks.lootbag.admin` or `ks.shop.admin`; see each mod's permission page. Core's own tiles:

| Tile | Permission |
|---|---|
| NPCs (NPC management), NPC viewer | `ks.citizen.admin` or `ks.admin` |
| NPC shops (shop editor) | `ks.admin`, checked again on every save |
| Crowns (Kronen admin window, 2.10.0) | `ks.kronen.admin`, checked again on every action |

### Web editor and dev tools

| Command | Permission |
|---|---|
| `/kseditor` | `ks.admin.editor` (+ `kyuubisoft.editor` in game) |
| `/kstrusteditor <code>` | `ks.admin.editor` (+ `kyuubisoft.editor` in game) |
| `/ksapplyconfig <code>` | `ks.admin.editor` + `kyuubisoft.editor` |
| `/ksdev items`, `blocks`, `entities`, `citizens`, `worlds`, `emotes`, `all` | `ks.admin.dev` (+ `dev.admin` in game) |

Alias for `/ksdev`: `/dev`. The web editor commands only exist while `modules.webEditor` is on.

### Player commands

| Command | Permission |
|---|---|
| `/kslang`, `/kslang <code>`, `/kslang auto` | none |
| `/kssettings [mod]` | `ks.core.user.settings` (granted by default) |
| `/ksitemupdate` (alias `/itemupdate`) | `ks.itemupdate.user.use` (granted by default) |
| `/ksnpcshop open <shop>`, `sell <shop>`, `list` | `ks.core.shop.user.use` if set, otherwise `ks.shop.user.use` (granted by default) |
| `/kskronen`, `/kskronen history` (2.10.0) | `ks.kronen.user.balance` (granted by default) |
| `/kskronen pay <person> <amount> [reason]` (2.10.0) | `ks.kronen.user.pay` (granted by default) |
| `/kskronenadmin` (2.10.0) | `ks.kronen.admin` |

Shops with `openVia: "npc"` only open at their NPC, not with the command.

## Console Commands

`ks.core.admin.dialog.console` protects everything that runs a command as the server console. It is not granted to anyone by default, also not to holders of `ks.admin`. Without it, an admin can still see these commands and edit everything else.

The node is needed to:

- add, change, remove, copy or delete **dialog** commands that run as the console (dialog editor);
- add, change or remove **NPC** commands that run as the console (interact commands run as console, death commands, proximity commands), copy or delete an NPC that has them, undo a step that would change them, or `/kscitizen remove` such an NPC;
- change an NPC's permission while it has interact commands that run as console;
- add, change or remove **shop entries** that run as the console, change their permission or the shop's permission while it has them, and copy or delete a shop that has them (shop editor). Prices, names and limits stay editable;
- import NPC or shop files through the **web editor** that add, change or remove console commands. Without the node the current console commands are kept, the rest of the import is applied, and the result and the server log name what was kept. Sessions started from the server console count as having the node;
- go back to a **restore point** on the web editor's Backup page. Going back replaces the files completely and can bring back console commands.

Other KS mods use the same node for their own console command rewards and buttons, for example Season Pass, Achievements, Info Hub and Item Control. Existing console commands keep running.

## Citizens

Citizens use their own nodes. See [Citizens Permissions](https://wiki.kyuubisoft.com/hytale/citizens/permissions/):

- `ks.citizen.admin` (or `ks.admin`) for all `/kscitizen` subcommands and the NPC windows
- `ks.citizen` for the bare `/kscitizen` usage list
- per-NPC interaction permissions that you choose freely in the NPC config

## Showcase Mode

On a server in read-only showcase mode, write actions are blocked even for players with the admin nodes, unless they are listed as real admins. Visitors still see the read-only admin pages.

## LuckPerms Examples

```bash
# Full admin stack
/lp group owner permission set ks.admin true
/lp group owner permission set kyuubisoft.admin true
/lp group owner permission set ks.admin.cleanup true
/lp group owner permission set ks.admin.migrate true
/lp group owner permission set ks.admin.xp true
/lp group owner permission set ks.admin.editor true
/lp group owner permission set kyuubisoft.editor true
/lp group owner permission set ks.admin.dev true
/lp group owner permission set dev.admin true
/lp group owner permission set ks.core.admin.dialog.console true

# NPC builders: NPC windows and /kscitizen, but no console commands
/lp group builder permission set ks.citizen.admin true

# Hide the KS settings window from guests
/lp group guest permission set ks.core.user.settings false
```

## Migration from Older Versions

| Before | Now |
|---|---|
| `/ksadmin` needed `ks.admin` and `kyuubisoft.admin` | `ks.admin` only |
| `/ksadmin reload` needed `ks.admin.reload` | `ks.admin` (`ks.admin.reload` is no longer used) |
| `/kscitizen` needed `ks.citizen`, `ks.citizen.admin` and `citizen.admin` together | `ks.citizen.admin` or `ks.admin`; the old `citizen.admin` still works |
| NPC shops used `/ksshop` and `ks.shop.user.use` | `/ksnpcshop`; `ks.core.shop.user.use` decides when set, otherwise `ks.shop.user.use` |
| Console commands could be edited by any admin | `ks.core.admin.dialog.console` is needed |