# Item Control

# Item Control

**14 modules**, each with its own switch, cover everything from crafting restrictions and custom drops to soulbound items and inventory backups. A module that is off does nothing on your server.

One mod, one admin window, full control over every item on your server.

**Main Command:** `/ksitem` (Aliases: `itemcontrol`, `ic`)

---

## What's new in 3.0

All windows of version 3.0.1 are new, and the [Admin UI](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/) page explains each of them.

- **One new admin window.** A column on the left leads to every place. A module that is off stays visible and offers **Turn on**.
- **See what is wrong.** **To check** lists entries that do nothing, such as a mistyped item ID. **Check item** shows every rule that hits an item, also through patterns.
- **Pick instead of type.** Select items from a list, see how many items a pattern affects, and bring back a removed entry with **Undo**.
- **Safer inventories.** Clearing, restoring and removing an item store a [safety backup](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/#safety-backups) first. You can compare a backup with the inventory now.
- **New rights.** [`ks.item.admin.clearslot` and `ks.item.admin.removeall`](https://wiki.kyuubisoft.com/hytale/item-control/permissions/#clearing-and-removing-items) are not part of `ks.item.admin`, and `/ksitem inv clear` and `/ksitem inv wipe` now need them.
- **Item card.** A small card above the hotbar shows the cooldown of the held item, and why it is blocked.
- **Temporary rules** can start later and announce themselves to everyone.
- **Drop chances in percent** in the window. The file and `/ksitem drops add` keep a fraction from 0 to 1.
- **Recipes** have filters, templates, a check before saving and a way to switch many at once.

---

## Modules at a Glance

### Item Browser

Lets every player look through all items, with search and category filters.

- Details for each item, with recipes and the NPCs and blocks that drop it
- **Item Comparison:** Two items side by side, with the differences in color
- **Give Item** right from the details, for admins

### Crafting Rules

Control what can be crafted on your server.

- **Blocking:** Block single items, patterns or whole item categories
- **Your own recipes:** Up to 4 inputs, also resource types like `res:Fuel`, with templates and a check before saving
- **Changing recipes:** Edit vanilla recipes and keep their progression locks unless you remove them on purpose
- **On and off:** Switch single recipes or everything a filter shows
- **Bypass:** A permission for VIPs or staff

Recipes reach players at once, without a client restart.

### Drop Rules (NPC + Block)

Change what NPCs and blocks drop.

- **3 modes:** Add on top of the vanilla drops, replace them or remove an item from them
- **Amount and chance:** A range from min to max, and a chance in percent in the window
- **Wildcards:** `*` applies a rule to all NPCs, `Trork_*` or `Ore_*` to all matching roles or blocks
- **Lookup:** See what a role drops today and what your rule changes
- **Real loot:** Ores drop what they really drop in the game, not the block itself

### Soulbound System

Bind items to one player.

- Cannot be dropped, put into chests or picked up by others
- A container with soulbound items in it cannot be destroyed
- **Auto-bind:** Items that bind on pickup
- **Recovery:** Get lost items back with a command
- **Tooltip:** An optional "Soulbound: PlayerName" line, with DynamicTooltipsLib
- `/soulbound` lets every player check the held item

### Death Rules

Control what happens to items when players die.

- **3 modes:** Vanilla, Keep All and Selective
- Protect single items, patterns or whole item categories
- Optional: no durability loss on death

### Usage Rules

Decide who may use an item.

- Block equipping, using or both, or only picking up in the file
- For nobody, only the soulbound owner, or players with a permission you choose
- Your own message for players who are stopped, also on the [item card](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/#item-card)

### Drop Protection

Mark items so they cannot be dropped and stay in the inventory on death, without binding them to a player.

- Mark the held item, or keep a list that marks items on pickup
- Works with the death rules and with KyuubiSoft Graveyard
- Optional "Drop Protected" tooltip line, with DynamicTooltipsLib

### Cooldowns

Make players wait between two uses of an item.

- **Items:** A duration for one item
- **ID starts:** A duration for every item whose ID starts like `Potion_`
- **Groups:** Items that wait together, each with a duration of its own
- Each player has their own timers, shown on the item card

### Watched

Keep an eye on certain items.

- Reports when an item is crafted, picked up, dropped or dropped by an NPC
- **Chat alerts** for your staff
- **Alerts** page with search and filters, up to 500 entries, also after a restart

### Inventory Tools

Look into and repair player inventories.

- **Live view** of any online player, also in other worlds
- **Automatic backups** on joining and on death, and by hand
- **History** with a comparison against the inventory now, also for offline players
- **Restore** a backup, **clear** an inventory or a slot, and **remove an item from everyone** online
- **Safety backups** before every change

### Item Overrides

Change the values of single items while the server runs, in the **Item Adjustments** window.

- Durability, stack size, quality, damage, tool speed, resistance, crafting tier and more
- The original value is always kept, and changes stay after a restart
- **Transfer** saved values to other items of the same kind

### Weapon Editor

Edit how a weapon works.

- **Interactions:** All attacks, filtered by light, charged and signature
- **Damage:** Per damage type, or all interactions at once by a percentage
- **Signature attack:** Swap it for that of another weapon
- **Properties:** Knockback, stats per hit and weapon stats

### Armor Editor

Edit armor by damage type.

- **Per damage type:** Resistance, Enhancement, KB Resistance and KB Enhancement
- **Base Resistance** and **Stat Modifiers**
- **Attack Class Enhancement** for light, charged and signature attacks

### Temporary Rules

Rules that end by themselves.

- Block crafting, unlock crafting or block usage for a set time
- Start now, in an hour or tomorrow, and extend a running rule by 30 minutes
- An optional announcement to everyone when the rule starts
- Good for weekend events and for items you need to take away quickly

### Command Blocks

Give blocks in the world a command that runs when a player hits them.

- **Edit mode:** Hit any block to open the editor
- **Placeholders:** `@p` for the player name, `@pos` for the block position
- **Run as:** Player (default), or Console with full server rights, which needs `ks.core.admin.dialog.console` to set up
- **Indestructible:** Only admins can break the block

---

## Admin Hub

One window to manage everything, opened with `/ksitem admin`:

| Group | Places |
|-------|--------|
| | **Modules** |
| **Item Rules** | **Crafting**, **Death**, **Soulbound**, **Drop Protection**, **Cooldowns**, **Usage Rules** |
| **Admin** | **Watched**, **Alerts**, **Temp Rules** |
| **Recipes and drops** | **Recipes**, **NPC/Block Drops** |
| **World** | **Inventory**, **Command Blocks**, **Item Adjustments** |

With KyuubiSoft Core installed, it also opens from the Item Control tile in the `/ksadmin` hub. See the [Admin UI](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/) page.

---

## Commands

See [Commands](https://wiki.kyuubisoft.com/hytale/item-control/commands/) for the full list.

| Command | Description | Permission |
|---------|-------------|------------|
| `/ksitem admin` | Open the Admin Hub | `ks.item.admin` + `kyuubisoft.itemcontrol.admin` |
| `/ksitem browse` | Open the Item Browser | All players |
| `/ksitem compare <item1> <item2>` | Compare two items | All players |
| `/soulbound` | Check the held item | All players |
| `/ksitem give <itemId> [--amount=<n>]` | Give yourself items | `ks.item.give` + `kyuubisoft.itemcontrol.give` |
| `/ksitem reload` | Reload the config | `ks.item.admin` + `kyuubisoft.itemcontrol.admin` |

---

## Permissions

See [Permissions](https://wiki.kyuubisoft.com/hytale/item-control/permissions/) for the full list. Admin commands check two nodes, so grant both of a pair.

| Permission | Description |
|-----------|-------------|
| `ks.item.admin` + `kyuubisoft.itemcontrol.admin` | Admin Hub and all admin commands except give and inventory tools |
| `ks.item.admin` + `kyuubisoft.itemcontrol.inventory` | Inventory commands (`/ksitem inv`) |
| `ks.item.admin.clearslot` | **Clear** and **Clear slot** in the inventory view, and `/ksitem inv clear` |
| `ks.item.admin.removeall` | **Remove item from everyone** and `/ksitem inv wipe` |
| `ks.item.give` + `kyuubisoft.itemcontrol.give` | Give items |
| `ks.core.admin.dialog.console` | Set up command blocks that run as the server console |
| `ks.item.user.browse`, `ks.item.user.compare`, `ks.item.user.soulbound` | Player commands, allowed by default |
| `kyuubisoft.itemcontrol.craft.bypass` | Bypass crafting restrictions (configurable) |
| `kyuubisoft.itemcontrol.watchlist.notify` | Receive chat alerts about watched items |

---

## Localization

**9 languages** out of the box, detected per player:

- English, German, Spanish, French, Italian
- Polish, Portuguese (BR), Russian, Turkish
- Add your own with a new JSON file

---

## Requirements

- Hytale Server 0.7.x (Update 7; version 3.0.1 is built against 0.7.0)
- Java 25.0.1
- Optional: DynamicTooltipsLib for the tooltip lines
- Optional: KyuubiSoft Core for the tile in the `/ksadmin` hub and its language settings