# Configuration

# Configuration

Item Control uses one `config.json` for the module toggles, the options and the crafting, death and usage rules. The lists of the other modules (soulbound, cooldowns, watched items, drop prevention, drops, overrides, temporary rules, command blocks) live in their own data files next to it. Most of this is easier in the [Admin Hub](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/).

## File Location

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

## What Applies When

| You change | It applies |
|------------|------------|
| Anything in the Admin Hub | Right away, and it is saved |
| Rules and options in `config.json` by hand | After `/ksitem reload` or **Reload Config** |
| `modules` in `config.json` by hand | After a server restart. `/ksitem reload` does not start or stop modules. |
| A data file of another module by hand | After a server restart. Drop rules also with `/ksitem drops reload`. |

## Module Toggles

Every module can be individually enabled or disabled. Disabled modules have zero overhead — no events are processed, no services run.

```json
{
  "modules": {
    "item-browser": { "enabled": true },
    "admin-give": { "enabled": true },
    "crafting-rules": { "enabled": true },
    "death-rules": { "enabled": true },
    "usage-rules": { "enabled": true },
    "soulbound": { "enabled": false },
    "cooldowns": { "enabled": false },
    "item-watchlist": { "enabled": false },
    "inventory-tools": { "enabled": false },
    "drop-rules": { "enabled": false },
    "item-overrides": { "enabled": false },
    "temp-rules": { "enabled": false },
    "command-blocks": { "enabled": false },
    "drop-prevention": { "enabled": false }
  }
}
```

:::tip[Shorthand Syntax]
Module toggles also support shorthand: `"soulbound": true` is equivalent to `"soulbound": { "enabled": true }`.
:::

While the server runs, use the switches on the **Modules** page of the Admin Hub, or `/ksitem module enable|disable <id>`. A module that is off keeps its entries saved, and they have no effect until you turn it on again. The commands of a module only exist if it was on at server start, see [Commands](https://wiki.kyuubisoft.com/hytale/item-control/commands/).

## Options

```json
{
  "hud-card": {
    "enabled": true,
    "showReady": true
  },
  "temp-rules": {
    "strictTypes": false
  }
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `hud-card.enabled` | `boolean` | `true` | Shows the [item card](https://wiki.kyuubisoft.com/hytale/item-control/admin-ui/#item-card) above the hotbar |
| `hud-card.showReady` | `boolean` | `true` | The card also shows "ready" while a player holds an item with a cooldown |
| `temp-rules.strictTypes` | `boolean` | `false` | `false`: **Block Crafting** and **Block Usage** both block crafting and usage, as in older versions. `true`: each one only blocks its own kind. |

If an option is missing from your file, Item Control adds it with its default when it loads the file.

## Crafting Rules

```json
{
  "crafting-rules": {
    "blockedItems": ["Weapon_Legendary_Sword", "Armor_Diamond_*"],
    "blockedCategories": ["@category:Combat"],
    "disabledRecipes": ["recipe_id_1", "recipe_id_2"],
    "bypassPermission": "kyuubisoft.itemcontrol.craft.bypass"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `blockedItems` | `string[]` | Item IDs or [patterns](https://wiki.kyuubisoft.com/hytale/item-control/modules/#item-patterns) that cannot be crafted |
| `blockedCategories` | `string[]` | Item types (`@weapon`, `@armor`, `@tool`, …) or named categories (`@category:Combat`) that cannot be crafted; the leading `@` is optional |
| `disabledRecipes` | `string[]` | Recipe IDs that are disabled (hidden from crafting UI) |
| `bypassPermission` | `string` | Permission node that bypasses crafting restrictions |

The shipped file also contains `"mode": "blacklist"`. Only blacklist behaviour exists; the field has no effect.

## Death Rules

```json
{
  "death-rules": {
    "defaultMode": "selective",
    "protectedItems": ["Quest_Reward_Amulet", "Tool_*"],
    "protectedCategories": ["@tool"],
    "preserveDurability": false
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `defaultMode` | `"vanilla"`, `"keep-all"`, `"selective"` | Default behavior on death |
| `protectedItems` | `string[]` | Item IDs or patterns that are never lost (selective mode) |
| `protectedCategories` | `string[]` | Item types or named categories (same format as `blockedCategories`) that are never lost (selective mode) |
| `preserveDurability` | `boolean` | If true, items lose no durability on death |

### Death Modes

- **vanilla** — Default Hytale behavior, items drop normally
- **keep-all** — All items are kept on death
- **selective** — Only items/categories in the protected lists are kept; every other item is lost. A player's own soulbound items are always kept.

The shipped file contains an empty `permissionRules` list. Per-permission death rules are not implemented; the field is ignored.

## Usage Rules

```json
{
  "usage-rules": {
    "restrictedItems": {
      "Weapon_Legendary_Sword": {
        "action": "block-equip",
        "permission": "vip.legendary_weapons",
        "message": "Only VIPs can use this sword."
      }
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| key | `string` | Item ID or pattern |
| `action` | `"block-all"`, `"block-equip"`, `"block-use"`, `"block-pickup"` | What is blocked. Without this field the rule is `block-equip`. `block-pickup` is only available in this file. |
| `permission` | `string` | Players with this node may use the item anyway (optional). The value `owner` lets only the soulbound owner use it. Without a permission nobody may use it |
| `message` | `string` | Custom denial message (optional) |

## Drop Rules

The chance of a rule in `drop-rules.json` is a fraction from 0 to 1, so `0.5` means 50 %. `/ksitem drops add` takes the same fraction. Only the **NPC/Block Drops** window of the Admin Hub speaks percent.

## Data Files of the Other Modules

The shipped `config.json` also contains `soulbound`, `cooldowns` and `item-watchlist` sections. They are not read. These modules keep their settings in their own files:

| File | Module | Content |
|------|--------|---------|
| `soulbound_data.json` | Soulbound | Auto-soulbound list (`autoSoulbound`) |
| `soulbound_recovery.json` | Soulbound | Items waiting for `/ksitem soulbound recover` |
| `cooldowns_config.json` | Cooldowns | `itemCooldowns`, `categoryCooldowns` (ID starts) and `sharedGroups`, in seconds |
| `watchlist_config.json` | Watched | Watched items (`watchedItems`) |
| `dropprevention_data.json` | Drop Protection | Auto-protect list (`autoProtected`) |
| `drop-rules.json` | Drop Rules | NPC and block drop rules |
| `item_overrides.json` | Item Overrides | Item stat overrides |
| `custom_recipes.json` | Crafting Rules | Custom and edited recipes; edited vanilla recipes store `removeLocks`, resource-type inputs store `resourceTypeId` |
| `temp_rules.json` | Temporary Rules | Time-limited rules |
| `command_blocks.json` | Command Blocks | Command block assignments (position, command, run mode, indestructible) |
| `itemcontrol.db` | Inventory Tools, Watched | SQLite database (inventory backups, alerts) |

The files are created when a module first saves data. Prefer the Admin Hub or the commands for changes. `/ksitem reload` only reads `config.json`, the languages and the item list again, so after editing one of these files by hand, restart the server.

The permission for alerts about watched items is fixed: `kyuubisoft.itemcontrol.watchlist.notify`.

## Localization

Localization files are stored in `mods/kyuubisoft_item-control/localization/`. Each file is named by locale (e.g. `en-US.json`, `de-DE.json`). The plugin auto-detects the player's language and serves the correct translations. With KyuubiSoft Core installed, the server's default player language and the "players may choose" switch from Core apply.

To add a new language, create a new JSON file following the existing key structure. The localization version is tracked internally — when new keys are added by an update, files are automatically refreshed on next startup.