Skip to content
Hytale Server Modding Hytale Server Modding

Tools

Tools are utility items designed for resource gathering, farming, and world interaction. Unlike weapons, tools have specialized Tool configuration that determines their effectiveness against different block types.

Asset Location

Section titled “Asset Location”

Server Definitions: Assets/Server/Item/Items/Tool/[Category]/ Client Models: Assets/Common/Items/Tools/[Category]/

Tool Categories

Section titled “Tool Categories”

Hytale includes 13 tool categories with 48 total tool definitions:

Gathering Tools

Section titled “Gathering Tools”
CategoryFilesPurpose
Pickaxe7Mining rocks, ores, and stone blocks
Hatchet10Chopping wood and wooden structures
Shovel5Digging soil and soft ground
Shears1Harvesting plants and wool

Farming Tools

Section titled “Farming Tools”
CategoryFilesPurpose
Hoe3Tilling soil for farming
Sickle1Harvesting crops
Watering Can1Watering plants

Utility Tools

Section titled “Utility Tools”
CategoryFilesPurpose
Hammer2Cycling through block variants
Repair Kit3Repairing damaged items
Capture Crate1Capturing NPCs
Feedbag1Feeding animals
Fishing Trap1Catching fish (placeable)

Specialized

Section titled “Specialized”
CategoryFilesPurpose
Prototype1Development/testing tool
Misc5Map, Growth Potion, Sap Shunt, Trap Bait

JSON Schema Reference

Section titled “JSON Schema Reference”

Core Tool Properties

Section titled “Core Tool Properties”
FieldTypeDescription
ParentstringTemplate to inherit from
TranslationPropertiesobjectLocalization configuration
ModelstringPath to .blockymodel file
TexturestringPath to texture file
IconstringPath to inventory icon
QualitystringQuality tier
ItemLevelintegerLevel requirement
Categoriesstring[]Should include "Items.Tools"
TagsobjectType classification

Tool-Specific Properties

Section titled “Tool-Specific Properties”
FieldTypeDefaultDescription
Toolobject-Tool configuration with Specs array
Tool.Specsarray-Gathering power per block type
Tool.Speeddouble0Global tool speed modifier
Tool.DurabilityLossBlockTypesarray-Durability loss per block set
Tool.HitSoundLayerstring-Sound played when hitting a block this tool is designed to break (inherited)
Tool.IncorrectMaterialSoundLayerstring-Sound played when hitting a block this tool cannot break (inherited)
MaxDurabilitynumber100Maximum durability
PlayerAnimationsIdstring-Animation set (Pickaxe, Hoe, etc.)
Utilityobject-Utility item settings

Spec Fields

Section titled “Spec Fields”

Each entry in the Tool.Specs array has these fields:

FieldTypeDescription
GatherTypestringThe block gather type this spec applies to
PowerdoubleGathering power against this type (higher = faster)
QualityintegerQuality level of the tool for this gather type
IsIncorrectbooleanMarks this spec as using the wrong tool for the block type
HitSoundLayerstringSound played when hitting this block type (inherited)

GatherType Values

Section titled “GatherType Values”

The GatherType string references a named gather type defined in the block system. Common values seen in vanilla tools:

GatherTypeDescriptionPrimary Tool
SoftBlocksSoft blocks like plantsAll tools
SoilsDirt, sand, gravelShovel
WoodsTrees, wooden blocksHatchet
RocksStone, rock formationsPickaxe
BenchesCrafting stationsAll tools
VolcanicRocksVolcanic stonePickaxe
OresOre depositsPickaxe

Tool Specs System

Section titled “Tool Specs System”

The Tool.Specs array determines how effective a tool is against different block types. The Tool object also supports a top-level Speed modifier and sound layers for hit/incorrect feedback.

Tool Specs structure
{
  "Tool": {
    "Speed": 1.0,
    "Specs": [
      {
        "Power": 1,
        "GatherType": "SoftBlocks"
      },
      {
        "Power": 0.5,
        "Quality": 2,
        "GatherType": "Rocks",
        "HitSoundLayer": "SFX_Pickaxe_T2_Impact_Nice"
      },
      {
        "Power": 0.05,
        "GatherType": "Woods",
        "IsIncorrect": true
      }
    ],
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores", "Soil"],
        "DurabilityLossOnHit": 0.25
      }
    ]
  }
}

Power Values

Section titled “Power Values”

These are representative power values seen in vanilla tools:

PowerEffectiveness
1.0Full speed gathering
0.5Half speed (secondary use)
0.25-0.35Reduced effectiveness
0.05Minimal (wrong tool type)
0.017-0.084Very low (volcanic rocks)

