# FAQ & Troubleshooting

# FAQ & Troubleshooting

## General

### How many modules does Item Control have?

**14 modules**, each with its own switch:

| Module | ID | Default |
|--------|----|---------|
| Item Browser | `item-browser` | On |
| Admin Give | `admin-give` | On |
| Crafting Rules | `crafting-rules` | On |
| Death Rules | `death-rules` | On |
| Usage Rules | `usage-rules` | On |
| Soulbound | `soulbound` | Off |
| Cooldowns | `cooldowns` | Off |
| Watched | `item-watchlist` | Off |
| Inventory Tools | `inventory-tools` | Off |
| Drop Rules | `drop-rules` | Off |
| Temporary Rules | `temp-rules` | Off |
| Item Overrides | `item-overrides` | Off |
| Command Blocks | `command-blocks` | Off |
| Drop Protection | `drop-prevention` | Off |

### Do disabled modules affect performance?

No. A module that is off processes no events and runs no services.

### Does Item Control require KyuubiSoft Core?

No, it works on its own. With Core installed you also get:

- An Item Control tile in the `/ksadmin` hub
- The server's default player language and the "players may choose" switch
- The item card hides while the world map is open

### Does Item Control require DynamicTooltipsLib?

No. It only adds the "Soulbound" and "Drop Protected" lines to item tooltips. All protections work without it.

### What Java version is required?

Java **25.0.1**, the same as the Hytale server.

### What Hytale server version is supported?

Item Control 3.0.1 is for **Hytale 0.7.x (Update 7)** and is built against 0.7.0.

---

## Configuration

### Where is the config file located?

```
mods/kyuubisoft_item-control/config.json
```

