Configuration

Item Control uses a single config.json file for all settings. The configuration is hot-reloadable via /ksitem reload.

File Location

configs/kyuubisoft_itemcontrol/config.json

Module Toggles

Every module can be individually enabled or disabled. Disabled modules have zero overhead — no events are registered, no systems 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 },
    "temp-rules": { "enabled": false },
    "item-overrides": { "enabled": false },
    "command-blocks": { "enabled": false }
  }
}

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

Modules can also be toggled at runtime via the Admin Hub UI or the /ksitem module enable|disable <id> command. When a rule is added via the Admin UI while the corresponding module is disabled, the module is automatically enabled.

Crafting Rules

{
  "crafting-rules": {
    "mode": "blacklist",
    "blockedItems": ["Weapon_Legendary_Sword"],
    "bypassPermission": "kyuubisoft.itemcontrol.craft.bypass",
    "disabledRecipes": ["recipe_id_1", "recipe_id_2"]
  }
}

Field	Type	Description
`mode`	`"blacklist"` or `"whitelist"`	Whether `blockedItems` acts as a blacklist or whitelist
`blockedItems`	`string[]`	Item IDs to block (or allow in whitelist mode)
`bypassPermission`	`string`	Permission node that bypasses crafting restrictions
`disabledRecipes`	`string[]`	Recipe IDs that are disabled (hidden from crafting UI)

Death Rules

{
  "death-rules": {
    "defaultMode": "selective",
    "protectedItems": ["Quest_Reward_Amulet"],
    "protectedCategories": ["tools"],
    "preserveDurability": false,
    "permissionRules": [
      { "permission": "vip.keepitems", "mode": "keep-all" },
      { "permission": "vip.basic", "lossPercentage": 25 }
    ]
  }
}

Field	Type	Description
`defaultMode`	`"vanilla"`, `"keep-all"`, `"selective"`	Default behavior on death
`protectedItems`	`string[]`	Item IDs that are never lost (selective mode)
`protectedCategories`	`string[]`	Item categories that are never lost
`preserveDurability`	`boolean`	If true, items lose no durability on death
`permissionRules`	`object[]`	Permission-based overrides (checked in order)

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; the rest drop normally

Permission Rules

Permission rules are evaluated in order. The first matching rule applies.

mode: "keep-all" — Player keeps all items
lossPercentage: 25 — Player loses 25% of non-protected items

Soulbound

{
  "soulbound": {
    "autoSoulboundItems": ["Quest_Reward_Sword"],
    "autoSoulboundCategories": [],
    "tooltipPrefix": "Soulbound",
    "allowAdminOverride": true
  }
}

Field	Type	Description
`autoSoulboundItems`	`string[]`	Items that automatically bind on pickup
`autoSoulboundCategories`	`string[]`	Item categories that automatically bind on pickup
`tooltipPrefix`	`string`	Prefix shown in soulbound tooltip (requires DynamicTooltipsLib)
`allowAdminOverride`	`boolean`	Whether admins can unbind soulbound items

Cooldowns

{
  "cooldowns": {
    "itemCooldowns": {
      "Food_Healing_Potion": 30
    },
    "categoryCooldowns": {
      "consumable": 3
    },
    "sharedCooldownGroups": {
      "potions": ["Food_Healing_Potion", "Food_Mana_Potion"]
    }
  }
}

Field	Type	Description
`itemCooldowns`	`map<string, int>`	Per-item cooldown in seconds
`categoryCooldowns`	`map<string, int>`	Per-category cooldown in seconds
`sharedCooldownGroups`	`map<string, string[]>`	Named groups where all items share one timer

Item Watchlist

{
  "item-watchlist": {
    "watchedItems": ["Weapon_Legendary_Sword"],
    "watchedCategories": [],
    "notifyPermission": "kyuubisoft.itemcontrol.watchlist.notify",
    "logToFile": true
  }
}

Field	Type	Description
`watchedItems`	`string[]`	Item IDs to monitor
`watchedCategories`	`string[]`	Item categories to monitor
`notifyPermission`	`string`	Permission node for receiving real-time alerts
`logToFile`	`boolean`	Whether to log alerts to the SQLite database

Additional Data Files

Beyond config.json, Item Control uses several data files in the plugin directory:

File	Description
`item_overrides.json`	Persisted item stat overrides
`custom_recipes.json`	Custom recipe definitions
`drop-rules.json`	NPC and block drop rules
`soulbound_data.json`	Auto-soulbound item list
`command_blocks.json`	Command block assignments (position, command, options)
`itemcontrol.db`	SQLite database (inventory backups, watchlist alerts)

All JSON files are auto-created with defaults on first startup. The SQLite database is shared across the Inventory Tools and Watchlist modules.

Localization

Localization files are stored in configs/kyuubisoft_itemcontrol/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.

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.