# Permissions

# Permissions

Item Control uses the `ks.item.*` nodes for its commands. Admin commands additionally check the older `kyuubisoft.itemcontrol.*` nodes, so staff need **both** nodes of a pair. On top of that come per-item and per-recipe permission strings that you choose yourself.

## Player Nodes

| Permission | Default | Description |
|---|---|---|
| `ks.item.user.browse` | allowed | `/ksitem browse` — open the Item Browser |
| `ks.item.user.compare` | allowed | `/ksitem compare <a> <b>` and **Compare** in the Item Browser |
| `ks.item.user.soulbound` | allowed | `/soulbound` — inspect your held item's soulbound state |

Set one of these to `false` for a group to take it away from those players.

## Admin Nodes

| Grant both | What it unlocks |
|---|---|
| `ks.item.admin` + `kyuubisoft.itemcontrol.admin` | `/ksitem admin` (Admin Hub) and every admin subcommand except `give` and `inv` (see the table below) |
| `ks.item.admin` + `kyuubisoft.itemcontrol.inventory` | `/ksitem inv ...` (view, snapshot, restore, clear, history). `wipe` needs one node more. |
| `ks.item.give` + `kyuubisoft.itemcontrol.give` | `/ksitem give`, and **Give Item** in the Item Browser while the `admin-give` module is on |

:::caution[Grant both nodes]
`ks.item.admin` lets the command through, and the command then checks `kyuubisoft.itemcontrol.admin` (or `.inventory` / `.give`). A player with only one of the two gets "no permission". Operators with `*` have both.
:::

`ks.item.give` is separate from `ks.item.admin` on purpose: you can give staff the admin tools without letting them spawn items.

### Clearing and Removing Items

Two actions have a right of their own, and nobody has them until you grant them:

| Permission | What it unlocks |
|---|---|
| `ks.item.admin.clearslot` | **Clear** and **Clear slot** in the inventory view, and `/ksitem inv clear` |
| `ks.item.admin.removeall` | **Remove item from everyone** in the Inventory place, and `/ksitem inv wipe` |

Without the right, the button does not appear, and the server checks again when the click arrives.

:::caution[`ks.item.admin` does not include them]
`ks.item.admin` is one node, not a group of nodes. A player with only `ks.item.admin` does not get these two rights. `ks.item.admin.*`, `ks.item.*`, `ks.*` and `*` include them, and `ks.item.admin.*` covers `ks.item.admin` itself too. Check your groups if you use wildcards.
:::

### Admin Subcommand Coverage

`ks.item.admin` + `kyuubisoft.itemcontrol.admin` cover:

| Subcommand | Description |
|---|---|
| `/ksitem admin` | Open the Admin Hub |
| `/ksitem reload` | Reload configs |
| `/ksitem module ...` | List, enable and disable modules |
| `/ksitem craft ...` | Crafting rules |
| `/ksitem death ...` | Death rules |
| `/ksitem restrict ...` | Usage restrictions |
| `/ksitem soulbound ...` | Soulbound management |
| `/ksitem dropprevention ...` | Drop prevention |
| `/ksitem cooldown ...` | Cooldown management. `check` only needs `ks.item.admin`. |
| `/ksitem watch ...` | Watched items |
| `/ksitem drops ...` | Drop rules |
| `/ksitem temprule ...` | Temporary rules |
| `/ksitem override ...` | Item overrides |
| `/ksitem cmdblock` | Command block edit mode |
| `/ksitem browsescripts` | Script file browser (needs KyuubiSoft Core; currently unavailable) |

### Other Checks

| Where | Node |
|---|---|
| Item Control tile in the `/ksadmin` hub | `ks.item.admin` + `kyuubisoft.itemcontrol.admin`. Core's hub itself needs `ks.admin`. |
| **Inventory** place in the Admin Hub | The rights of the hub. `kyuubisoft.itemcontrol.inventory` is not checked there. |
| Hitting a block in command block edit mode opens the editor | `kyuubisoft.itemcontrol.admin` |
| Breaking an indestructible command block | `kyuubisoft.itemcontrol.admin` (console blocks: also `ks.core.admin.dialog.console`) |

:::note[Inventory tools in the hub]
Whoever can open the Admin Hub can use the **Inventory** place: view, back up, clear and restore. Grant the hub only to people you trust with player inventories.
:::

## Command Blocks

A command block that runs **as the server console** runs its command with full server rights for whoever hits it. Adding, changing or removing such a block therefore needs **`ks.core.admin.dialog.console`** in addition to the admin nodes. This is the same right that KyuubiSoft Core uses for console commands in its NPC window, dialog editor and shop editor.

Without `ks.core.admin.dialog.console`:

- The editor shows a console block read-only with a hint. Command, run mode and **Indestructible** are locked, and **Test**, **Save** and **Delete** are not available.
- The list of **Command Blocks** offers **View** instead of **Edit** and no **×** for such a block.
- You cannot switch a block to **Console**, and you cannot switch a console block back to **Player**.
- You cannot break an indestructible console block.
- Blocks that run as the player stay fully editable. New blocks run as the player by default.

Existing console blocks keep working. The server checks the right again when a block is saved, tested or deleted.

## Config-driven Permissions

These are strings you choose. The mod checks whatever value you set, so name them to fit your server.

### Crafting bypass

```json
{
  "crafting-rules": {
    "bypassPermission": "kyuubisoft.itemcontrol.craft.bypass"
  }
}
```
Players with this permission can craft blocked items. The default string is `kyuubisoft.itemcontrol.craft.bypass`.

### Usage restrictions

Enter a permission such as `vip.legendary_weapons` in **Usage Rules** in the Admin Hub, or with the command:

```bash
/ksitem restrict add Weapon_Legendary_Sword vip.legendary_weapons
```

Only players with that node can use the restricted item. Without a permission nobody may use it, and `owner` lets only the soulbound owner use it. Permissions cannot contain spaces.

### Custom recipes

Custom recipes can include a permission field. Players without it do not see the recipe and cannot craft it.

### Watched item notifications

Admins with `kyuubisoft.itemcontrol.watchlist.notify` receive real-time chat alerts when a watched item is crafted, picked up or dropped. This node is fixed; the `notifyPermission` field in `config.json` is not read.

## LuckPerms Examples

```
# Staff admin — every admin subcommand except give and inv
/lp group admin permission set ks.item.admin true
/lp group admin permission set kyuubisoft.itemcontrol.admin true

# Inventory tools
/lp group admin permission set kyuubisoft.itemcontrol.inventory true

# Clear single slots, and remove an item from everyone online
/lp group admin permission set ks.item.admin.clearslot true
/lp group headadmin permission set ks.item.admin.removeall true

# Give (common pattern: only for trusted staff)
/lp group mod permission set ks.item.give true
/lp group mod permission set kyuubisoft.itemcontrol.give true

# Console command blocks (only for people you trust with the server console)
/lp user Steve permission set ks.core.admin.dialog.console true

# Crafting bypass for VIPs
/lp group vip permission set kyuubisoft.itemcontrol.craft.bypass true
```