Agent-Skills.md

Agent Skills: Creating Custom Hytale Items

Create custom items for Hytale including tools, weapons, armor, consumables, and special items. Use when asked to "add a custom item", "create a weapon", "make armor", "add a tool", or "create consumable items".

UncategorizedID: mnkyarts/hytale-skills/hytale-custom-items

Repository

mnkyarts/hytale-skills
MnkyArtsLicense: MIT
3

Install this agent skill to your local

pnpm dlx add-skill https://github.com/MnkyArts/hytale-skills/tree/HEAD/skills/hytale-custom-items

Skill Files

Browse the full folder contents for hytale-custom-items.

Download Skill

Loading file tree…

skills/hytale-custom-items/SKILL.md

Skill Metadata

Name
hytale-custom-items
Description
Create custom items for Hytale including tools, weapons, armor, consumables, and special items. Use when asked to "add a custom item", "create a weapon", "make armor", "add a tool", or "create consumable items".

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.