Creating Custom Hytale Items

Complete guide for defining custom items with tools, weapons, armor, and special abilities.

When to use this skill

Use this skill when:

• Creating new item types
• Making custom weapons with stats
• Designing armor sets
• Creating tools for gathering
• Adding consumable items
• Defining item interactions
• Setting up item crafting recipes

Item Asset Structure

Items are defined as JSON assets in your plugin's asset pack:

my-plugin/
└── assets/
    └── Server/
        └── Content/
            └── Items/
                ├── my_sword.item
                ├── my_armor.item
                └── my_tool.item

Basic Item Definition

File: my_item.item

{
  "DisplayName": {
    "en-US": "Custom Item"
  },
  "Description": {
    "en-US": "A mysterious custom item"
  },
  "Icon": "MyPlugin/Icons/custom_item",
  "MaxStack": 64,
  "Categories": ["MyPlugin:Miscellaneous"],
  "Tags": {
    "Type": ["Resource"]
  }
}

Item Properties Reference

Core Properties

Property	Type	Default	Description
DisplayName	LocalizedString	-	Localized item name
Description	LocalizedString	-	Localized description
Parent	String	-	Inherit from another item
Icon	String	-	Icon texture path
Model	String	-	3D model for held item
MaxStack	Integer	64	Maximum stack size
MaxDurability	Integer	0	Durability (0 = infinite)
Categories	Array	[]	Item category references
Tags	Object	{}	Category tags

Visual Properties

Property	Type	Description
Texture	String	Item texture
Scale	Float	Model scale
Animation	String	Item animation set
Particles	String	Held particle effect
Trail	String	Swing trail effect
Light	Object	Light emission settings

Behavior Properties

Property	Type	Description
Rarity	Enum	Common, Uncommon, Rare, Epic, Legendary
BlockId	String	Block to place (for placeable items)
Interactions	Object	Interaction type mappings
CanDrop	Boolean	Can be dropped
DestroyOnDeath	Boolean	Lost on player death

Tool Items

Create tools for gathering resources:

{
  "DisplayName": { "en-US": "Mythril Pickaxe" },
  "Icon": "MyPlugin/Icons/mythril_pickaxe",
  "Model": "MyPlugin/Models/mythril_pickaxe",
  "MaxDurability": 1500,
  "Rarity": "Rare",
  "Tool": {
    "Specs": [
      {
        "GatherType": "Pickaxe",
        "Power": 5,
        "Quality": 4
      }
    ],
    "Speed": 1.5,
    "DurabilityLossPerUse": 1,
    "Efficiency": 1.2
  },
  "Tags": {
    "Type": ["Tool", "Pickaxe"]
  }
}

Tool Spec Properties

Property	Type	Description
GatherType	Enum	Pickaxe, Axe, Shovel, Hoe, Shears
Power	Integer	Mining power level
Quality	Integer	Material quality level

Tool Properties

Property	Type	Default	Description
Speed	Float	1.0	Mining speed multiplier
DurabilityLossPerUse	Integer	1	Durability cost per block
Efficiency	Float	1.0	Efficiency multiplier
SilkTouch	Boolean	false	Drop blocks directly
Fortune	Integer	0	Drop multiplier level

Weapon Items

Create melee and ranged weapons:

Melee Weapon

{
  "DisplayName": { "en-US": "Shadow Blade" },
  "Icon": "MyPlugin/Icons/shadow_blade",
  "Model": "MyPlugin/Models/shadow_blade",
  "MaxDurability": 500,
  "Rarity": "Epic",
  "Weapon": {
    "Type": "Sword",
    "AttackDamage": 12,
    "AttackSpeed": 1.6,
    "Knockback": 0.4,
    "CriticalChance": 0.15,
    "CriticalMultiplier": 1.5,
    "DurabilityLossOnHit": 1,
    "DualWield": false,
    "StatModifiers": {
      "Strength": 2,
      "Speed": 0.1
    },
    "DamageType": "Slashing",
    "Enchantable": true
  },
  "Trail": "MyPlugin/Trails/shadow_swing",
  "Animation": "MyPlugin/Animations/sword",
  "Tags": {
    "Type": ["Weapon", "Sword", "Melee"]
  }
}

Ranged Weapon

{
  "DisplayName": { "en-US": "Frost Bow" },
  "Icon": "MyPlugin/Icons/frost_bow",
  "Model": "MyPlugin/Models/frost_bow",
  "MaxDurability": 384,
  "Weapon": {
    "Type": "Bow",
    "AttackDamage": 8,
    "DrawTime": 1.0,
    "ProjectileSpeed": 3.0,
    "Projectile": "MyPlugin:FrostArrow",
    "Accuracy": 0.95,
    "AmmoType": "Hytale:Arrow",
    "InfiniteAmmo": false,
    "StatModifiers": {
      "Dexterity": 1
    }
  },
  "Animation": "MyPlugin/Animations/bow"
}

Weapon Types

