Skip to main content

FAQ & Troubleshooting

General​

How many modules does Item Control have?​

Item Control includes 13 modules (12 feature modules plus admin give):

ModuleIDDefault
Item Browseritem-browserEnabled
Admin Giveadmin-giveEnabled
Crafting Rulescrafting-rulesEnabled
Death Rulesdeath-rulesEnabled
Usage Rulesusage-rulesEnabled
SoulboundsoulboundDisabled
CooldownscooldownsDisabled
Item Watchlistitem-watchlistDisabled
Inventory Toolsinventory-toolsDisabled
Drop Rulesdrop-rulesDisabled
Temp Rulestemp-rulesDisabled
Item Overridesitem-overridesDisabled
Command Blockscommand-blocksDisabled

Do disabled modules affect performance?​

No. Disabled modules have zero overhead. While ECS systems are registered at startup for all modules, the enabled flag controls whether events are actually processed. No listeners fire, no services run, no memory is consumed by disabled modules.

Does Item Control require KyuubiSoft Core?​

No. Item Control works fully standalone. KyuubiSoft Core is an optional soft dependency that provides:

  • Admin menu integration (Item Control appears in /ksadmin)
  • Per-player language detection
  • Player avatar display in inventory view

Does Item Control require DynamicTooltipsLib?​

No. DynamicTooltipsLib is an optional soft dependency used only for soulbound tooltip display. Without it, soulbound items work normally but the "Soulbound: PlayerName" tooltip line is not shown. All other soulbound protections (drop, pickup, container, block-break) work without it.

What Java version is required?​

Java 25.0.1 is required, matching the Hytale Server runtime.

What Hytale server version is supported?​

Item Control requires Hytale Server Update 3 or later. The Item HUD overlay features (restricted/cooldown badges) use the Update 4 ItemHudUI system with graceful degradation on pre-Update 4 servers.

Configuration​

Where is the config file located?​

configs/kyuubisoft_itemcontrol/config.json

Additional data files in the same directory:

  • item_overrides.json -- 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
  • itemcontrol.db -- SQLite database (inventory backups, watchlist alerts)

Can I reload the config without restarting the server?​

Yes. Use /ksitem reload to hot-reload the config, localization files, and item registry. Module enable/disable changes also take effect immediately via the Admin Hub UI or /ksitem module enable|disable <id>.

What happens if I add a rule via the Admin UI while the module is disabled?​

The module is automatically enabled when a rule is added through the Admin Hub. For example, adding a crafting blacklist entry while the crafting-rules module is disabled will enable the module.

Can I use shorthand syntax in config.json?​

Yes. Module toggles support both formats:

{
  "modules": {
    "soulbound": true,
    "cooldowns": { "enabled": true }
  }
}

Modules​

Why are soulbound items not showing tooltips?​

The soulbound tooltip ("Soulbound: PlayerName") requires DynamicTooltipsLib as an optional dependency. Install it alongside Item Control for tooltip support. The server log will show:

[ItemControl] DynamicTooltipsLib not found — soulbound tooltips disabled

if the library is not present.

Can soulbound items be duplicated through container exploits?​

No. The soulbound system includes comprehensive dupe protection:

  • Container guard with full transaction support (Move, ItemStack, List transactions)
  • Re-entrancy guard preventing server freezes
  • "Take All" protection -- soulbound items are excluded from bulk container operations
  • Block-break protection -- containers holding soulbound items cannot be destroyed

How do I recover a soulbound item that was lost?​

The soulbound module includes a recovery system. Use the admin command:

/ksitem soulbound recover

This recovers soulbound items that were lost due to edge cases. Items have a cooldown period before they can be recovered.

What is the difference between crafting blacklist and whitelist mode?​

  • Blacklist mode (default): All items can be crafted except those explicitly listed in blockedItems
  • Whitelist mode: Only items listed in blockedItems can be crafted; everything else is blocked

How do custom recipes work with the client?​