Complete Tool Examples

Section titled “Complete Tool Examples”

Pickaxe (Mining Tool)

Section titled “Pickaxe (Mining Tool)”
Tool_Pickaxe_Iron.json
{
  "TranslationProperties": {
    "Name": "server.items.Tool_Pickaxe_Iron.name",
    "Description": "server.items.Tool_Pickaxe_Crude.description"
  },
  "Parent": "Tool_Pickaxe_Crude",
  "Icon": "Icons/ItemsGenerated/Tool_Pickaxe_Iron.png",
  "Quality": "Uncommon",
  "ItemLevel": 20,
  "Model": "Items/Tools/Pickaxe/Iron.blockymodel",
  "Texture": "Items/Tools/Pickaxe/Iron_Texture.png",
  "Recipe": {
    "TimeSeconds": 3.5,
    "Input": [
      { "ItemId": "Ingredient_Bar_Iron", "Quantity": 5 },
      { "ItemId": "Ingredient_Leather_Light", "Quantity": 2 },
      { "ItemId": "Ingredient_Fabric_Scrap_Linen", "Quantity": 2 }
    ],
    "BenchRequirement": [
      {
        "Id": "Workbench",
        "Type": "Crafting",
        "Categories": ["Workbench_Tools"]
      }
    ]
  },
  "Tool": {
    "Specs": [
      { "Power": 1, "GatherType": "SoftBlocks" },
      { "Power": 0.5, "GatherType": "Soils" },
      { "Power": 0.05, "GatherType": "Woods" },
      {
        "Power": 0.5,
        "GatherType": "Rocks",
        "HitSoundLayer": "SFX_Pickaxe_T2_Impact_Nice"
      },
      { "Power": 0.5, "GatherType": "Benches" },
      { "Power": 0.17, "GatherType": "VolcanicRocks" }
    ],
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores", "Soil"],
        "DurabilityLossOnHit": 0.25
      }
    ]
  },
  "MaxDurability": 250
}

Hatchet (Woodcutting Tool)

Section titled “Hatchet (Woodcutting Tool)”
Tool_Hatchet_Iron.json
{
  "TranslationProperties": {
    "Name": "server.items.Tool_Hatchet_Iron.name",
    "Description": "server.items.Tool_Hatchet_Crude.description"
  },
  "Parent": "Tool_Hatchet_Crude",
  "Icon": "Icons/ItemsGenerated/Tool_Hatchet_Iron.png",
  "Quality": "Uncommon",
  "ItemLevel": 20,
  "Model": "Items/Tools/Hatchet/Iron.blockymodel",
  "Texture": "Items/Tools/Hatchet/Iron_Texture.png",
  "Recipe": {
    "TimeSeconds": 3.5,
    "Input": [
      { "ItemId": "Ingredient_Bar_Iron", "Quantity": 5 },
      { "ItemId": "Ingredient_Leather_Light", "Quantity": 2 },
      { "ItemId": "Ingredient_Fabric_Scrap_Linen", "Quantity": 2 }
    ],
    "BenchRequirement": [
      { "Type": "Crafting", "Categories": ["Workbench_Tools"], "Id": "Workbench" }
    ]
  },
  "Tool": {
    "Specs": [
      { "Power": 1, "GatherType": "SoftBlocks" },
      { "Power": 0.05, "GatherType": "Soils" },
      {
        "Power": 0.3,
        "GatherType": "Woods",
        "HitSoundLayer": "SFX_Hatchet_T2_Impact_Nice"
      },
      { "Power": 0.05, "GatherType": "Rocks" },
      {
        "Power": 0.5,
        "GatherType": "Benches",
        "HitSoundLayer": "SFX_Hatchet_T2_Impact_Nice"
      },
      { "Power": 0.017, "GatherType": "VolcanicRocks" }
    ],
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores", "Soil"],
        "DurabilityLossOnHit": 0.25
      }
    ]
  },
  "MaxDurability": 250
}

Farming Tools

