hytale-custom-items

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Custom Hytale Items

为Hytale创建自定义物品

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

物品通过插件资源包中的JSON资源进行定义：

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"]
  }
}

文件：

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

属性	类型	默认值	描述
`DisplayName`	LocalizedString	-	多语言物品名称
`Description`	LocalizedString	-	多语言物品描述
`Parent`	String	-	继承自其他物品
`Icon`	String	-	图标纹理路径
`Model`	String	-	手持物品的3D模型
`MaxStack`	Integer	64	最大堆叠数量
`MaxDurability`	Integer	0	耐久度（0表示无限）
`Categories`	Array	[]	物品分类引用
`Tags`	Object	{}	分类标签

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

属性	类型	描述
`Texture`	String	物品纹理
`Scale`	Float	模型缩放比例
`Animation`	String	物品动画集
`Particles`	String	手持时的粒子效果
`Trail`	String	挥动时的轨迹效果
`Light`	Object	发光设置

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

属性	类型	描述
`Rarity`	Enum	`Common` （普通）、 `Uncommon` （ uncommon）、 `Rare` （稀有）、 `Epic` （史诗）、 `Legendary` （传说）
`BlockId`	String	可放置物品对应的方块ID
`Interactions`	Object	交互类型映射
`CanDrop`	Boolean	是否可丢弃
`DestroyOnDeath`	Boolean	玩家死亡时是否掉落

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"]
  }
}

创建用于采集资源的工具：

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

属性	类型	描述
`GatherType`	Enum	`Pickaxe` （镐子）、 `Axe` （斧头）、 `Shovel` （铲子）、 `Hoe` （锄头）、 `Shears` （剪刀）
`Power`	Integer	采集等级
`Quality`	Integer	材料品质等级

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

属性	类型	默认值	描述
`Speed`	Float	1.0	采集速度倍率
`DurabilityLossPerUse`	Integer	1	每次采集消耗的耐久度
`Efficiency`	Float	1.0	效率倍率
`SilkTouch`	Boolean	false	是否精准采集（直接掉落方块）
`Fortune`	Integer	0	掉落倍率等级

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"]
  }
}

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

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

类型	描述
`Sword`	标准近战武器
`Axe`	重型近战武器
`Spear`	长柄近战武器
`Dagger`	快速近战武器
`Mace`	钝器近战武器
`Bow`	远程武器，需要弹药
`Crossbow`	远程武器，射速较慢
`Wand`	魔法远程武器
`Staff`	魔法远程武器
`Thrown`	投掷武器

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

类型	描述
`Physical`	默认物理伤害
`Slashing`	切割伤害
`Piercing`	穿刺伤害
`Blunt`	钝击伤害
`Fire`	火焰伤害
`Ice`	冰霜伤害
`Lightning`	雷电伤害
`Magic`	奥术伤害
`Poison`	毒素伤害
`True`	真实伤害（忽略护甲）

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"]
  }
}

创建带有防护属性的护甲：

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

部位	对应装备
`Head`	头盔
`Chest`	胸甲
`Legs`	护腿
`Feet`	靴子
`Offhand`	盾牌
`Accessory`	戒指、护身符

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

属性	类型	描述
`Defense`	Integer	基础护甲值
`Toughness`	Float	伤害减免比例
`DamageResistance`	Object	各伤害类型的减免比例
`StatModifiers`	Object	穿戴时的属性加成
`SetBonus`	Object	套装加成效果
`EquipSound`	String	穿戴时的音效
`SpecialAbility`	String	主动技能引用

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

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

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
  }
}

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

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
  }
}

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
  }
}

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

定义自定义使用行为：

json

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

Interaction in Java

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
    );
}

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

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

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

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"]
  }
}

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中的物品事件

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());
}

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

检查资源路径是否正确
验证清单文件是否包含资源包
检查JSON语法错误
确保图标纹理存在

Tool Not Working

工具无法使用

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

确认
```
Tool.Specs
```
配置正确
检查
```
GatherType
```
是否与方块材质匹配
确保
```
Power
```
等级足够

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.

设置
```
MaxDurability
```
> 0
配置
```
DurabilityLossPerUse
```
确保耐久度物品的堆叠数量为1

更多属性修改细节请参考

references/item-stats.md

。更多效果参考请查看

references/item-effects.md

。