# Permissions

KyuubiSoft mods use the `ks.<mod>.<scope>.<action>` permission scheme.

- **User nodes** -- `ks.<mod>.user.<action>` -- granted by default (absence means "allowed"). Admins only need to touch them to *take* a command away from a group.
- **Admin nodes** -- `ks.<mod>.admin` -- not granted by default. Give them to staff groups only.
- **The console node** -- `ks.core.admin.dialog.console` -- not granted by default, also not to holders of `ks.admin`. See [Console Commands](#console-commands).
- **Dynamic nodes** -- per-item or per-content permissions you set in config files (NPC interaction permissions, Info Hub sections, ...). See [Dynamic Permissions](#dynamic--config-driven-permissions).

The server console may run every command.

## User Permissions (default: allowed)

| Permission | Mod | Command(s) |
|---|---|---|
| `ks.core.user.settings` | Core | `/kssettings` (KS settings window) |
| `ks.itemupdate.user.use` | Core | `/ksitemupdate` (item update window) |
| `ks.shop.user.use` | Core | Core NPC shops (`/ksnpcshop`) while `ks.core.shop.user.use` is not set |
| `ks.citizen.user.repair` | Core | `/kscitizen repair` (item repair window) |
| `ks.quest.user.use` | Quests | `/ksquest` (Questbook) |
| `ks.quest.user.settings` | Quests | `/ksquestsettings` |
| `ks.achievements.user.use` | Achievements | `/ksachievements` |
| `ks.achievements.user.rewards` | Achievements | `/ksrewards` |
| `ks.achievements.user.titles` | Achievements | `/kstitles` |
| `ks.info.user.use` | Info Hub | `/ksinfo`, `/ksinfoitem`, section and page commands |
| `ks.seasonpass.user.use` | Season Pass | `/ksseasonpass` |
| `ks.bank.user.open` | Bank | `/ksbank open` |
| `ks.bank.user.page` | Bank | `/ksbank page` |
| `ks.bank.user.upgrade` | Bank | `/ksbank upgrade` |
| `ks.bank.user.history` | Bank | `/ksbank history` |
| `ks.pet.user.use` | Pets | `/kspet` (compendium, summon, dismiss, rename, pickup filter) |
| `ks.pet.user.combat` | Pets | `/kscombatpet` |
| `ks.pet.user.mount` | Pets | `/ksmount` |
| `ks.lootbag.user.use` | Lootbags | `/kslootbags` (catalog) |
| `ks.graveyard.user.use` | Graveyard | `/ksgraveyard menu`, `list`, `locate` |
| `ks.item.user.browse` | Item Control | `/ksitem browse` (item browser) |
| `ks.item.user.compare` | Item Control | `/ksitem compare` |
| `ks.item.user.soulbound` | Item Control | `/soulbound` (inspect your held item) |
| `ks.shop.user.browse` | Player Shops | Browse player shops |
| `ks.shop.user.create` | Player Shops | Create your own shop |
| `ks.shop.user.edit` | Player Shops | Edit your own shop |
| `ks.shop.user.collect` | Player Shops | Collect sold items and coins |
| `ks.shop.user.delete` | Player Shops | Delete your own shop |
| `ks.shop.user.rate` | Player Shops | Rate shops |
| `ks.nameplate.user.use` | Nameplates | `/ksnameplate` |
| `ks.dungeon.user.use` | Dungeons | `/ksdungeon open`, `play`, `leave`, `party` |
| `ks.dungeon.user.map.use` | Dungeons | `/ksdungeon maps`, `mapinfo`, using dungeon maps |
| `ks.dungeon.user.stone.use` | Dungeons | Using dungeon stones |
| `ks.claims.user.<action>` | Claims | `/ksclaim` and each subcommand, one node per action (`open`, `claim`, `unclaim`, `info`, `list`, `rename`, `home`, `sethome`, `trust`, `untrust`, `ban`, `unban`, `transfer`, `accept`, `delete`, `buychunks`, `border`, `help`) |
| `ks.guilds.user.open` | Guilds | `/ksguild` (guild window; inside it the guild's rank rights decide) |
| `ks.guilds.user.create`, `ks.guilds.user.invite`, `ks.guilds.user.accept`, `ks.guilds.user.deny`, `ks.guilds.user.join`, `ks.guilds.user.request`, `ks.guilds.user.withdraw`, `ks.guilds.user.leave` | Guilds | `/ksguild create`, `invite`, `accept`, `deny`, `join`, `request`, `withdraw`, `leave` |
| `ks.guilds.user.kick`, `ks.guilds.user.promote`, `ks.guilds.user.demote`, `ks.guilds.user.transfer`, `ks.guilds.user.disband` | Guilds | `/ksguild kick`, `promote`, `demote`, `transfer`, `disband` |
| `ks.guilds.user.info`, `ks.guilds.user.contribute`, `ks.guilds.user.help` | Guilds | `/ksguild info`, `contribute`, `help` |
| `ks.guilds.user.lock`, `ks.guilds.user.unlock`, `ks.guilds.user.lockinfo`, `ks.guilds.user.autolock` | Guilds | `/ksguild lock`, `unlock`, `lockinfo`, `autolock` |
| `ks.guilds.user.home`, `ks.guilds.user.sethome` | Guilds | `/ksguild home`, `/ksguild sethome` (also the **Set here** button) |
| `ks.guilds.user.land` | Guilds | `/ksguild land add`, `remove`, `list` (with Claims 2.0) |
| `ks.guilds.user.chat` | Guilds | `/gc` and the guild chat mode |
| `ks.heirlooms.user.open` | Heirlooms | `/ksheirloom` (story window) |
| `ks.whisperstone.user.use` | Whisperstone | `/kswhisper` and using the Whisperstone item |
| `ks.whisperstone.user.message` | Whisperstone | Raven rune, writing messages and sharing positions |
| `ks.whisperstone.user.call` | Whisperstone | Farcall rune, calling and being called |
| `ks.whisperstone.user.map` | Whisperstone | Star Map rune and the stone's world map markers |
| `ks.chat.user.use` | ChatPlus | `/kschat` |
| `ks.chat.user.msg` | ChatPlus | `/msg`, `/r`, `/ksmail`, `/ignore` |
| `ks.chat.user.rp` | ChatPlus | Roleplay commands (`/me`, `/do`, `/ooc`, `/whisper`, `/shout`) |
| `ks.mastery.user.use` | Weapon Mastery | `/ksmastery` |
| `ks.showcase.user.use` | Showcase | `/ksshowcase` |

`/kslang` has no permission check. VoiceHub's player commands have no permission nodes; every player may use them.

## Admin Permissions (default: deny)

| Permission | Mod | Command |
|---|---|---|
| `ks.admin` | Core | `/ksadmin` hub, `/ksadmin reload`, `/ksadmin testsound`, the NPC shop editor, "Back to Core" from other mods' admin windows; also accepted for all NPC tools |
| `ks.admin.cleanup` | Core | `/ksadmin cleanup nametags` (+ `kyuubisoft.admin` in game) |
| `ks.admin.migrate` | Core | `/ksadmin migrate-storage ...` (+ `kyuubisoft.admin` in game) |
| `ks.admin.xp` | Core | `/ksadmin addxp`, `removexp` (+ `kyuubisoft.admin` in game) |
| `ks.admin.editor` | Core | `/kseditor`, `/kstrusteditor`, `/ksapplyconfig` (+ `kyuubisoft.editor` in game) |
| `ks.admin.dev` | Core | `/ksdev` (+ `dev.admin` in game) |
| `ks.citizen.admin` | Core | `/kscitizen` subcommands, NPC management, skin editor, NPC viewer, dialog editor (`ks.admin` and the old `citizen.admin` work too) |
| `ks.core.admin.dialog.console` | Core and others | Anything that runs as the server console, see below |
| `ks.quest.admin` | Quests | `/ksquestadmin` (alias `/qadmin`) and the Quests admin window |
| `ks.achievements.admin` | Achievements | `/ksachievementadmin` (alias `/acadmin`) and the admin window |
| `ks.info.admin` | Info Hub | `/ksinfoadmin` and the admin window (the old `infohub.admin` still works) |
| `ks.seasonpass.admin` | Season Pass | `/ksseasonpassadmin` (alias `/spadmin`) |
| `ks.bank.admin` | Bank | `/ksbank admin`, `give`, `adminupgrade`, `reset`, `log`, `reload` |
| `ks.pet.admin` | Pets | `/kspetadmin` (alias `/petadmin`) and the admin window |
| `ks.lootbag.admin` | Lootbags | `/kslootbagsadmin` (alias `/lbadmin`) and the admin panel |
| `ks.graveyard.admin` | Graveyard | `/ksgraveyard` admin subcommands (`admin_list`, `admin_clear`, `admin_remove`, `admin_tp`, `admin_stats`, `design_give`, `design_revoke`, `particle_give`, `particle_revoke`, `reload`) |
| `ks.item.admin` | Item Control | `/ksitem` admin subcommands (together with `kyuubisoft.itemcontrol.admin`; `/ksitem inv` with `kyuubisoft.itemcontrol.inventory`) |
| `ks.item.admin.clearslot` | Item Control | **Clear**, **Clear slot** and `/ksitem inv clear`. Not part of `ks.item.admin`, but part of `ks.item.admin.*` |
| `ks.item.admin.removeall` | Item Control | `/ksitem inv wipe` and **Remove item from everyone**. Not part of `ks.item.admin`, but part of `ks.item.admin.*` |
| `ks.item.give` | Item Control | `/ksitem give` (together with `kyuubisoft.itemcontrol.give`), and **Give Item** in the Item Browser with the `admin-give` module |
| `ks.shop.admin` | Player Shops | `/ksshopadmin` (alias `/kssa`) and the Shop Admin window (`ks.admin` alone is not enough) |
| `ks.rental.rent`, `ks.rental.bid` | Player Shops | Rent shops, bid on rentals |
| `ks.shop.list.free`, `ks.shop.list.permanent` | Player Shops | Listing perks |
| `ks.nameplate.admin` | Nameplates | `/ksnameplate admin` (together with `kyuubisoft.nameplates.admin`, configurable) |
| `ks.dungeons.admin` | Dungeons | `/ksdungeon givemap`, `givestone`, `testmap`, `browseprefabs` |
| `kyuubisoft.voicehub.admin` | VoiceHub | `/ksvoice admin`, `/ksvoice proximity` (node name configurable) |
| `ks.claims.admin` | Claims | `/ksclaimadmin` and every subcommand, the admin window, the Claims tile in the `/ksadmin` hub |
| `ks.claims.admin.bypass` | Claims | Ignores the protection of every claim and server zone |
| `ks.guilds.admin` | Guilds | `/ksguild admin`, the admin window and its `/ksadmin` tile; change, remove and break any lock (does not open locks) |
| `ks.guilds.admin.bypass` | Guilds | Open, use and break every locked chest, door and gate |
| `ks.heirlooms.admin` | Heirlooms | `/ksheirloom admin`, `test`, `check`, `clear`, `wear`, `reload` and the admin window |
| `ks.whisperstone.admin` | Whisperstone | `/kswhisper give`, `reload`, `demo`, `demo ring` |
| `ks.chat.admin` | ChatPlus | `/kschatadmin` |
| `ks.mastery.admin` | Weapon Mastery | `/ksmasteryadmin` |
| `ks.mobcontrol.admin` | Mob Control | `/ksmobcontrol` |
| `ks.oreregen.admin` | Ore Regeneration | `/ksoreregen` |
| `ks.showcase.admin` | Showcase | `/ksshowcase savepack` |

The `/ksadmin` hub needs `ks.admin`. Most mod tiles in it also check that mod's own admin node (for example `ks.pet.admin`, `ks.bank.admin`, `ks.lootbag.admin`, `ks.shop.admin`).

## Console Commands

`ks.core.admin.dialog.console` protects everything that runs a command as the **server console**. Admins without it can still see these commands and edit everything else; existing console commands keep running. Grant it only to people you would also give console access.

| Mod | What needs the node (on top of the mod's admin node) |
|---|---|
| Core | NPC commands run as console (interact, death, proximity), dialog commands run as console, NPC shop entries run as console and the permissions that guard them, web editor imports that touch any of these |
| Quests | Console commands in quest rewards and NPC profiles |
| Achievements | Console command rewards |
| Info Hub | Quick tiles with `runAsConsole` |
| Season Pass | Command rewards in tiers, the shop and prestige levels |
| Item Control | Command blocks that run as the console |

See each mod's permission page for the details.

## Dynamic / Config-driven Permissions

These are not hardcoded; server operators set them per item, NPC or section in config files.

| Pattern | Mod | Used in |
|---|---|---|
| `ks.core.shop.user.use` | Core shops | Access to all Core NPC shops; decides when set (granted or denied) |
| shop / entry `permission` | Core shops | Per-shop or per-item purchase gate (optional) |
| `citizen.interact.<custom>` | Core citizens | Per-NPC interaction gate (optional, any string) |
| `infohub.bypass.commandfilter` | Info Hub | Bypass the command browser filter (configurable) |
| section and category permissions | Info Hub | Per-section and per-category access gates (any string) |
| `ks.claims.chunks.<n>`, `ks.claims.claims.<n>` (and `.unlimited`) | Claims | Quota tiers; the tested values come from `quota.chunkTiers` / `quota.claimTiers` in `config.json` |

:::info
These nodes don't have to follow the `ks.*` scheme because you write them yourself. Admins can name them whatever they like (`shop.vip`, `citizen.interact.blacksmith`, ...); the mod passes them to the permission check as they are.
:::

## Per-Mod Detail Pages

Each mod has its own permission page with the complete command table and showcase/console notes:

- [Core](https://wiki.kyuubisoft.com/hytale/core/permissions/)
- [Citizens](https://wiki.kyuubisoft.com/hytale/citizens/permissions/)
- [Shop System (NPC shops)](https://wiki.kyuubisoft.com/hytale/shop-system/permissions/)
- [Quest System](https://wiki.kyuubisoft.com/hytale/quest-system/permissions/)
- [Achievement System](https://wiki.kyuubisoft.com/hytale/achievement-system/permissions/)
- [Info Hub](https://wiki.kyuubisoft.com/hytale/info-hub/permissions/)
- [Bank](https://wiki.kyuubisoft.com/hytale/bank/permissions/)
- [Pets](https://wiki.kyuubisoft.com/hytale/pets/permissions/)
- [Graveyard](https://wiki.kyuubisoft.com/hytale/graveyard/permissions/)
- [Season Pass](https://wiki.kyuubisoft.com/hytale/season-pass/permissions/)
- [Player Shops](https://wiki.kyuubisoft.com/hytale/player-shops/permissions/)
- [Item Control](https://wiki.kyuubisoft.com/hytale/item-control/permissions/)
- [Lootbags](https://wiki.kyuubisoft.com/hytale/lootbags/permissions/)
- [VoiceHub](https://wiki.kyuubisoft.com/hytale/voicehub/permissions/)
- [Nameplates](https://wiki.kyuubisoft.com/hytale/nameplates/permissions/)
- [Dungeons](https://wiki.kyuubisoft.com/hytale/dungeons/permissions/)
- [Claims](https://wiki.kyuubisoft.com/hytale/claims/permissions/)
- [Guilds](https://wiki.kyuubisoft.com/hytale/guilds/permissions/)
- [Heirlooms](https://wiki.kyuubisoft.com/hytale/heirlooms/permissions/)
- [Whisperstone](https://wiki.kyuubisoft.com/hytale/whisperstone/permissions/)

## Older Permission Nodes

Earlier releases used a mixed scheme (`questbook.admin`, `bank.admin`, `pets.admin`, `kyuubisoft.admin`, `citizen.admin`, ...). Most of these were replaced by the `ks.*` nodes above, but a few are **still checked** in addition, or still accepted:

| Older node | Status |
|---|---|
| `kyuubisoft.admin` | Still checked in game for `/ksadmin cleanup`, `migrate-storage`, `addxp`, `removexp`. No longer needed for `/ksadmin` and `/ksadmin reload`. |
| `ks.admin.reload` | No longer used; `/ksadmin reload` needs `ks.admin`. |
| `kyuubisoft.editor` | Still checked in game for the web editor commands. |
| `dev.admin` | Still checked in game for `/ksdev`. |
| `citizen.admin` | Still accepted instead of `ks.citizen.admin`. |
| `infohub.admin` | Still accepted instead of `ks.info.admin`. |
| `kyuubisoft.itemcontrol.*` | Still checked together with the `ks.item.*` admin nodes. |
| `kyuubisoft.nameplates.admin` | Still checked together with `ks.nameplate.admin` (configurable). |
| `ks.claim.user.use`, `ks.claim.admin`, `ksclaim.admin` | No longer checked since Claims 2.0.0; use the `ks.claims.*` nodes. |

:::tip[Quick setup]
```
# Staff group: every admin node, including the older ones still checked
group.staff.permission.ks.admin: true
group.staff.permission.kyuubisoft.admin: true
group.staff.permission.ks.admin.cleanup: true
group.staff.permission.ks.admin.migrate: true
group.staff.permission.ks.admin.xp: true
group.staff.permission.ks.admin.editor: true
group.staff.permission.kyuubisoft.editor: true
group.staff.permission.ks.admin.dev: true
group.staff.permission.dev.admin: true
group.staff.permission.ks.citizen.admin: true
group.staff.permission.ks.quest.admin: true
group.staff.permission.ks.achievements.admin: true
group.staff.permission.ks.info.admin: true
group.staff.permission.ks.seasonpass.admin: true
group.staff.permission.ks.bank.admin: true
group.staff.permission.ks.pet.admin: true
group.staff.permission.ks.lootbag.admin: true
group.staff.permission.ks.graveyard.admin: true
group.staff.permission.ks.item.admin: true
group.staff.permission.kyuubisoft.itemcontrol.admin: true
group.staff.permission.kyuubisoft.itemcontrol.inventory: true
group.staff.permission.ks.item.admin.clearslot: true
group.staff.permission.ks.shop.admin: true
group.staff.permission.ks.nameplate.admin: true
group.staff.permission.kyuubisoft.nameplates.admin: true
group.staff.permission.ks.dungeons.admin: true
group.staff.permission.ks.claims.admin: true
group.staff.permission.ks.guilds.admin: true
group.staff.permission.ks.heirlooms.admin: true
group.staff.permission.ks.whisperstone.admin: true
group.staff.permission.ks.chat.admin: true
group.staff.permission.ks.mastery.admin: true
group.staff.permission.ks.mobcontrol.admin: true
group.staff.permission.ks.oreregen.admin: true

# Head admins only: item spawning, removing items from everyone and console commands
group.headadmin.permission.ks.item.give: true
group.headadmin.permission.kyuubisoft.itemcontrol.give: true
group.headadmin.permission.ks.item.admin.removeall: true
group.headadmin.permission.ks.core.admin.dialog.console: true
```
:::