Configuration

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

File Location

plugins/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 }
  }
}

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"],
    "allowAdminOverride": true
  }
}

Field	Type	Description
autoSoulboundItems	string[]	Items that automatically bind on pickup
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"],
    "logToFile": true
  }
}

Field	Type	Description
watchedItems	string[]	Item IDs to monitor
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
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 plugins/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.