Type	Description
Sword	Standard melee
Axe	Heavy melee
Spear	Long reach melee
Dagger	Fast melee
Mace	Blunt melee
Bow	Ranged, requires ammo
Crossbow	Ranged, slower
Wand	Magic ranged
Staff	Magic ranged
Thrown	Throwable weapon

Damage Types

Type	Description
Physical	Default damage
Slashing	Cutting damage
Piercing	Stabbing damage
Blunt	Impact damage
Fire	Fire damage
Ice	Cold damage
Lightning	Electric damage
Magic	Arcane damage
Poison	Toxic damage
True	Ignores armor

Armor Items

Create armor with protection stats:

{
  "DisplayName": { "en-US": "Dragon Scale Chestplate" },
  "Icon": "MyPlugin/Icons/dragon_chestplate",
  "Model": "MyPlugin/Models/dragon_chestplate",
  "MaxDurability": 528,
  "Rarity": "Legendary",
  "Armor": {
    "Slot": "Chest",
    "Defense": 8,
    "Toughness": 3,
    "DamageResistance": {
      "Fire": 0.5,
      "Physical": 0.2
    },
    "StatModifiers": {
      "Health": 20,
      "FireResistance": 50
    },
    "SetBonus": {
      "SetId": "MyPlugin:DragonScale",
      "RequiredPieces": 4,
      "Bonuses": {
        "FireImmunity": true,
        "FlyAbility": true
      }
    }
  },
  "Tags": {
    "Type": ["Armor", "Chest"]
  }
}

Armor Slots

Slot	Coverage
Head	Helmet
Chest	Chestplate
Legs	Leggings
Feet	Boots
Offhand	Shield
Accessory	Ring, Amulet

Armor Properties

Property	Type	Description
Defense	Integer	Base armor points
Toughness	Float	Damage reduction scaling
DamageResistance	Object	Per-damage-type reduction
StatModifiers	Object	Stat bonuses when worn
SetBonus	Object	Multi-piece set bonuses
EquipSound	String	Sound on equip
SpecialAbility	String	Active ability reference

Consumable Items

Create food, potions, and usable items:

Food Item

{
  "DisplayName": { "en-US": "Healing Berries" },
  "Icon": "MyPlugin/Icons/healing_berries",
  "MaxStack": 32,
  "Utility": {
    "Type": "Food",
    "ConsumeTime": 1.0,
    "Nutrition": 4,
    "Saturation": 2.5,
    "Effects": [
      {
        "Effect": "Hytale:Regeneration",
        "Duration": 10,
        "Amplifier": 1
      }
    ],
    "ConsumeSound": "Hytale/Sounds/eat",
    "ConsumeParticle": "MyPlugin/Particles/heal"
  }
}

Potion Item

{
  "DisplayName": { "en-US": "Potion of Strength" },
  "Icon": "MyPlugin/Icons/strength_potion",
  "MaxStack": 16,
  "Utility": {
    "Type": "Potion",
    "ConsumeTime": 0.5,
    "Effects": [
      {
        "Effect": "Hytale:Strength",
        "Duration": 180,
        "Amplifier": 2
      }
    ],
    "RemoveOnUse": true,
    "ReturnItem": "Hytale:EmptyBottle"
  }
}

Throwable Item

{
  "DisplayName": { "en-US": "Fire Bomb" },
  "Icon": "MyPlugin/Icons/fire_bomb",
  "MaxStack": 16,
  "Utility": {
    "Type": "Thrown",
    "ThrowSpeed": 1.5,
    "Projectile": "MyPlugin:FireBombProjectile",
    "RemoveOnUse": true,
    "Cooldown": 0.5
  }
}

Special Items

Placeable Item

{
  "DisplayName": { "en-US": "Torch" },
  "Icon": "MyPlugin/Icons/torch",
  "MaxStack": 64,
  "BlockId": "MyPlugin:TorchBlock",
  "PlaceSound": "Hytale/Sounds/place_torch"
}

Container Item

{
  "DisplayName": { "en-US": "Backpack" },
  "Icon": "MyPlugin/Icons/backpack",
  "MaxStack": 1,
  "Container": {
    "Slots": 27,
    "AllowNesting": false,
    "PickupOnBreak": true
  }
}

Glider Item

{
  "DisplayName": { "en-US": "Glider Wings" },
  "Icon": "MyPlugin/Icons/glider",
  "MaxDurability": 200,
  "Glider": {
    "GlideSpeed": 1.2,
    "FallSpeed": 0.08,
    "Maneuverability": 1.0,
    "Model": "MyPlugin/Models/glider_wings",
    "DurabilityLossPerSecond": 1
  }
}

Item Interactions

Define custom use behaviors:

{
  "Interactions": {
    "Use": "MyPlugin:MyItemUse",
    "UseOnBlock": "MyPlugin:MyItemUseOnBlock",
    "UseOnEntity": "MyPlugin:MyItemUseOnEntity",
    "Attack": "MyPlugin:MyItemAttack"
  }
}