Custom recipes are fully integrated into the game's crafting system. They are synced to clients via UpdateRecipes packets and appear in the normal crafting UI alongside vanilla recipes. No client restart is needed -- recipes register immediately.

What happens when a temporary rule expires?​

Temporary rules automatically remove themselves when the timer runs out. The rule transitions through three states:

  1. Pending -- Created but not yet active (for scheduled rules)
  2. Active -- Currently enforced
  3. Expired -- Duration has passed, rule is no longer enforced

Do drop rules work with blocks?​

Yes. Drop Rules support both NPC kills and block breaking. Block drops read the vanilla BlockGathering config to determine correct drops (e.g., iron ore blocks drop iron ore items, not the block itself).

What are the three drop modes?​

ModeDescription
addAdd extra drops alongside vanilla drops (default)
replaceReplace all vanilla drops with your custom drops
removeRemove specific items from vanilla drops

How does the * wildcard work for drop rules?​

Using * as the NPC role ID applies the rule to all NPCs. This is useful for global drop modifications.

Commands​

What is the difference between /soulbound and /ksitem soulbound?​

  • /soulbound -- Standalone command available to all players (no permission required). Shows soulbound info of the held item.
  • /ksitem soulbound -- Admin command requiring kyuubisoft.itemcontrol.admin. Provides bind, unbind, check, autobind, and recover subcommands.

Why does my command say "Module not enabled"?​

Most commands require their corresponding module to be enabled. Enable the module first:

/ksitem module enable <moduleId>

For example, to use cooldown commands: /ksitem module enable cooldowns

Can I use wildcards in item IDs?​

Yes. Crafting rules, death protection, and usage restrictions support wildcard patterns. For example, Weapon_* matches all items starting with "Weapon_".

Troubleshooting​

"JsonPrimitive cannot be cast to JsonObject" error on startup​

This was a known issue fixed in v2.0.0. The config parser now accepts both shorthand ("module": true) and object ("module": { "enabled": true }) formats. Update to the latest version.

Admin Hub tabs are missing​

Tabs only appear for enabled modules. If you don't see the Soulbound tab, for example, enable the module first:

/ksitem module enable soulbound

Items are not syncing to clients after an override​

Item overrides are synced via UpdateItems packets. If changes don't appear immediately:

  1. Verify the override was applied: /ksitem override get <itemId>
  2. Have the player relog -- overrides are re-synced on connect
  3. Check the server log for errors

Inventory backup restore is not working​

Ensure:

  1. The inventory-tools module is enabled
  2. The target player is online (restore requires an active player session)
  3. A backup exists for the player (check with /ksitem inv history [player])

Soulbound container guard not activating​

The container guard registers on AddPlayerToWorldEvent, which fires on connect and world change. If the guard is not active:

  1. Check that the soulbound module is enabled
  2. Have the player relog or change worlds
  3. Check the server log for "Soulbound guard: player ref still null" warnings -- this indicates a timing issue that resolves after retries

Command blocks not responding to hits​

  1. Ensure the command-blocks module is enabled
  2. Verify the block has an assigned command (check in Admin Hub > Cmd Blocks tab)
  3. Check execution mode -- Console mode runs with elevated permissions, Player mode runs with the player's context

Localization​

How do I add a new language?​

Create a new JSON file in the localization directory following the existing key structure:

configs/kyuubisoft_itemcontrol/localization/xx-XX.json

Copy an existing file (e.g., en-US.json) and translate all values. The plugin auto-detects the player's language and serves the correct translations.

What languages are included?​

9 languages out of the box:

  • English (en-US)
  • German (de-DE)
  • Spanish (es-ES)
  • French (fr-FR)
  • Italian (it-IT)
  • Polish (pl-PL)
  • Portuguese - Brazil (pt-BR)
  • Russian (ru-RU)
  • Turkish (tr-TR)

Are new localization keys added automatically?​

Yes. The localization version is tracked internally. When new keys are added by an update, files are automatically refreshed on next startup with missing keys merged from defaults.