The lists of soulbound, cooldowns, watched items, drop protection, drops, overrides, temporary rules and command blocks are in their own files in the same folder. See [Configuration](https://wiki.kyuubisoft.com/hytale/item-control/configuration/#data-files-of-the-other-modules).

### Can I reload the config without restarting the server?

Partly. `/ksitem reload` and **Reload Config** read `config.json`, the languages and the item list again. They do not start or stop modules, and they do not read the data files of the other modules. For those, restart the server. `/ksitem drops reload` reads the drop rules.

Everything you change in the Admin Hub works right away, without any of this.

### What happens if I add a rule while its module is off?

You cannot. The page of a module that is off says how many saved entries have no effect and offers **Turn on**. Older versions turned the module on by themselves, and that is gone.

### Can I use shorthand syntax in config.json?

Yes. Module toggles support both formats:

```json
{
  "modules": {
    "soulbound": true,
    "cooldowns": { "enabled": true }
  }
}
```

### How do I switch off the item card?

Set `hud-card.enabled` to `false`, or only `hud-card.showReady` to hide the "ready" card. See [Options](https://wiki.kyuubisoft.com/hytale/item-control/configuration/#options).

---

## Permissions

### I gave a moderator `ks.item.admin`, but the commands say "no permission"

Admin commands check two nodes: `ks.item.admin` and `kyuubisoft.itemcontrol.admin`. Inventory commands check `kyuubisoft.itemcontrol.inventory` instead of the second one. Grant both. See [Permissions](https://wiki.kyuubisoft.com/hytale/item-control/permissions/#admin-nodes).

### An admin cannot see "Clear", "Clear slot" or "Remove item from everyone"

These have rights of their own: `ks.item.admin.clearslot` and `ks.item.admin.removeall`. `ks.item.admin` does not include them, `ks.item.admin.*` does. Without the right the button is hidden. `/ksitem inv clear` needs `ks.item.admin.clearslot` too, and `/ksitem inv wipe` needs `ks.item.admin.removeall`. See [Clearing and Removing Items](https://wiki.kyuubisoft.com/hytale/item-control/permissions/#clearing-and-removing-items).

### The "Give Item" button is missing in the Item Browser

It needs the `admin-give` module, `ks.item.give` and `kyuubisoft.itemcontrol.give`. It is also hidden on showcase servers.

### I cannot edit or delete a command block

Blocks that run as the server console are read-only without `ks.core.admin.dialog.console`. That also covers deleting them from the list and breaking them when they are indestructible. Blocks that run as the player stay editable. See [Permissions](https://wiki.kyuubisoft.com/hytale/item-control/permissions/#command-blocks).

---

## Modules

### My cooldown group does nothing

A group only makes items wait together. It gives them no duration. Each item in the group needs a cooldown of its own, on the **Items** or **Categories** tab. **To check** on the **Modules** page lists such items.

### My cooldown "category" hits nothing

A cooldown category is the start of an item ID, such as `Potion_`, and not a game category. Upper and lower case count. The form shows the items it hits, and **Add** only works when there is at least one.

### Can I use wildcards in item IDs?

In **Crafting**, **Death**, **Soulbound**, **Drop Protection**, **Usage Rules** and in `remove` drop rules, yes: `Weapon_*`, `*_Iron`, `*Pickaxe*`, `@weapon` or `@category:<Name>`. See [Item Patterns](https://wiki.kyuubisoft.com/hytale/item-control/modules/#item-patterns).

**Cooldowns**, **Watched** and **Temp Rules** only compare exact item IDs.

### Why are soulbound items not showing tooltips?

The "Soulbound: PlayerName" line needs DynamicTooltipsLib. Without it, the server log says:

```
[ItemControl] DynamicTooltipsLib not found — soulbound tooltips disabled
```

### Can soulbound items be duplicated through containers?

No. They cannot be put into containers, "Take All" leaves them out, and a container with soulbound items in it cannot be destroyed.

### How do I recover a soulbound item that was lost?

Use `/ksitem soulbound recover`. It gets back your own lost items, 5 minutes after they were lost.

### Is there a crafting whitelist mode?

No. Every item can be crafted **except** the ones you block. To block large groups at once, use patterns such as `Weapon_*` or `@armor`, or the **Categories** tab. The `mode` field in `config.json` has no effect.

### I edited a vanilla recipe and now it can be crafted without the usual progression

Since 2.5.0 the recipe editor keeps vanilla progression locks. Recipes that were edited and saved with an older version keep their locks removed. Open such a recipe in the editor and save it with **Locks: kept**.

### How do custom recipes reach the players?

They appear in the normal crafting window next to the vanilla recipes, without a client restart.

### When do players see the announcement of a temporary rule?

When the rule becomes active. Everyone online reads it in chat, up to 30 seconds late because the server checks every 30 seconds. A rule that was already running when the server or the module started is not announced again. Temporary rules from `/ksitem temprule add` have no announcement.

### What happens when a temporary rule expires?

It removes itself. Before that it is **pending** until it starts, and **active** while it runs.

### Why does Block Crafting also block usage?

By default **Block Crafting** and **Block Usage** both block crafting and usage, as in older versions. Set [`temp-rules.strictTypes`](https://wiki.kyuubisoft.com/hytale/item-control/configuration/#options) to `true` to keep them apart.

### Do drop rules work with blocks?

Yes, with NPC kills and with breaking blocks. Block drops read the gathering setup of the game, so ores drop their real loot and not the block itself.

### My drop rule drops far too rarely or far too often

Check the unit. The window takes percent, so `0.5` there means 0.5 %. The file and `/ksitem drops add` take a fraction, so `0.5` there means 50 %.

### What are the three drop modes?

| Mode | What it does |
|------|--------------|
| `add` | Comes on top of the vanilla drops (default) |
| `replace` | Replaces all vanilla drops |
| `remove` | Takes this item away from the vanilla drops |

### How does the `*` wildcard work for drop rules?

`*` as the role applies the rule to **all NPCs**.

### Can I undo clearing an inventory?

Yes, unless you switched off **Store a backup first**. Item Control stores a [safety backup](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/#safety-backups) first. Open the player's history, choose the filter **Admin**, select the backup marked **Safety** and click **Restore**.

---

## Commands

### A command does not exist, but I turned the module on

The subcommands of a module are only created when the server starts. Restart the server after turning the module on. Its window works right away.

### Why does my command say the module is not enabled?

You turned the module off after the server started. Turn it on again on the **Modules** page of the Admin Hub, or with `/ksitem module enable <id>`.

### What is the difference between `/soulbound` and `/ksitem soulbound`?

- `/soulbound` is for **all players** and shows soulbound info of the held item.
- `/ksitem soulbound` is for admins, with bind, unbind, check, autobind and recover.

---

## Troubleshooting

### A place in the Admin Hub is greyed out

Its module is off. The place stays in the column, marked **Off**. Open it and click **Turn on**, or use the **Modules** page.

### My rule does nothing

Open the **Modules** page and look at **To check**, or use **Check item** with the item. It shows every rule that hits the item, including rules in a module that is off.

### Item values are not reaching a player after an adjustment

1. Open **Item Adjustments** and check that the value is saved. A value with **Unsaved** next to the item is still waiting for **Save**.
2. Have the player relog.
3. Check the server log for errors.

### Restoring an inventory backup is not working

1. The `inventory-tools` module must be on.
2. The player must be **online**. Offline players can only be looked at.
3. A backup that cannot be read completely cannot be restored.
4. Stacks that have no room stay in the backup, and a message says how many.

### Soulbound protection does not work yet

1. Check that the soulbound module is on.
2. Have the player relog or change worlds.
3. Check the server log for errors.

### Command blocks not responding to hits

1. The `command-blocks` module must be on.
2. The block must be in the list in **Command Blocks**.
3. Edit mode must be off for you, otherwise a hit opens the editor.
4. Check how it runs. In **Player** mode, a command the player may not use fails.

---

## Localization

### How do I add a new language?

Create a JSON file in the localization folder with the same keys as the others:

```
mods/kyuubisoft_item-control/localization/xx-XX.json
```

Copy `en-US.json` and translate the values. Item Control detects each player's language.

### What languages are included?

9 languages out of the box:

- English (`en-US`)
- German (`de-DE`)
- Spanish (`es-ES`)
- French (`fr-FR`)
- Italian (`it-IT`)
- Polish (`pl-PL`)
- Portuguese - Brazil (`pt-BR`)
- Russian (`ru-RU`)
- Turkish (`tr-TR`)

### What happens to my language files on an update?

When an update brings new texts, Item Control replaces its language files on the next start, and keeps a copy of the old one next to it as `<language>.json.backup-v<number>`. Copy your own changes back from there.