Adding Items

Basics

Items are JSON files that define visual appearance, behavior bindings, and properties.

Pack location: Server/Item/Items/
Base game reference: Assets.zip/Server/Item/Items/

Minimal Item

Create Server/Item/Items/Weapon/My_Sword.json in your pack:

{
  "TranslationProperties": { "Name": "My Item" },
  "Model": "Items/Weapons/Sword/Iron.blockymodel",
  "Texture": "Items/Weapons/Sword/Iron_Texture.png",
  "Icon": "Icons/ItemsGenerated/Weapon_Sword_Iron.png"
}

The asset ID becomes My_Sword (filename without .json).

Using Inheritance

Most items should inherit from a base game template:

{
  "Parent": "Template_Weapon_Sword",
  "TranslationProperties": { "Name": "Flaming Sword" },
  "Model": "Items/Weapons/Sword/Iron.blockymodel",
  "Texture": "Items/Weapons/Sword/Iron_Texture.png",
  "Icon": "Icons/ItemsGenerated/Weapon_Sword_Iron.png"
}

This inherits all interactions, animations, and properties from the template.

Common templates (in base game Server/Item/Items/Weapon/):

• Template_Weapon_Sword - One-handed sword
• Template_Weapon_Battleaxe - Two-handed axe
• Template_Weapon_Daggers - Dual daggers
• Template_Weapon_Bow - Bow
• Template_Weapon_Crossbow - Crossbow

Customizing Damage

Use InteractionVars to override damage without changing the attack chain:

{
  "Parent": "Template_Weapon_Sword",
  "InteractionVars": {
    "Swing_Left_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Left_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 25, "Fire": 10 }
        }
      }]
    },
    "Swing_Right_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Right_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 25, "Fire": 10 }
        }
      }]
    },
    "Swing_Down_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Down_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 40, "Fire": 20 }
        }
      }]
    }
  }
}

Finding Var names: Look at the weapon’s interaction chain in base game. Search for "Var": in:

• Assets.zip/Server/Item/Interactions/Weapons/Sword/

Adding Passive Stats

Weapons can grant stat bonuses while held:

{
  "Parent": "Template_Weapon_Sword",
  "Weapon": {
    "StatModifiers": {
      "MaxHealth": [{ "Amount": 50, "CalculationType": "Additive" }],
      "MovementSpeed": [{ "Amount": 0.15, "CalculationType": "Multiplicative" }],
      "SignatureEnergy": [{ "Amount": 30, "CalculationType": "Additive" }]
    }
  }
}

CalculationType:

• Additive - Add flat amount
• Multiplicative - Multiply by (1 + Amount)

Custom Interactions

To use completely different attacks, override Interactions:

{
  "Parent": "Template_Weapon_Sword",
  "Interactions": {
    "Primary": "My_Custom_Attack",
    "Secondary": "My_Custom_Block",
    "Ability1": "My_Custom_Ultimate"
  }
}

See adding-interactions.md for creating custom interactions.

Item Properties

Quality (Rarity)

{
  "Quality": "Legendary"
}

Values: Common, Uncommon, Rare, Epic, Legendary, Technical

Defined in base game: Assets.zip/Server/Item/Qualities/

Stack Size

{
  "MaxStack": 64
}

Categories (for UI)

{
  "Categories": ["Items.Weapons", "Items.Melee"]
}

Tags

{
  "Tags": {
    "Type": ["Weapon"],
    "Family": ["Sword"],
    "Element": ["Fire"]
  }
}

Visual Effects on Item

Particles (ambient)

{
  "Particles": [
    {
      "SystemId": "Fire_Aura",
      "TargetNodeName": "Handle"
    }
  ]
}

Light emission

{
  "Light": {
    "Color": "#ff4400",
    "Intensity": 2.0
  }
}

Model VFX (glow/highlight)

{
  "ModelVfx": "Sword_Signature_Status"
}

References in base game: Assets.zip/Server/Entity/ModelVFX/

Complete Example: Fire Sword

Server/Item/Items/Weapon/Weapon_Sword_Fire.json:

{
  "Parent": "Template_Weapon_Sword",

  "TranslationProperties": {
    "Name": "Blazing Edge"
  },

  "Model": "Items/Weapons/Sword/Iron.blockymodel",
  "Texture": "Items/Weapons/Sword/Iron_Texture.png",
  "Icon": "Icons/ItemsGenerated/Weapon_Sword_Iron.png",

  "Quality": "Epic",

  "InteractionVars": {
    "Swing_Left_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Left_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 15, "Fire": 20 },
          "CriticalHitChance": 0.2,
          "CriticalHitMultiplier": 2.0
        },
        "DamageEffects": {
          "Knockback": { "Force": 8.0 },
          "WorldParticles": [{ "SystemId": "Impact_Fire" }]
        }
      }]
    },
    "Swing_Right_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Right_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 15, "Fire": 20 }
        }
      }]
    },
    "Swing_Down_Damage": {
      "Interactions": [{
        "Parent": "Weapon_Sword_Primary_Swing_Down_Damage",
        "DamageCalculator": {
          "BaseDamage": { "Physical": 25, "Fire": 35 }
        },
        "DamageEffects": {
          "WorldParticles": [{ "SystemId": "Explosion_Fire_Small" }]
        }
      }]
    }
  },

  "Weapon": {
    "StatModifiers": {
      "MaxHealth": [{ "Amount": 20, "CalculationType": "Additive" }]
    }
  },

  "Particles": [
    { "SystemId": "Fire_Embers", "TargetNodeName": "Blade_Tip" }
  ],

  "Light": {
    "Color": "#ff6600",
    "Intensity": 1.5
  }
}

Complete Example: Simple Gun

Server/Item/Items/Weapon/Weapon_Pistol.json:

{
  "TranslationProperties": { "Name": "Pistol" },

  "Model": "Items/Hypixel/Minigames/GunPvP/Weapons/Handguns/Handgun.blockymodel",
  "Texture": "Items/Hypixel/Minigames/GunPvP/Weapons/Handguns/Handgun_Texture.png",
  "Icon": "Icons/ItemsGenerated/Weapon_Handgun.png",

  "PlayerAnimationsId": "Handgun",

  "Interactions": {
    "Primary": {
      "Cooldown": { "Id": "Shoot", "Cooldown": 0.3 },
      "Interactions": [{
        "Type": "LaunchProjectile",
        "ProjectileId": "My_Bullet",
        "RunTime": 0.1,
        "Effects": {
          "ItemAnimationId": "Shoot",
          "WorldSoundEventId": "SFX_Rifle_Fire",
          "CameraEffect": "Handgun_Shoot"
        }
      }]
    },
    "Secondary": "Gun_Attack"
  },

  "Quality": "Rare",
  "Weapon": {}
}

Crafting Recipes

Items can embed a recipe directly in their JSON:

{
  "Parent": "Template_Weapon_Sword",
  "Recipe": {
    "Input": [
      { "ItemId": "hytale:iron_ingot", "Quantity": 3 },
      { "ItemId": "hytale:wood_stick", "Quantity": 2 }
    ],
    "BenchRequirement": [{ "Type": "Crafting", "Id": "Anvil" }]
  }
}

Embedded recipes are auto-generated as "{itemId}_Recipe_Generated_0" at load time. You can also define recipes as standalone files in Server/Item/Recipes/. See Adding Recipes for the full recipe format and bench types, or Crafting & Recipes for runtime management and events.

File Checklist

When adding an item, ensure these exist:

• Item JSON in your pack’s Server/Item/Items/
• Model .blockymodel in Common/Items/ (or use base game model)
• Texture .png in Common/Items/ (or use base game texture)
• Icon .png in Common/Icons/ (or use base game icon)
• (Optional) Custom interactions in Server/Item/Interactions/
• (Optional) Custom projectiles in Server/Projectiles/
• (Optional) Crafting recipe in Server/Item/Recipes/ or embedded Recipe field

File Locations

What	Your Pack	Base Game Reference
Item definitions	Server/Item/Items/	Assets.zip/Server/Item/Items/
Item templates	(inherit from base)	Assets.zip/Server/Item/Items/Weapon/Template_*
Models	Common/Items/	Assets.zip/Common/Items/
Textures	Common/Items/	Assets.zip/Common/Items/
Icons	Common/Icons/	Assets.zip/Common/Icons/
Interactions	Server/Item/Interactions/	Assets.zip/Server/Item/Interactions/