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.

:::tip Custom Recipes 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
Recovery system — recover lost soulbound items via /ksitem soulbound recover (items have a cooldown period)
Tooltip integration — optional “Soulbound: PlayerName” indicator (requires DynamicTooltipsLib)
Standalone command — /soulbound available 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.notify permission
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)

:::warning Bulk Operations 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: Disabled

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

:::tip Safe Modifications 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. :::

Command Blocks

Module ID: command-blocks | Default: Disabled

Assign commands to specific blocks in the world. When a player hits the block, the command is executed.

Features:

Edit Mode: Toggle with /ksitem cmdblock, then hit any block to open the editor UI
Command Editor: In-game UI with text field for the command, options for indestructible and execution mode
Placeholders: @p (player name), @pos (block position as x y z)
Execution Mode: Choose per command block whether to run as Console (permission bypass) or as Player (has position/world context)
Indestructible: Mark blocks as unbreakable — only admins can destroy them
Auto-Cleanup: When a command block is broken, the assignment is automatically removed
Admin Hub Tab: View and delete all command blocks from the admin menu
JSON persistence in command_blocks.json

Use Cases:

Teleport blocks: /tp @p 100 64 200
Shop triggers: /ksshop open @p weapons
NPC spawners: npc spawn sheep (as Player for position context)
Info points: /ksinfoitem give @p welcome_book

:::info Execution Mode Use Console mode for commands that require elevated permissions (e.g., /give). Use Player mode for commands that need the player’s position or world context (e.g., npc spawn). :::