Skip to content
Hytale Modding Manual

Item Definitions

Overview

Item definitions are JSON files that describe every item in Hytale — food, weapons, tools, blocks, and more. Each file lives in a category subfolder under Assets/Server/Item/Items/ and can extend a parent template to inherit shared fields. The BlockType sub-object controls how the item looks when placed in the world.

File Location

Assets/Server/Item/Items/<Category>/<ItemId>.json

Examples:

  • Assets/Server/Item/Items/Food/Food_Bread.json
  • Assets/Server/Item/Items/Weapon/Axe/Weapon_Axe_Copper.json
  • Assets/Server/Item/Items/Tool/Pickaxe/Tool_Pickaxe_Copper.json

Schema

Top-Level Fields

FieldTypeRequiredDefaultDescription
ParentstringNo—ID of a template item to inherit fields from (e.g. "Template_Food").
TranslationPropertiesobjectYes—Localization keys for the item’s display text.
TranslationProperties.NamestringYes—Localization key for the item name (e.g. "server.items.Food_Bread.name").
TranslationProperties.DescriptionstringNo—Localization key for the item description.
QualitystringNo—Quality tier ID. One of Junk, Common, Uncommon, Rare, Epic, Legendary, Tool, Developer, Template.
IconstringNo—Path to the item icon image (e.g. "Icons/ItemsGenerated/Food_Bread.png").
Categoriesstring[]No—List of category IDs this item appears in (e.g. ["Items.Foods"]).
ItemLevelnumberNo—Item power level used by progression and crafting unlock systems.
MaxStacknumberNo—Maximum number of this item that can stack in one inventory slot.
DropOnDeathbooleanNofalseWhether this item drops when the carrying player dies.
ScalenumberNo1.0Visual scale of the item entity when dropped in the world.
InteractionsobjectNo—Maps interaction slot names (e.g. Primary, Secondary) to interaction chain IDs.
InteractionVarsobjectNo—Named interaction variable overrides. Each key is a variable name; each value has an Interactions array of inline or parent-referenced chains.
RecipeobjectNo—Crafting recipe for this item. See Recipe fields below.
BlockTypeobjectNo—Controls how the item appears when placed as a world block. See BlockType fields below.
ResourceTypesobject[]No—List of { "Id": "<ResourceTypeId>" } objects. Marks this item as belonging to resource groups used in recipes.
TagsobjectNo—Key-value tag groups (e.g. { "Type": ["Food"], "Family": ["Axe"] }). Used for filtering and interactions.
MaxDurabilitynumberNo—Maximum durability for tools and weapons.
DurabilityLossOnHitnumberNo—Durability lost per hit for weapons.
WeaponobjectNo—Marks this item as a weapon. Usually an empty object {} that activates weapon behavior.
ToolobjectNo—Tool configuration including Specs (gather power per block type) and DurabilityLossBlockTypes.
ConsumablebooleanNo—Marks this item as a consumable.
PlayerAnimationsIdstringNo—Animation set ID used when the player holds this item (e.g. "Axe", "Item").
ModelstringNo—Path to the .blockymodel file for weapon/tool held-model (e.g. "Items/Weapons/Axe/Copper.blockymodel").
TexturestringNo—Path to the texture used with Model.

BlockType Fields

FieldTypeRequiredDefaultDescription
MaterialstringNo—Physical material type. One of Solid, Fluid, Empty, Plant.
DrawTypestringNo—Rendering style. Common values: Model, Block, Plant.
OpacitystringNo—Transparency level. One of Opaque, Semitransparent, Transparent.
CustomModelstringNo—Path to the .blockymodel file used when the item is placed as a block (e.g. "Items/Consumables/Food/Bread.blockymodel").
CustomModelTextureobject[]No—Array of { "Texture": "<path>", "Weight": <number> } objects for randomized texture variants.
CustomModelScalenumberNo1.0Scale multiplier applied to the custom model.
HitboxTypestringNo—ID of the hitbox shape (e.g. "Food_Medium", "Food_Large").
RandomRotationstringNo—Rotation randomization mode applied when placed (e.g. "YawStep1").
ParticleColorstringNo—Hex color used for block break particles (e.g. "#e4cb69").
Texturesobject[]No—For placeable blocks: array of texture objects with face keys. Each entry can have All, Sides, UpDown, Top, Bottom, North, South, East, West, and a Weight for random variants.
GatheringobjectNo—Defines which gather types apply when this block is harvested or broken (Harvest, Soft, Breaking).

Recipe Fields

FieldTypeRequiredDefaultDescription
Inputobject[]Yes—Array of ingredient objects. Each has either ItemId or ResourceTypeId, plus an optional Quantity (defaults to 1).
Outputobject[]No—Array of output objects with ItemId and optional Quantity. Defaults to the item itself with quantity 1.
OutputQuantitynumberNo1Shorthand for setting output quantity when the output item is the definition’s own item.
BenchRequirementobject[]No—Array of bench requirements. Each has Type ("Crafting", "Processing", "StructuralCrafting"), Id (bench ID), and optional Categories array.
TimeSecondsnumberNo0Crafting duration in seconds.
KnowledgeRequiredbooleanNotrueWhether the player must have learned this recipe before crafting it.

Example

Assets/Server/Item/Items/Food/Food_Bread.json:

{
  "TranslationProperties": {
    "Name": "server.items.Food_Bread.name",
    "Description": "server.items.Food_Bread.description"
  },
  "Parent": "Template_Food",
  "Interactions": {
    "Secondary": "Root_Secondary_Consume_Food_T2"
  },
  "Quality": "Uncommon",
  "Icon": "Icons/ItemsGenerated/Food_Bread.png",
  "BlockType": {
    "Material": "Empty",
    "DrawType": "Model",
    "Opacity": "Semitransparent",
    "CustomModel": "Items/Consumables/Food/Bread.blockymodel",
    "CustomModelTexture": [
      {
        "Texture": "Items/Consumables/Food/Bread_Texture.png",
        "Weight": 1
      }
    ],
    "HitboxType": "Food_Medium",
    "RandomRotation": "YawStep1",
    "CustomModelScale": 0.5,
    "ParticleColor": "#e4cb69"
  },
  "InteractionVars": {
    "Consume_Charge": {
      "Interactions": [
        {
          "Parent": "Consume_Charge_Food_T1_Inner",
          "Effects": {
            "Particles": [
              {
                "SystemId": "Food_Eat",
                "Color": "#DCC15D",
                "TargetNodeName": "Mouth",
                "TargetEntityPart": "Entity"
              }
            ]
          }
        }
      ]
    },
    "Effect": {
      "Interactions": [
        {
          "Type": "ApplyEffect",
          "EffectId": "Food_Instant_Heal_Bread"
        }
      ]
    }
  },
  "Recipe": {
    "Input": [
      {
        "ItemId": "Ingredient_Dough",
        "Quantity": 1
      },
      {
        "ResourceTypeId": "Fuel",
        "Quantity": 3
      }
    ],
    "Output": [
      {
        "ItemId": "Food_Bread"
      }
    ],
    "BenchRequirement": [
      {
        "Type": "Crafting",
        "Id": "Cookingbench",
        "Categories": [
          "Baked"
        ]
      }
    ],
    "TimeSeconds": 5
  },
  "Scale": 1.5,
  "ItemLevel": 7,
  "MaxStack": 25,
  "DropOnDeath": true
}