Interaction in Java

public class MyItemInteraction extends Interaction {
    public static final BuilderCodec<MyItemInteraction> CODEC = BuilderCodec.builder(
        Codec.INT.optionalFieldOf("Power", 10)
    ).constructor(MyItemInteraction::new);
    
    private final int power;
    
    public MyItemInteraction(int power) {
        this.power = power;
    }
    
    @Override
    public InteractionResult interact(InteractionContext context) {
        // Custom interaction logic
        Player player = context.getPlayer();
        player.sendMessage("Used item with power: " + power);
        return InteractionResult.SUCCESS;
    }
}

// Register in plugin setup
@Override
protected void setup() {
    getCodecRegistry(Interaction.CODEC).register(
        "MyItemUse", 
        MyItemInteraction.class, 
        MyItemInteraction.CODEC
    );
}

Crafting Recipes

Shaped Recipe

{
  "Type": "Shaped",
  "Pattern": [
    "MMM",
    " S ",
    " S "
  ],
  "Key": {
    "M": { "Item": "MyPlugin:MythrilIngot" },
    "S": { "Item": "Hytale:Stick" }
  },
  "Result": {
    "Item": "MyPlugin:MythrilPickaxe",
    "Quantity": 1
  },
  "Category": "MyPlugin:ToolCrafting",
  "RequiredBench": "MyPlugin:Forge"
}

Shapeless Recipe

{
  "Type": "Shapeless",
  "Ingredients": [
    { "Item": "Hytale:Coal", "Quantity": 1 },
    { "Item": "Hytale:Stick", "Quantity": 1 },
    { "Item": "Hytale:GunPowder", "Quantity": 1 }
  ],
  "Result": {
    "Item": "MyPlugin:FireBomb",
    "Quantity": 4
  },
  "Category": "MyPlugin:Alchemy"
}

Smelting Recipe

{
  "Type": "Smelting",
  "Input": { "Item": "MyPlugin:RawMythril" },
  "Result": { "Item": "MyPlugin:MythrilIngot" },
  "ProcessingTime": 200,
  "Experience": 1.0,
  "RequiredBench": "Hytale:Furnace"
}

Complete Example: Magic Staff

{
  "DisplayName": {
    "en-US": "Staff of Lightning"
  },
  "Description": {
    "en-US": "Channels the power of storms"
  },
  "Icon": "MyPlugin/Icons/lightning_staff",
  "Model": "MyPlugin/Models/lightning_staff",
  "MaxStack": 1,
  "MaxDurability": 250,
  "Rarity": "Epic",
  "Weapon": {
    "Type": "Staff",
    "AttackDamage": 5,
    "AttackSpeed": 0.8,
    "DamageType": "Lightning",
    "Projectile": "MyPlugin:LightningBolt",
    "ProjectileSpeed": 5.0,
    "ManaCost": 15,
    "Cooldown": 1.5,
    "StatModifiers": {
      "Intelligence": 5,
      "MagicDamage": 0.2
    }
  },
  "Particles": "MyPlugin/Particles/electric_aura",
  "Light": {
    "Level": 5,
    "Color": { "R": 0.8, "G": 0.9, "B": 1.0 }
  },
  "Animation": "MyPlugin/Animations/staff_cast",
  "Interactions": {
    "Use": "MyPlugin:CastLightning",
    "UseCharged": "MyPlugin:CastChainLightning"
  },
  "Tags": {
    "Type": ["Weapon", "Staff", "Magic"],
    "Element": ["Lightning"]
  }
}

Item Events in Java

@Override
protected void setup() {
    // Listen for item pickup
    getEntityStoreRegistry().registerSystem(new PickupItemHandler());
    
    // Listen for item drop
    getEventRegistry().registerGlobal(DropItemEvent.class, this::onItemDrop);
    
    // Listen for item crafting
    getEventRegistry().registerGlobal(CraftRecipeEvent.class, this::onCraft);
}

private void onItemDrop(DropItemEvent event) {
    ItemStack stack = event.getItemStack();
    if (stack.getItem().getId().equals("MyPlugin:CursedItem")) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("You cannot drop this cursed item!");
    }
}

private void onCraft(CraftRecipeEvent event) {
    CraftingRecipe recipe = event.getRecipe();
    getLogger().atInfo().log("Player crafted: %s", recipe.getResult().getItem().getId());
}

Troubleshooting

Item Not Appearing

1. Check asset path is correct
2. Verify manifest includes asset pack
3. Check for JSON syntax errors
4. Ensure Icon texture exists

Tool Not Working

1. Verify Tool.Specs is configured
2. Check GatherType matches block material
3. Ensure Power level is sufficient

Durability Issues

1. Set MaxDurability > 0
2. Configure DurabilityLossPerUse
3. Check stack size is 1 for durability items

See references/item-stats.md for stat modifier details. See references/item-effects.md for effect reference.