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

json

{
  "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:

json

{
  "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

json

{
  "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

json

{
  "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:

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

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

Container Item

json

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

Glider Item

json

{
  "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:

json

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

Interaction in Java

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

json

{
  "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

json

{
  "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

json

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

Complete Example: Magic Staff

json

{
  "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

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

Check asset path is correct
Verify manifest includes asset pack
Check for JSON syntax errors
Ensure Icon texture exists

Tool Not Working

Verify
```
Tool.Specs
```
is configured
Check
```
GatherType
```
matches block material
Ensure
```
Power
```
level is sufficient

Durability Issues

Set
```
MaxDurability
```
> 0
Configure
```
DurabilityLossPerUse
```
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.

hytale-custom-items

NPX Install

Tags

SKILL.md Content

Creating Custom Hytale Items

When to use this skill

Item Asset Structure

Basic Item Definition

Item Properties Reference

Core Properties

Visual Properties

Behavior Properties

Tool Items

Tool Spec Properties

Tool Properties

Weapon Items

Melee Weapon

Ranged Weapon

Weapon Types

Damage Types

Armor Items

Armor Slots

Armor Properties

Consumable Items

Food Item

Potion Item

Throwable Item

Special Items

Placeable Item

Container Item

Glider Item

Item Interactions

Interaction in Java

Crafting Recipes

Shaped Recipe

Shapeless Recipe

Smelting Recipe

Complete Example: Magic Staff

Item Events in Java

Troubleshooting

Item Not Appearing

Tool Not Working

Durability Issues