Modules
Item Control is built around a modular architecture. Each feature is a self-contained module that can be independently enabled or disabled.
Module Management
# List all modules and their status
/ksitem module list
# Enable a module
/ksitem module enable <moduleId>
# Disable a module
/ksitem module disable <moduleId>
Item Browser
Module ID: item-browser | Default: Enabled
Browse all registered items in the game through an in-game UI.
Features:
- Search items by name with real-time filtering
- Paginated grid view with item icons
- Item detail view showing ID, level, max stack, durability, quality and categories
- Side-by-side comparison of two items
Commands:
/ksitem browse— Open the item browser/ksitem compare <item1> <item2>— Compare two items
Admin Give
Module ID: admin-give | Default: Enabled
Give any registered item to yourself or other players.
Commands:
/ksitem give <itemId> [amount]— Give an item
Permission: kyuubisoft.itemcontrol.give
Crafting Rules
Module ID: crafting-rules | Default: Enabled
Control which items can be crafted on your server. Supports both blacklist and whitelist modes.
Blacklist Mode (default): All items can be crafted except those explicitly blocked.
Whitelist Mode: Only explicitly listed items can be crafted.
Features:
- Block individual items or entire categories
- Disable specific recipe IDs
- Bypass permission for VIP/staff players
- Custom recipe creation through the admin UI
Admin UI: Available in the Admin Hub under the Recipes tab. The Custom Recipe Editor allows creating new recipes with a visual interface — select output item, crafting station, up to 4 input items, craft time and optional permission requirement.
Custom recipes are fully integrated into the game's crafting system. Players see them in their normal crafting UI alongside vanilla recipes. You can also enable/disable individual recipes through the admin hub.
Death Rules
Module ID: death-rules | Default: Enabled
Control what happens to player items when they die.
Death Modes:
| Mode | Behavior |
|---|---|
vanilla | Standard Hytale behavior — items drop on the ground |
keep-all | All items are retained in the player's inventory |
selective | Only protected items are kept, unprotected items drop |
Features:
- Protect specific items or entire categories from being lost
- Permission-based rules — different behavior per rank (e.g., VIP keeps all items, basic members lose 25%)
- Optional durability preservation on death
- Per-item and per-category configuration
Usage Rules
Module ID: usage-rules | Default: Enabled
Restrict how specific items can be used. Require permissions to equip or use certain items.
Restriction Types:
block-equip— Prevent equipping the item without permission
Features:
- Per-item permission requirements
- Custom denial messages shown to players
- Category-based restrictions
Soulbound
Module ID: soulbound | Default: Disabled
Bind items to specific players using per-instance metadata. Soulbound items cannot be dropped, traded or placed in shared containers.
Features:
- Per-instance metadata binding — owner UUID, name and timestamp stamped directly on the ItemStack (BsonDocument)
- Drop protection — soulbound items cannot be dropped by any player
- Container protection — soulbound items cannot be placed in chests; "Take All" operations are dupe-proof
- Pickup protection — other players cannot pick up items bound to someone else
- Block-break protection — containers holding soulbound items cannot be destroyed
- Auto-bind — configure items that automatically bind to the player who picks them up
- Tooltip integration — optional "Soulbound: PlayerName" indicator (requires DynamicTooltipsLib)
- Standalone command —
/soulboundavailable to all players (no admin permission) to check their held item - Admin override for manual bind/unbind
Use Cases:
- Quest items that shouldn't be tradeable
- Class-specific equipment
- Event rewards bound to the recipient
Cooldowns
Module ID: cooldowns | Default: Disabled
Add usage cooldowns to items to prevent spam or balance gameplay.
Features:
- Per-item cooldown timers
- Per-category cooldowns (e.g., all potions share a cooldown)
- Shared cooldown groups (custom groups of items sharing one cooldown)
- Real-time feedback showing remaining cooldown
- Per-player tracking
Example: Set a 30-second cooldown on health potions so players can't spam-heal during combat.
Item Watchlist
Module ID: item-watchlist | Default: Disabled
Monitor and log item movements for moderation and anti-cheat purposes.
Tracked Events:
- Item crafted
- Item picked up
- Item dropped
Features:
- Watch specific items or entire categories
- Real-time notifications to admins with
watchlist.notifypermission - Alert history with timestamps, player names and event details
- SQLite-backed storage for persistent alert logs
Use Cases:
- Monitor rare/valuable item economy
- Detect item duplication exploits
- Track quest item distribution
Inventory Tools
Module ID: inventory-tools | Default: Disabled
Advanced inventory management tools for server administrators.
Features:
- View — Inspect any player's inventory through a UI page
- Snapshot — Create named backups of player inventories
- Restore — Restore a player's inventory from a snapshot
- Wipe — Remove a specific item from all online players at once
- Clear — Clear a player's entire inventory
- History — View inventory change history with timeline
Use Cases:
- Investigate player reports about missing items
- Create pre-event inventory backups
- Emergency item removal (e.g., remove a bugged item from all players)
The wipe command affects all online players and cannot be undone. Always create snapshots before performing bulk operations.
Temporary Rules
Module ID: temp-rules | Default: Disabled
Create item restrictions that automatically expire after a set duration.
Rule Types:
| Type | Description |
|---|---|
crafting-block | Temporarily prevent crafting an item |
crafting-unlock | Temporarily allow crafting a normally blocked item |
usage-block | Temporarily prevent using an item |
Rule States:
- Pending — Rule created but not yet active
- Active — Rule is currently enforced
- Expired — Duration has passed, rule no longer enforced
Use Cases:
- Time-limited event items (craftable only during an event)
- Temporary item bans while investigating bugs
- Scheduled item releases
Drop Rules
Module ID: drop-rules | Default: Enabled
Customize NPC and block drop tables without modifying game files.
Drop Modes:
| Mode | Description |
|---|---|
add | Add extra drops alongside vanilla drops (default) |
replace | Replace all vanilla drops with custom ones |
remove | Remove specific items from vanilla drops |
Features:
- Works for both NPC kills and block breaking
- Configurable quantity ranges (min/max)
- Drop chance probability (0.0 to 1.0)
- Block drops read the vanilla gathering config — ores drop their configured loot (e.g., iron ore + basalt), not the block itself
- Wildcard support:
*applies rules to all NPCs - Persistent storage
Examples:
# Trork Warriors now drop Iron Swords with 50% chance (1-3 qty)
/ksitem drops add Trork_Warrior Weapon_Sword_Iron 1 3 0.5
# Remove iron ore from basalt ore blocks (keeps the basalt drop)
/ksitem drops add Ore_Iron_Basalt Ore_Iron 1 1 1.0 remove
# Replace all drops from a block with a custom item
/ksitem drops add Ore_Gold_Basalt Custom_Gold_Nugget 2 5 1.0 replace
Item Overrides
Module ID: item-overrides | Default: Disabled
Modify item properties at runtime without server restart. Changes are applied via client packets for immediate effect.
Editable Properties:
| Property | Type | Description |
|---|---|---|
maxDurability | int | Maximum durability |
durabilityLossOnHit | int | Durability lost per hit |
maxStack | int | Maximum stack size |
qualityId | string | Item quality identifier |
consumable | boolean | Whether item is consumable |
dropOnDeath | boolean | Whether item drops on death |
durabilityLossOnDeath | int | Durability lost on death |
toolSpeed | double | Tool mining speed |
armorResistance | double | Armor damage resistance |
craftingTier | int | Required crafting tier |
craftingOutputQty | int | Crafting output quantity |
weaponDamage | double | Weapon damage value |
Features:
- Original values are tracked and can be reset at any time
- Changes persist across server restarts
- Client-side updates applied immediately
Item overrides always track the original value. You can reset individual properties or all overrides for an item at any time with /ksitem override reset.