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.
File Location
Section titled “File Location”mods/kyuubisoft_item-control/config.jsonWhat Applies When
Section titled “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
Section titled “Module Toggles”Every module can be individually enabled or disabled. Disabled modules have zero overhead — no events are processed, no services run.
{ "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 } }}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.
Options
Section titled “Options”{ "hud-card": { "enabled": true, "showReady": true }, "temp-rules": { "strictTypes": false }}| Field | Type | Default | Description |
|---|---|---|---|
hud-card.enabled | boolean | true | Shows the 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
Section titled “Crafting Rules”{ "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 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
Section titled “Death Rules”{ "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
Section titled “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
Section titled “Usage Rules”{ "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
Section titled “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
Section titled “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
Section titled “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.