Skip to content

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.

mods/kyuubisoft_item-control/config.json
You changeIt applies
Anything in the Admin HubRight away, and it is saved
Rules and options in config.json by handAfter /ksitem reload or Reload Config
modules in config.json by handAfter a server restart. /ksitem reload does not start or stop modules.
A data file of another module by handAfter a server restart. Drop rules also with /ksitem drops reload.

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.

{
"hud-card": {
"enabled": true,
"showReady": true
},
"temp-rules": {
"strictTypes": false
}
}
FieldTypeDefaultDescription
hud-card.enabledbooleantrueShows the item card above the hotbar
hud-card.showReadybooleantrueThe card also shows “ready” while a player holds an item with a cooldown
temp-rules.strictTypesbooleanfalsefalse: 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": {
"blockedItems": ["Weapon_Legendary_Sword", "Armor_Diamond_*"],
"blockedCategories": ["@category:Combat"],
"disabledRecipes": ["recipe_id_1", "recipe_id_2"],
"bypassPermission": "kyuubisoft.itemcontrol.craft.bypass"
}
}
FieldTypeDescription
blockedItemsstring[]Item IDs or patterns that cannot be crafted
blockedCategoriesstring[]Item types (@weapon, @armor, @tool, …) or named categories (@category:Combat) that cannot be crafted; the leading @ is optional
disabledRecipesstring[]Recipe IDs that are disabled (hidden from crafting UI)
bypassPermissionstringPermission node that bypasses crafting restrictions

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

{
"death-rules": {
"defaultMode": "selective",
"protectedItems": ["Quest_Reward_Amulet", "Tool_*"],
"protectedCategories": ["@tool"],
"preserveDurability": false
}
}
FieldTypeDescription
defaultMode"vanilla", "keep-all", "selective"Default behavior on death
protectedItemsstring[]Item IDs or patterns that are never lost (selective mode)
protectedCategoriesstring[]Item types or named categories (same format as blockedCategories) that are never lost (selective mode)
preserveDurabilitybooleanIf true, items lose no durability on death
  • 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": {
"restrictedItems": {
"Weapon_Legendary_Sword": {
"action": "block-equip",
"permission": "vip.legendary_weapons",
"message": "Only VIPs can use this sword."
}
}
}
}
FieldTypeDescription
keystringItem 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.
permissionstringPlayers 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
messagestringCustom denial message (optional)

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.

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:

FileModuleContent
soulbound_data.jsonSoulboundAuto-soulbound list (autoSoulbound)
soulbound_recovery.jsonSoulboundItems waiting for /ksitem soulbound recover
cooldowns_config.jsonCooldownsitemCooldowns, categoryCooldowns (ID starts) and sharedGroups, in seconds
watchlist_config.jsonWatchedWatched items (watchedItems)
dropprevention_data.jsonDrop ProtectionAuto-protect list (autoProtected)
drop-rules.jsonDrop RulesNPC and block drop rules
item_overrides.jsonItem OverridesItem stat overrides
custom_recipes.jsonCrafting RulesCustom and edited recipes; edited vanilla recipes store removeLocks, resource-type inputs store resourceTypeId
temp_rules.jsonTemporary RulesTime-limited rules
command_blocks.jsonCommand BlocksCommand block assignments (position, command, run mode, indestructible)
itemcontrol.dbInventory Tools, WatchedSQLite 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 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.