Section titled “Farming Tools”
Tool_Hoe_Crude.json
{
  "TranslationProperties": {
    "Name": "server.items.Tool_Hoe_Crude.name",
    "Description": "server.items.Tool_Hoe.description"
  },
  "Categories": ["Items.Tools"],
  "Set": "Tool_Stone",
  "Icon": "Icons/ItemsGenerated/Tool_Hoe_Crude.png",
  "Quality": "Common",
  "MaxStack": 1,
  "ItemLevel": 1,
  "Recipe": {
    "TimeSeconds": 1.5,
    "Input": [
      { "ResourceTypeId": "Wood_Trunk", "Quantity": 2 },
      { "ResourceTypeId": "Rock", "Quantity": 1 }
    ],
    "BenchRequirement": [
      { "Type": "Crafting", "Categories": ["Farming"], "Id": "Farmingbench" }
    ]
  },
  "Interactions": {
    "Primary": "Hoe_Attack",
    "Secondary": "Hoe_Till"
  },
  "InteractionVars": {
    "Hoe_Swing_Left_Effect": "Hoe_Swing_Left_Effect",
    "Hoe_Swing_Left_Damage": {
      "Interactions": [{
        "Parent": "Hoe_Swing_Left_Damage",
        "DamageCalculator": {
          "Type": "Dps",
          "BaseDamage": { "Physical": 1 }
        }
      }]
    }
  },
  "Model": "Items/Tools/Hoe/Crude.blockymodel",
  "Texture": "Items/Tools/Hoe/Crude_Texture.png",
  "MaxDurability": 100,
  "PlayerAnimationsId": "Hoe",
  "Tags": { "Type": ["Tool"] },
  "ItemSoundSetId": "ISS_Weapons_Wood"
}

Utility Tools

Section titled “Utility Tools”
Tool_Hammer_Crude.json
{
  "TranslationProperties": {
    "Name": "server.items.Tool_Hammer_Crude.name",
    "Description": "server.items.Tool_Hammer_Crude.description"
  },
  "Categories": ["Items.Tools"],
  "Icon": "Icons/ItemsGenerated/Tool_Hammer_Crude.png",
  "Quality": "Common",
  "ItemLevel": 2,
  "MaxStack": 1,
  "Set": "Tool_Stone",
  "Model": "Items/Tools/Hammer/Crude.blockymodel",
  "Texture": "Items/Tools/Hammer/Crude_Texture.png",
  "PlayerAnimationsId": "Pickaxe",
  "Recipe": {
    "TimeSeconds": 1,
    "KnowledgeRequired": false,
    "Input": [
      { "ResourceTypeId": "Rubble", "Quantity": 2 },
      { "ItemId": "Ingredient_Fibre", "Quantity": 3 },
      { "ItemId": "Ingredient_Stick", "Quantity": 3 }
    ],
    "BenchRequirement": [
      { "Id": "Workbench", "Type": "Crafting", "Categories": ["Workbench_Tools"] }
    ]
  },
  "Interactions": {
    "Primary": {
      "Interactions": [{
        "Type": "CycleBlockGroup",
        "RunTime": 0.1,
        "Effects": { "ItemAnimationId": "Mine" }
      }]
    },
    "Secondary": {
      "Interactions": [{
        "Type": "CycleBlockGroup",
        "RunTime": 0.1,
        "Effects": { "ItemAnimationId": "Mine" }
      }]
    }
  },
  "MaxDurability": 100,
  "Tags": { "Type": ["Tool"] },
  "BlockSelectorTool": {
    "DurabilityLossOnUse": 1.0
  },
  "ItemSoundSetId": "ISS_Weapons_Wood"
}

Interaction Types for Tools

Section titled “Interaction Types for Tools”

Tools use various interaction types:

TypeDescriptionUsed By
Pickaxe_AttackMining interactionPickaxes
Hoe_Attack / Hoe_TillAttack and tillHoes
Sickle_AttackCrop harvestingSickles
Watering_Can_Fill / Watering_Can_UseFill and waterWatering Cans
CycleBlockGroupRotate block variantsHammers
OpenCustomUIOpen repair UIRepair Kits
UseCaptureCrateCapture NPCsCapture Crates

Material Tiers

Section titled “Material Tiers”

Tools follow a progression through material tiers. Power values are set explicitly per spec rather than through a global modifier — higher tier tools simply define higher Power values in their Specs array.

MaterialQualityItem LevelDurability
Crude/StoneCommon1-10100-150
IronUncommon20250

Animation Sets

Section titled “Animation Sets”

Each tool type uses a specific animation set:

Animation IDTool Types
PickaxePickaxes, Hammers
HoeHoes
SickleSickles
Watering_CanWatering Cans
BlockCapture Crates, placeable tools
ItemDefault / miscellaneous

Accessing Tools in Code

Section titled “Accessing Tools in Code”
ToolExample.java
import com.hypixel.hytale.server.core.asset.type.item.config.Item;
import com.hypixel.hytale.server.core.asset.type.item.config.ItemTool;
import com.hypixel.hytale.server.core.asset.type.item.config.ItemToolSpec;


