# Admin UI

# Admin UI

The Admin Hub is where you manage everything in Item Control. Open it with `/ksitem admin`, or with KyuubiSoft Core installed from the Item Control tile in the `/ksadmin` hub. Both ways need `ks.item.admin` and `kyuubisoft.itemcontrol.admin`, see [Permissions](https://wiki.kyuubisoft.com/hytale/item-control/permissions/).

## The Hub

The column on the left leads to every place, and the chosen place opens on the right. What you typed into a place stays there until you close the hub.

| Group | Places | Module |
|-------|--------|--------|
| | **Modules** | Always there |
| **Item Rules** | **Crafting**, **Death**, **Soulbound**, **Drop Protection**, **Cooldowns**, **Usage Rules** | `crafting-rules`, `death-rules`, `soulbound`, `drop-prevention`, `cooldowns`, `usage-rules` |
| **Admin** | **Watched**, **Alerts**, **Temp Rules** | `item-watchlist` (both), `temp-rules` |
| **Recipes and drops** | **Recipes**, **NPC/Block Drops** | `crafting-rules`, `drop-rules` |
| **World** | **Inventory**, **Command Blocks**, **Item Adjustments** | `inventory-tools`, `command-blocks`, `item-overrides` |

Each line shows a number, such as how many entries the list holds. **Reload Config** at the bottom does the same as `/ksitem reload`.

A place whose module is off stays in the column, dimmed and marked **Off**. Its page says how many saved entries have no effect right now and offers **Turn on**. Rules are not added while a module is off, so nothing turns on by itself.

## Modules

The first page shows the state of your server.

![The Modules page with five tiles, all modules with their switches, and the To check list with a warning about an item that does not exist](../../../../assets/item-control/item-control-modules.png)

- **Tiles:** **Modules on**, **Rules**, **Custom recipes**, **Command Blocks** and **Alerts**.
- **Module overview:** All 14 modules with one line about each. The switch turns a module on or off right away, and **Open ›** goes to its place. **Item Browser** opens the browser, and **Admin Give** has no place of its own.
- **To check:** Entries that do nothing without anybody noticing. Click a line to go straight to the entry.
- **Check item:** Pick an item and see every rule that hits it, also through patterns like `Weapon_*`. Click a line to go to that rule.

**To check** finds items that do not exist, patterns and categories that match nothing, patterns in lists that only compare exact IDs, modules that are off but still hold entries, a death protection list that has no effect in the current death mode, and cooldown group items without a duration.

## How the Rule Lists Work

**Crafting**, **Death**, **Soulbound**, **Drop Protection**, **Cooldowns**, **Usage Rules**, **Watched** and **Temp Rules** all work the same way, with the list on the left and the form on the right.

![The Crafting page with blocked items by exact ID, by pattern and by item kind, and a warning next to an ID that does not exist](../../../../assets/item-control/item-control-crafting.png)

**Adding an entry:**

- Type an item ID, or click **Select** to pick from all items by name or ID.
- Below the field you see how many items your entry affects, with a few icons. **Add** only works once the entry makes sense, and a line tells you why not, for example `This does not match any item. A typo?`
- **Templates**, where a list has them, fill in a ready-made pattern such as **All bows** or **All weapons**.

![The item selection with a search field, category tabs and a grid of items to click](../../../../assets/item-control/item-control-item-picker.png)

**Patterns:** **Crafting**, **Death**, **Soulbound**, **Drop Protection** and **Usage Rules** accept [patterns](https://wiki.kyuubisoft.com/hytale/item-control/modules/#item-patterns). The pills **Exact**, **Starts with** and **Contains** change what you typed into a pattern, and **Weapons**, **Armor** and **Tools** enter a whole item type.

**Cooldowns**, **Watched** and **Temp Rules** compare exact item IDs, so the form offers no patterns there.

**The list:** **Search the list…** filters the rows. An entry that does nothing is marked in red: `Item does not exist`, `Matches no item` or `Patterns have no effect here`.

**Removing an entry:** **×** removes it at once, and **Undo** brings it back. Only a running temporary rule with an announcement asks first, because bringing it back would announce it again.

## Crafting

**Crafting** has two tabs. **Items** is the list of items and patterns that cannot be crafted. **Categories** is explained under [Categories](#categories).

## Death

**Items** is the list of items that are kept on death. **Categories** is explained under [Categories](#categories).

Above the form you choose the **Death Mode**:

| Mode | What happens |
|------|--------------|
| **Vanilla** | Drop everything |
| **Keep All** | Keep everything |
| **Selective** | Only the items on the list stay. Your own soulbound items always stay. |

**Preserve Durability on Death** is a switch of its own. In any mode other than **Selective**, a warning says that the list has no effect.

## Categories

The **Categories** tab of **Crafting** and **Death** saves you from listing items one by one. Switch on what you want, and the list shows how many items each entry hits:

- **Item kinds:** Weapons, Armor, Tools, Consumables, Blocks, Utility and Gliders.
- **Categories in the game:** The item categories the server knows. **Search categories…** finds them.

![The Categories tab with switches for item kinds and game categories, each with the number of items it matches](../../../../assets/item-control/item-control-categories.png)

New entries are saved as `@weapon` or `@category:Items.Weapons`. Bare words from older files stay as they are and keep working.

## Soulbound

**Auto-bind** lists items that bind to a player on pickup. Binding a single item by hand and recovering lost items stay [commands](https://wiki.kyuubisoft.com/hytale/item-control/commands/#soulbound).

## Drop Protection

**Auto-protect** lists items that are marked as drop protected on pickup. Marking a single item by hand is a [command](https://wiki.kyuubisoft.com/hytale/item-control/commands/#drop-prevention).

## Cooldowns

**Cooldowns** has three tabs.

### Items

An exact item ID and a **Duration in seconds**, with buttons for 10, 30, 60 and 300 seconds.

### Categories

A cooldown "category" is the start of an item ID, not a category of the game. **ID start** takes something like `Potion_`, and the cooldown applies to every item whose ID starts like this. Upper and lower case count. A cooldown of the item itself comes first. **Add** only works when the start hits at least one item, and you see up to six of them.

### Groups

When a player uses an item of a group, all items of the group wait just as long. The duration comes from the item that was used. An item belongs to one group at most, so adding it to a second group moves it there.

![The Groups tab with three cooldown groups on the left, one of them marked in red for items without a duration, and the items of the chosen group on the right](../../../../assets/item-control/item-control-cooldown-groups.png)

- **New group** creates a group. Change its name under **Name of the group**.
- **Add item** picks an item for the **Items of the group**.
- **Delete group** removes the group. The items keep their own cooldown.

:::caution[Groups need durations]
A group only works for items that have a duration of their own, through the **Items** or **Categories** tab. An item without one is marked `No duration of its own, no effect here`, and using it starts nothing.
:::

## Usage Rules

The form has these parts:

| Part | What it does |
|------|--------------|
| **Restrict** | Item ID or pattern |
| **Permission** | Who may use the item. **For nobody** leaves it empty, **Owner only** enters `owner` for the soulbound owner, any other text is a permission node. |
| **Blocks** | **Block all**, **Equip only** or **Use only** |
| **Message** | Optional text for the player, otherwise the standard text |

:::note
A rule added here starts with **Block all**. `/ksitem restrict add` creates `block-equip`. Pickup-only rules exist too, but only in [`config.json`](https://wiki.kyuubisoft.com/hytale/item-control/configuration/#usage-rules).
:::

## Watched

**Watch item** takes an exact item ID. Whoever has `kyuubisoft.itemcontrol.watchlist.notify` gets a chat line when such an item moves, and the event lands in **Alerts**.

## Alerts

All events of watched items, newest first. Search with **Search player or item…** and filter by **All**, **Crafted**, **Picked up**, **Dropped** or **NPC drop**.

**Inventory ›** opens the inventory of that player, or their history if they are offline. It needs the `inventory-tools` module and does not appear for **NPC drop**, because the name there is an NPC role. The server keeps the last 500 alerts.

## Temp Rules

Rules that end by themselves.

| Part | What it does |
|------|--------------|
| **Rule Type** | **Block Crafting**, **Unlock Crafting** or **Block Usage** |
| **Items** | Exact item IDs, several with commas |
| **Duration in minutes** | With buttons for 1 hour, 1 day and 1 week |
| **Starts** | **Now**, **In 1 hour** or **Tomorrow** |
| **Announcement** | Optional text for everyone |

Each row shows the state, such as `active, 42 min` or `pending, in 1 h`. **+30 min** extends a running rule.

**Announcement:** When the rule becomes active, everyone online reads the text in chat. The server checks every 30 seconds, so it can come up to 30 seconds late. Rules that were already running when the server or the module started are not announced again.

By default **Block Crafting** and **Block Usage** both block crafting and usage. To keep them apart, set [`temp-rules.strictTypes`](https://wiki.kyuubisoft.com/hytale/item-control/configuration/#options) to `true`. A usage block needs the `usage-rules` module, a crafting block the `crafting-rules` module.

## Recipes

The **Recipe Manager** lists every recipe. Above the list you see how many there are, how many are off and how many are custom.

![The Recipes page with filters, every recipe with its switch and tags, and the details of the chosen recipe](../../../../assets/item-control/item-control-recipes.png)

- **Filters:** **Search recipe or output …**, a dropdown with **All benches**, **Custom** and each bench, and the pills **All**, **On**, **Off**, **Custom**, **Edited** and **Locked**.
- **Rows:** Each row shows the output, the bench and the tags. The switch with **KS: On** or **KS: Off** turns a recipe on or off. It shows Item Control's own state only.
- **Locked:** The recipe has a vanilla progression lock, such as a bench upgrade, "must be learned first" or a world memories level. It can be **KS: On** and still not be craftable yet.
- **Enable filtered** and **Disable filtered:** Change everything the current filter shows. They ask first, with the count and the filter. Vanilla locks stay in place.
- **+ Add Custom:** Opens the [recipe editor](#recipe-editor) for a new recipe.

Click a recipe to see its inputs, output, **Bench**, **Tier**, **Time**, **Permission** and locks. There you find:

- **Edit** opens the recipe editor.
- **Duplicate** creates a custom recipe on the same bench. A copy has no progression locks, and a message tells you so.
- **Delete** only appears for custom recipes. It asks first.

### Recipe Editor

![The recipe editor with templates, inputs, a preview, the crafting station, permission, progression locks and the Check button](../../../../assets/item-control/item-control-recipe-editor.png)

| Part | What it does |
|------|--------------|
| **Template** | **Weapon**, **Armor**, **Potion**, **Food** or **Smelting** fill in bench, category and time, nothing else |
| **Output** | Click the slot to pick an item, or type an ID. **Qty** from 1 to 9999. |
| **Inputs (up to 4)** | Click a slot to pick an item or a resource type. By hand, a resource type is `res:Fuel`. Leave a row empty if you do not need it. |
| **Preview** | The recipe as it looks when crafting |
| **Crafting Station** | **Bench**, **Category** (or automatic), **Tier** from 0 to 999, **Time in seconds** from 0 to 86400 |
| **Permission (optional)** | Empty means everybody may use the recipe. Without the permission a player does not see it. |
| **Check** | Lists everything that stops saving. Click a line to jump to the row. |

- **Progression locks:** A vanilla recipe with locks shows them here with **Locks: kept** or **Locks: removed**. "Kept" is the default.
- **What the form does not show stays:** Inputs after slot 4, other benches and secondary outputs of a vanilla recipe are kept when you save.
- **Reset:** Empties your changes in the form of an untouched recipe. On an edited recipe it asks first (**Discard edit**), and the vanilla recipe comes back for all online players. A recipe that is switched off stays off.

## NPC/Block Drops

![The drop page with the form for a rule on the left, the custom rules on the right and a preview of the vanilla drops with the new rule below them](../../../../assets/item-control/item-control-drops.png)

**The form** on the left creates a drop rule:

| Field | What it does |
|-------|--------------|
| **Role** | NPC role, block ID, drop list ID, a pattern like `Trork_*`, or `*` for all. **List ›** goes to the drop lists. |
| **Item** | Item ID, or **Choose** to pick. Patterns only work in mode **Remove**. |
| **Min** / **Max** | Whole numbers from 1 to 9999 |
| **Chance in %** | From 0 to 100, with comma or point |
| **Mode** | **Add** comes on top of the vanilla drops, **Replace** replaces all of them, **Remove** takes this item away |

:::caution[Percent, not a fraction]
The window takes percent: `50` is 50 %, and `0.5` is 0.5 %. The file and `/ksitem drops add` keep a fraction from 0 to 1, so there `0.5` means 50 %. For a value of 1 % or less the window shows a hint, and anything that cannot be read shows a message and saves nothing.
:::

**Lookup** shows what this role drops today and what your rule changes about that: vanilla lines, lines that are gone, saved rules and your new rule.

**Custom Rules** lists all rules. Click a rule to load it into the form. Adding a rule for the same role and item replaces it, and **×** removes a rule after asking.

**Drop Lists** shows the drop lists of the game with a search. Click one to put it into **Role** and look it up.

## Inventory

**Inventory Tools** lists **Online players** and **Known players (backup history)**, who are players with backups, also offline. **Search player…** finds them. Up to 50 known players are listed, so search for the others.

Select a player to see the last backup and how many there are, with these buttons:

| Button | What it does |
|--------|--------------|
| **View Inventory** | Opens the [inventory view](#inventory-view). Online players only. |
| **View History** | Opens the [history](#history), also for offline players. |
| **Create Backup** | Stores a backup by hand, marked with your name. Online players only. |

**Remove item from everyone** only appears with `ks.item.admin.removeall`. Pick an item and you see `5 stacks at 2 players`. **Remove** first stores a backup for each of these players. It hits only players who are online. A player whose backup fails keeps the item, and a message says how many.

### Inventory View

A live view of **Hotbar**, **Armor**, **Utility**, **Backpack**, **Storage** and **Tools**, with **World**, **Position** and how many slots are **Filled**. It works for players in other worlds too.

![The inventory view with the player facts and buttons on the left, all slots in the middle and the details of the chosen item on the right](../../../../assets/item-control/item-control-inventory.png)

Click a slot to see **ID**, **Amount**, **Slot**, **Section**, durability and whether the item is soulbound or drop protected. Hovering shows the normal item tooltip of the game.

| Button | What it does |
|--------|--------------|
| **Refresh** | Reads the inventory again |
| **Snapshot** | Stores a backup with a name you choose |
| **History** | Opens the history of this player |
| **Clear** | Empties the whole inventory after asking. **Store a backup first** is on by default. Only with `ks.item.admin.clearslot`. |
| **Clear slot** | Empties the chosen slot after asking. It always stores a backup first. Only with `ks.item.admin.clearslot`. If the slot changed in the meantime, nothing is removed. |

### History

All backups of a player, newest first, also while the player is offline. The filters are **All**, **Join**, **Death**, **Admin** and **Manual**. **Load older** gets more.

![The history with the backups of a player on the left and the chosen backup on the right, with the slots that differ from the inventory now marked in gold](../../../../assets/item-control/item-control-history.png)

Select a backup to see its contents, then:

- **Compare with now** marks every slot that differs from the current inventory in gold. Online players only.
- **Teleport** takes you to where the backup was made, also in another world. The window closes when the world changes.
- **Restore** asks first and completely replaces the inventory. Online players only. Stacks that have no room stay in the backup, and a message says how many. A backup that cannot be read completely cannot be restored.

### Safety Backups

Item Control stores a backup before it changes an inventory. If that backup fails, nothing is changed.

| Backup type | Stored before | Also with |
|-------------|---------------|-----------|
| `before-clear` | **Clear** (unless you switch it off) and **Clear slot** | `/ksitem inv clear`, always |
| `before-restore` | **Restore** | `/ksitem inv restore` |
| `before-wipe` | **Remove item from everyone**, for each player who holds it | `/ksitem inv wipe` |

They appear in the history with the tag **Safety** and a line such as `Before clearing`, under the filter **Admin**. A player keeps up to 50 normal backups and up to 20 safety backups, and safety backups never push out a normal one. An empty inventory stores no backup.

## Command Blocks

All command blocks of the server. **Search command, world or position…** filters them, and blocks that run as the console or are indestructible have a tag.

![The Command Blocks page with every block, its command and position, and buttons to edit it or teleport there](../../../../assets/item-control/item-control-command-blocks.png)

- **Edit mode** does the same as `/ksitem cmdblock`. Close the window and hit a block, and the editor opens.
- **Edit** opens the editor. For a console block without the [console right](https://wiki.kyuubisoft.com/hytale/item-control/permissions/#command-blocks), the button says **View** instead.
- **Teleport** takes you to the block, also in another world.
- **×** removes the block after asking.

### Command Block Editor

| Part | What it does |
|------|--------------|
| **Command** | The command to run. `@p` is the player name, `@pos` the block position. |
| **Templates** | **Teleport**, **NPC shop**, **Info book** and **Spawn NPC** enter an example |
| **How it runs** | The command with its placeholders filled in, and whether the first word is a known command. Arguments are only checked when it runs. |
| **Indestructible** | Only admins can break this block |
| **Run as** | **Player** runs with the rights and position of the player, **Console** runs with full server rights for everyone who hits the block |

**Test** runs the command right now. As a player the result is in the chat, and as the console it is in the server log. **Save** stores the block and **Delete** removes it.

Without the console right, a console block opens read-only: command, run mode and **Indestructible** are locked, and **Delete**, **Test** and **Save** are not available.

## Item Adjustments

This window changes the values of single items. Values take effect at once, without a restart, and the original value is always kept. The module is `item-overrides`.

![The Item Adjustments window with the item list on the left and the values of an iron sword on the right, with the original value next to a changed one](../../../../assets/item-control/item-control-customize.png)

Find an item with **Search item…**, or show only changed ones with **Adjusted only**. A value you typed stays while you look at another item, and the list marks that item **Unsaved**. Only fields that apply to the item are shown:

| Section | Fields |
|---------|--------|
| **Durability** | **Max Durability**, **Durability Loss/Hit** |
| **Stack and quality** | **Max Stack**, **Quality ID** (**Common** to **Legendary**) |
| **Values** | **Weapon Damage**, **Tool Speed**, **Armor Resistance** |
| **Behavior** | **Consumable**, **Drop on Death**, **Durability Loss/Death**, each **Yes** or **No** |
| **Crafting** | **Crafting Tier**, **Crafting Output Qty** |

- **Save** shows how many values are waiting. If a number is not valid, it says how many and saves nothing.
- **×** next to a value resets only that field. **Reset** resets the whole item after asking.
- **Transfer** copies the saved values to other items of the same kind. Values that make no sense on an item are left out.
- **Edit Weapon** and **Edit Armor** open the editors below. Leaving with unsaved values asks first.

### Weapon Editor

![The weapon editor with all interactions of a weapon, their damage values and properties](../../../../assets/item-control/item-control-weapon.png)

**Interactions** lists all interactions of a weapon, filtered by **All**, **Light**, **Charged** or **Signature**. Each one shows **Damage**, **Properties** (knockback and sequence values) and **Per hit**.

- **All damage** changes the damage of the interactions shown by -10 %, +10 % or +25 %. Nothing changes until you save.
- **Add damage type** adds a type with a value to all interactions that lack it. An added type stays after a restart, and resetting the interactions removes it again.

**Weapon Stats** holds the **Signature attack**, which you change with **Apply**, and the weapon values.

### Armor Editor

**Base Resistance**, **Stat Modifiers**, **Attack Class Enhancement** and the damage values per type, each with **Resistance**, **Enhancement**, **KB Resistance** and **KB Enhancement**. **Add Type** and **Add Stat** add new rows, **Legend** explains the fields, and **Reset All** goes back to the original values after asking.

## Item Browser

Every player can open the browser with `/ksitem browse`, and admins also from **Modules**.

![The Item Browser with categories on the left, the item grid in the middle and the details of the chosen item on the right](../../../../assets/item-control/item-control-item-browser.png)

Choose a category, or use **Search items...**. Click an item to see three tabs:

- **Info:** **ID**, **Item Level**, **Max Stack**, **Max Durability**, **Consumable**, **Quality** and **Categories**.
- **Recipes:** All recipes for this item. Click an ingredient to go to it.
- **Drops:** The NPCs and blocks that drop it.

**Compare** opens the comparison. **Give Item** with an **Amount** of 1, 10 or a stack only appears if you may give items, see [Permissions](https://wiki.kyuubisoft.com/hytale/item-control/permissions/#admin-nodes).

### Item Comparison

Two items side by side, also with `/ksitem compare <item1> <item2>`. A green value on the right is higher than on the left, a red one is lower. **Swap** changes sides, and **Other item** picks another one.

![Two items side by side with their values, and the differences in green and red](../../../../assets/item-control/item-control-compare.png)

## Item Card

A small card above the hotbar tells players about the item in their hand.

![Several states of the card side by side above a hotbar: ready, ready again, a running cooldown, temporarily blocked and restricted](../../../../assets/item-control/item-control-hud.png)

| Card | When |
|------|------|
| Name, bar and time left | The cooldown is running |
| `Cooldown 30 s · ready` | The item has a cooldown and is ready. Switch this off with `hud-card.showReady`. |
| `Ready again` | The cooldown just ended, for 2 seconds |
| `RESTRICTED ITEM` | A usage rule stops this player. It shows your message, or what is blocked and for whom. |
| `Temporarily blocked` | A temporary rule blocks the item, with the time left |

The picture shows several cards side by side, but a player only ever sees one. A temporary block comes first, then a usage rule, then the cooldown.

A player who may use the item gets no restriction card. The card is hidden while a window is open, and with KyuubiSoft Core also while the world map is open. Switch it off with [`hud-card.enabled`](https://wiki.kyuubisoft.com/hytale/item-control/configuration/#options).