Documents Hytale's item system including the Item Registry API, custom item JSON definitions, crafting recipes, custom interactions (SimpleInstantInteraction), interaction chaining (Condition, Charging, Serial, Replace), and linking interactions to items. Use when creating custom items, querying the item registry, defining crafting recipes, building item interactions, or working with ItemStack. Triggers - item, custom item, item registry, Item.getAssetMap, DefaultAssetMap, ItemStack, item JSON, item definition, crafting recipe, interaction, SimpleInstantInteraction, InteractionContext, InteractionType, item interaction, Charging, Condition, Serial, Replace, item properties, MaxStack, Categories, item ID.
Hytale Items & Interactions
Comprehensive reference for creating custom items, querying the item registry, defining crafting recipes, and building custom interactions in Hytale plugins.
Related skills: For persistent data/Codec patterns, see hytale-persistent-data. For ECS fundamentals, see hytale-ecs. For inventory management, see the Hytale inventory APIs. For entity effects applied by items, see hytale-entity-effects.
Related reference: For the canonical interaction list and trigger semantics, see the official server/interaction-reference page.
{"TranslationProperties":{"Name":"My New Item","Description":"My New Item Description"},"Id":"My_New_Item","Icon":"Icons/ItemsGenerated/my_new_item_icon.png","Model":"Items/my_new_item/model.blockymodel","Texture":"Items/my_new_item/model_texture.png","Quality":"Common","MaxStack":1,"Categories":["Items.Example"]}
Key Item Properties
Property
Type
Description
Id
String
Unique identifier for the item (used in registry lookups)
TranslationProperties.Name
String
Display name (or localization key)
TranslationProperties.Description
String
Item description (or localization key)
Icon
String
Path to inventory icon (relative to Common/)
Model
String
Path to 3D model file (relative to Common/)
Texture
String
Path to model texture (relative to Common/)
Quality
String
Item quality/rarity tier (e.g., "Common")
MaxStack
int
Maximum stack size
Categories
String[]
Tags/categories for the item
Crafting Recipes
Add a "Recipe" block to the item JSON to make it craftable:
{"TranslationProperties":{"Name":"My New Item"},"Id":"My_New_Item","Icon":"Icons/ItemsGenerated/my_new_item_icon.png","Model":"Items/my_new_item/model.blockymodel","Texture":"Items/my_new_item/model_texture.png","Quality":"Common","MaxStack":1,"Categories":["Items.Example"],"Recipe":{"TimeSeconds":3.5,"Input":[{"ItemId":"Ingredient_1","Quantity":15},{"ItemId":"Ingredient_2","Quantity":15},{"ItemId":"Ingredient_3","Quantity":15}],"BenchRequirement":[{"Id":"Workbench","Type":"Crafting","Categories":["Workbench_Survival"]}]}}
Recipe Properties
Property
Type
Description
TimeSeconds
float
Time in seconds to craft the item
Input
Array
List of ingredient items with ItemId and Quantity
BenchRequirement
Array
Required crafting station(s)
BenchRequirement[].Id
String
Bench identifier
BenchRequirement[].Type
String
Bench type (e.g., "Crafting")
BenchRequirement[].Categories
String[]
Which bench tab/category
Custom Interactions
Custom interactions define what happens when a player uses an item. They are implemented in Java and linked via JSON.
Step 1: Create the Interaction Class
Extend SimpleInstantInteraction and override firstRun:
Interactions are nestable — combine them to create complex behaviors triggered by a single item use.
Condition
Check conditions before allowing the interaction to proceed:
{"Type":"Condition","Crouching":true,"Failed":"Block_Secondary","Next":{// interaction to run if condition is met}}
Property
Type
Description
Crouching
boolean
Only proceed if player is crouching
Failed
String
Interaction type to run if condition fails
Next
Object
Interaction to run if condition passes
Charging
Require the player to hold the interaction for a duration before it activates:
{"Type":"Charging","FailsOnDamage":true,"HorizontalSpeedMultiplier":0.4,"Next":{"2.5":{// interaction after 2.5 seconds of charging}},"Failed":{// interaction to run if charging fails/cancelled}}
Property
Type
Description
FailsOnDamage
boolean
Cancel charge if player takes damage
HorizontalSpeedMultiplier
float
Movement speed multiplier while charging
Next
Object
Map of duration (seconds) → interaction
Failed
Object
Interaction if charging is interrupted
Serial
Execute a sequence of interactions in order:
{"Type":"Serial","Interactions":[{/* first interaction */},{/* second interaction */}]}
Replace
Replace the default interaction behavior (e.g., inherited from parent):
