# Permissions

Citizens are part of Core. Since Core 2.9.2 one rule covers `/kscitizen` and every NPC window: **`ks.citizen.admin` or `ks.admin`**. Per-NPC interaction permissions are strings you choose freely.

## Permission Nodes

| Permission | Default | Description |
|---|---|---|
| `ks.citizen.admin` | staff only | All `/kscitizen` admin subcommands, NPC management, skin editor, NPC viewer and dialog editor |
| `ks.admin` | staff only | Accepted everywhere `ks.citizen.admin` is |
| `citizen.admin` | -- | Old node, still accepted the same way so no server loses access |
| `ks.citizen` | -- | Only the bare `/kscitizen` (usage list) |
| `ks.citizen.user.repair` | granted | `/kscitizen repair`: opens Hytale's item repair window for the held item |
| `ks.core.admin.dialog.console` | not granted | Needed in addition for anything that runs as the server console, see below |

The rule is checked when a subcommand runs, so subcommands also show up in help and tab completion for players without the node; they cannot run them. Wildcards follow Hytale's rules (`ks.*`, `ks.citizen.*`). The server console may run everything.

## Command Permission Matrix

| Command | Permission |
|---|---|
| `/kscitizen` (usage list) | `ks.citizen` |
| `/kscitizen list [group]` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen create <id>` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen remove <id>` | `ks.citizen.admin` or `ks.admin`; + `ks.core.admin.dialog.console` if the NPC has console commands |
| `/kscitizen tp <id>` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen respawn <id>` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen respawnall` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen reload` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen info <id>` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen marker <id> [type]` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen edit [id]` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen viewer` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen skinreload <id>` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen browseskins` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen wprecord <id>` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen wpadd [seconds]` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen wpundo` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen wpdone` | `ks.citizen.admin` or `ks.admin` |
| `/kscitizen repair` | `ks.citizen.user.repair` (granted by default) |

Alias: `/npc`. Permission checks are the same for both names.

## NPC Windows

| Window | Permission |
|---|---|
| NPC management (`/kscitizen edit`, or the NPCs tile in `/ksadmin`) | `ks.citizen.admin` or `ks.admin` |
| Skin editor | `ks.citizen.admin` or `ks.admin` |
| NPC viewer (`/kscitizen viewer`, or the hub tile) | `ks.citizen.admin` or `ks.admin` |
| Dialog editor | `ks.citizen.admin` or `ks.admin` |
| "Citizen file locked" notices and "Reload files" | `ks.citizen.admin` or `ks.admin` |

## Console Commands

Commands that run as the server console need `ks.core.admin.dialog.console` on top of the admin rule. This covers:

- NPC interact commands that run as console, death commands (they always run as console) and proximity commands: adding, changing or removing them, copying or deleting an NPC that has them, undoing a step that would change them, and `/kscitizen remove` of such an NPC;
- the NPC's interaction permission while it has interact commands that run as console (changing it would let more players trigger them);
- dialog commands that run as the console (dialog editor);
- web editor imports of NPC files that add, change or remove console commands.

Admins without the node still see these commands, read-only, and can edit everything else. Existing console commands keep running, and commands that run as the player are not affected.

## Showcase Mode

When the server runs in read-only showcase mode, these subcommands are blocked even for players with the admin rule, unless they are real admins:

- `/kscitizen create`, `remove`, `respawnall`, `reload`, `skinreload`
- `/kscitizen wprecord`, `wpadd`, `wpundo`, `wpdone`

Read-only commands (`list`, `tp`, `info`, `marker`, `viewer`) stay available.

## Per-Citizen Interaction Permissions (config-driven)

Individual citizens can require a custom permission string for player interaction. The mod passes whatever string you set to the permission check; no `ks.` prefix is required.

```json
{
  "id": "vip_merchant",
  "permission": "citizen.interact.vip",
  "noPermissionMessage": "Only VIP members can talk to this merchant."
}
```

| Field | Description |
|---|---|
| `permission` | String checked on interaction. Blocked players see `noPermissionMessage`. Leave `null` for open NPCs. |
| `noPermissionMessage` | Message shown to players who lack the required permission. |

The prefix `citizen.interact.*` is a convention; you can use `vip.npc.merchant`, `rank.premium` or anything else.

## LuckPerms Examples

```bash
# Staff admin (all NPC tools, no console commands)
/lp user Steve permission set ks.citizen.admin true

# Head admin who may also edit console commands
/lp user Alex permission set ks.citizen.admin true
/lp user Alex permission set ks.core.admin.dialog.console true

# VIP-only NPC interaction
/lp group vip permission set citizen.interact.vip true

# Take the repair command away from guests
/lp group guest permission set ks.citizen.user.repair false
```

## Migration from Older Versions

Before Core 2.9.2, `/kscitizen` needed `ks.citizen`, `ks.citizen.admin` and `citizen.admin` together. Now one of `ks.citizen.admin`, `ks.admin` or the old `citizen.admin` is enough. Per-NPC interaction strings are not affected.

:::warning
Do not grant `ks.citizen.admin` to regular players. It gives full control over every NPC on the server: create, change, delete and teleport to. Grant `ks.core.admin.dialog.console` only to people you would also give console access.
:::