public class ToolExample {
    public void accessTools() {
        Item pickaxe = Item.getAssetMap().get("Tool_Pickaxe_Iron");


        if (pickaxe != null) {
            ItemTool toolConfig = pickaxe.getTool();
            if (toolConfig != null) {
                float speed = toolConfig.getSpeed();
                ItemToolSpec[] specs = toolConfig.getSpecs();


                for (ItemToolSpec spec : specs) {
                    String gatherType = spec.getGatherType();
                    float power = spec.getPower();
                    int quality = spec.getQuality();
                    boolean incorrect = spec.isIncorrect();
                }
            }
        }
    }
}

Creating Custom Tools

Section titled “Creating Custom Tools”

Using Parent Inheritance

Section titled “Using Parent Inheritance”
MyPlugin_Tool_Pickaxe_Custom.json
{
  "Parent": "Tool_Pickaxe_Crude",
  "TranslationProperties": {
    "Name": "server.items.MyPlugin_Tool_Pickaxe_Custom.name"
  },
  "Model": "MyPlugin/Tools/Pickaxe/Custom.blockymodel",
  "Texture": "MyPlugin/Tools/Pickaxe/Custom_Texture.png",
  "Icon": "Icons/ItemsGenerated/MyPlugin_Tool_Pickaxe_Custom.png",
  "Quality": "Rare",
  "ItemLevel": 35,
  "Tool": {
    "Specs": [
      { "Power": 1, "GatherType": "SoftBlocks" },
      { "Power": 0.6, "GatherType": "Soils" },
      { "Power": 0.1, "GatherType": "Woods" },
      {
        "Power": 0.7,
        "GatherType": "Rocks",
        "HitSoundLayer": "SFX_Pickaxe_T2_Impact_Nice"
      },
      { "Power": 0.6, "GatherType": "Benches" },
      { "Power": 0.25, "GatherType": "VolcanicRocks" }
    ],
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores", "Soil"],
        "DurabilityLossOnHit": 0.2
      }
    ]
  },
  "MaxDurability": 400,
  "Recipe": {
    "TimeSeconds": 5,
    "Input": [
      { "ItemId": "MyPlugin_Custom_Ingot", "Quantity": 5 },
      { "ItemId": "Ingredient_Leather_Light", "Quantity": 3 }
    ],
    "BenchRequirement": [
      { "Type": "Crafting", "Categories": ["Workbench_Tools"], "Id": "Workbench" }
    ]
  }
}

Creating a New Tool Type

Section titled “Creating a New Tool Type”
MyPlugin_Tool_Multitool.json
{
  "TranslationProperties": {
    "Name": "server.items.MyPlugin_Tool_Multitool.name",
    "Description": "server.items.MyPlugin_Tool_Multitool.description"
  },
  "Categories": ["Items.Tools"],
  "Model": "MyPlugin/Tools/Multitool.blockymodel",
  "Texture": "MyPlugin/Tools/Multitool_Texture.png",
  "Icon": "Icons/ItemsGenerated/MyPlugin_Tool_Multitool.png",
  "Quality": "Epic",
  "ItemLevel": 50,
  "PlayerAnimationsId": "Pickaxe",
  "Tool": {
    "Speed": 1.0,
    "Specs": [
      { "Power": 1, "GatherType": "SoftBlocks" },
      { "Power": 0.4, "Quality": 2, "GatherType": "Soils" },
      { "Power": 0.4, "Quality": 2, "GatherType": "Woods" },
      { "Power": 0.4, "Quality": 2, "GatherType": "Rocks" },
      { "Power": 0.5, "GatherType": "Benches" },
      { "Power": 0.15, "GatherType": "VolcanicRocks" }
    ],
    "DurabilityLossBlockTypes": [
      {
        "BlockSets": ["Stone", "Rock", "Ores", "Soil", "Wood"],
        "DurabilityLossOnHit": 0.35
      }
    ]
  },
  "Utility": { "Compatible": true },
  "Interactions": {
    "Primary": "Pickaxe_Attack",
    "Secondary": "Pickaxe_Attack"
  },
  "MaxDurability": 300,
  "Tags": { "Type": ["Tool"] },
  "ItemSoundSetId": "ISS_Weapons_Blunt_Small"
}

Best Practices

Section titled “Best Practices”
  1. Specialize tools: Give each tool type clear strengths against specific block types
  2. Balance power values: Higher tier materials should have progressively better power
  3. Match durability to tier: More powerful tools should last longer
  4. Use parent inheritance: Inherit from existing tools to maintain consistency
  5. Include appropriate sounds: Use HitSoundLayer for satisfying feedback
  6. Set correct categories: Always include "Items.Tools" in categories
  7. Prefix IDs: Use plugin name prefix for all custom tools
Section titled “Related”