主题

自定义基础物品 ​

开发者可以通过在 addon 中配置 JSON 来添加自定义物品。自定义物品支持 ModAPI 中与物品相关的所有事件及接口。本文将介绍自定义物品的完整注册流程、行为包与资源包的配置方式，以及各组件的详细用法。

前置条件

本功能基于 format_version: 1.10，不需要开启实验性玩法。在开始之前，请确保你已经阅读了 自定义游戏内容概述，并准备好行为包与资源包的基础目录结构。

概述 ​

自定义物品是我的世界中国版 addon 系统中最基础的自定义内容之一。你可以通过编写 JSON 定义文件，向游戏中注册全新的物品，包括食物、材料、工具原料等。

自定义物品的核心思路是 数据驱动：你在 JSON 中通过 components（组件）声明物品的属性和行为，引擎会在运行时读取并应用这些配置。同时，自定义物品也完全兼容 Python Mod SDK 的事件与接口，可以实现更复杂的逻辑。

自定义物品支持以下能力：

  • 自定义贴图、名称、堆叠数、耐久度
  • 设置为食物、种子、燃料等功能性物品
  • 作为自定义配方的材料或产出
  • 在掉落表（loot_table）和村民交易中使用
  • 通过 custom_item_type 扩展为武器、盔甲、生物蛋等特殊类型

组件事件流程 ​

当玩家与自定义物品交互时（如右键使用、攻击等），引擎会按照固定顺序触发一系列事件。下面是简化的事件流程：

玩家右键使用物品
  │
  ├─ ClientItemTryUseEvent（客户端尝试使用）
  │
  ├─ ServerItemTryUseEvent（服务端尝试使用）
  │
  ├─ ActorUseItemClientEvent（客户端使用）
  │
  ├─ ActorUseItemServerEvent（服务端使用）
  │
  └─ 使用完成 / 被打断

事件顺序说明

ActorUseItemClientEvent（ActorUseItemServerEvent）与 ClientItemTryUseEvent（ServerItemTryUseEvent）的先后顺序与使用的物品类型有关。食物类物品的 TryUse 会在 UseItem 之前触发，而其他类型的物品可能顺序相反。建议在脚本中通过实际测试确认你所关心的事件顺序。

注册流程 ​

注册一个自定义物品需要 6 个步骤，涉及行为包和资源包两侧的配置：

步骤操作所在目录
1在行为包中创建 netease_items_beh/ 目录，编写物品定义 JSON行为包
2将物品贴图放入 textures/items/资源包
3在 textures/item_texture.json 中配置资源名与贴图的映射资源包
4在资源包中创建 netease_items_res/ 目录，编写物品表现 JSON资源包
5在 texts/zh_CN.lang 中配置物品的中文名称资源包
6进入游戏测试，通过创造模式或 /give 指令获取物品—

下面按照这个流程，逐步详细说明每一步的配置内容。

行为包配置（netease_items_beh） ​

在行为包根目录下新建 netease_items_beh/ 文件夹，然后在其中创建物品定义 JSON 文件。文件名可以自由命名（建议与物品名一致），但扩展名必须是 .json。

JSON 中至少有一个 component

行为包中的物品 JSON 必须包含至少一个组件，否则引擎会报错。如果你的物品不需要任何特殊属性，可以只写一个 minecraft:max_stack_size。

下面是一个最小化的物品定义：

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:basic_gem",
      "category": "items"
    },
    "components": {
      "minecraft:max_stack_size": 64
    }
  }
}

description 字段 ​

description 是物品的元数据描述，包含标识符、分类等信息。

键类型默认值说明
identifierstr—物品的唯一标识符，格式为 命名空间:物品名。由小写字母和下划线组成，禁止使用大写字母。命名空间建议与 mod 名称一致，identifier 必须全局唯一
categorystritems注册分类，决定物品在创造模式物品栏的位置。可选值见下方说明
custom_item_typestr—自定义物品类别，用于扩展特殊功能。不填则为普通物品

category 可选值：

值说明
construction注册到"建筑"分页
equipment注册到"装备"分页
items注册到"物品"分页（默认）
nature注册到"自然"分页
commands只能通过指令和 API 获取，不在创造物品栏显示
none只能通过 API 获取，指令也无法获取
自定义分页名称注册到自定义物品分页中

custom_item_type 可选值：

值说明详细文档
weapon武器/工具，需搭配 netease:weapon 组件自定义武器与工具
armor盔甲，需搭配 netease:armor 组件自定义盔甲
egg生物蛋，需搭配 netease:egg 组件其他特殊物品
ranged_weapon远程武器/蓄力物品自定义远程武器
bucket桶，需搭配 netease:bucket 组件其他特殊物品
projectile_item抛射物物品，需搭配 netease:projectile 组件其他特殊物品
shield盾牌，需搭配 netease:shield 组件其他特殊物品

identifier 命名规范

  • 必须使用 命名空间:物品名 的格式，如 mymod:ruby
  • 只能包含小写字母（a-z）、数字（0-9）和下划线（_）
  • 命名空间不要使用 minecraft，避免与原版冲突
  • identifier 必须在整个游戏中全局唯一（不同 mod 之间也不能重复）

原版组件（minecraft: components） ​

原版组件是以 minecraft: 为前缀的组件，定义物品的基础属性。以下是中国版支持的原版物品组件。

minecraft:max_stack_size ​

设置物品的最大堆叠数量。该值不能超过 64。

json
"minecraft:max_stack_size": 16

minecraft:max_damage ​

设置物品的耐久度上限，范围为 [0, 32767]。设置后物品会显示耐久条。

json
"minecraft:max_damage": 1561

堆叠与耐久的关系

若物品的堆叠数量大于 1，耐久度变化对整一叠物品生效。耐久度为 0 后，每次消耗耐久的行为会使数量减 1。

minecraft:hand_equipped ​

设为 true 时，物品会以竖直方式握在手中（类似武器的持握方式），而非平放。

json
"minecraft:hand_equipped": true

minecraft:foil ​

设为 true 时，物品会显示附魔光效（类似附魔物品的紫色闪烁）。

json
"minecraft:foil": true

minecraft:use_duration ​

设置物品的最大使用时长（单位：tick，20 tick = 1 秒）。用于食物的食用时长、蓄力物品的最大蓄力时间等。该值也决定 MoLang 变量 query.item_remaining_use_duration 和 variable.item_use_normalized 的值。

json
"minecraft:use_duration": 32

minecraft:food ​

将物品设为食物。详见下方完整示例部分。

字段类型说明
nutritionint营养值（恢复的饥饿值）
saturation_modifierstr饱和度等级：poor(0.1)、low(0.3)、normal(0.6)、good(0.8)、max(1.0)、supernatural(1.2)
can_always_eatbool是否可以在饥饿值满时食用
using_converts_tostr食用后转化为的物品（如 bowl）
cooldown_typestr冷却类型，同类型食物共享冷却
cooldown_timeint冷却时间（秒）
effectsarray食用后附加的状态效果列表
json
"minecraft:food": {
  "nutrition": 4,
  "saturation_modifier": "low",
  "can_always_eat": false,
  "effects": [
    {
      "name": "regeneration",
      "chance": 1.0,
      "duration": 30,
      "amplifier": 1
    }
  ]
}

饱和度计算公式

食物恢复的饱和度 = 营养值 x 饱和度系数 x 2。饱和度最大不超过当前饥饿值。饱和度是隐藏数值，玩家的行动会先消耗饱和度，耗尽后才开始消耗饥饿值。

minecraft:seed ​

设置物品的农作物属性，使其可以种植在特定方块上。

字段类型说明
crop_resultstr种植后放置出的方块
plant_atarray(str)可被种植的方块列表
json
"minecraft:seed": {
  "crop_result": "sweet_berry_bush",
  "plant_at": ["grass", "dirt", "podzol"]
}

plant_at 格式一致性

plant_at 列表中的方块名称需要保持格式一致，例如统一使用 ["minecraft:grass", "minecraft:dirt"] 或统一使用 ["grass", "dirt"]，不要混用。否则在相邻自定义农作物旁种植新的农作物时，可能导致上一个农作物被破坏。

minecraft:stacked_by_data ​

设置不同 aux 值（数据值）的物品是否能堆叠在一起。设为 true 时，不同 aux 值的物品无法堆叠，且在合成配方中会被识别为不同的原料。

json
"minecraft:stacked_by_data": true

与耐久度组件互斥

minecraft:stacked_by_data 无法与 minecraft:max_damage（耐久度）组件共存。

minecraft:tags ​

为物品设置标签，用于游戏的逻辑判断（如配方匹配等）。

json
"minecraft:tags": {
  "tags": ["minecraft:is_food", "minecraft:transform_templates"]
}

minecraft:use_animation ​

资源包组件

此组件需要写在资源包 netease_items_res/ 的物品 JSON 中，而非行为包。

定义右键或长按使用物品时播放的动画及声音。可选值：eat、drink、bow、block、camera、crossbow、brush。

json
"minecraft:use_animation": "eat"

minecraft:icon ​

资源包组件

此组件需要写在资源包 netease_items_res/ 的物品 JSON 中。

设置物品的贴图，值为 item_texture.json 中定义的资源名。

json
"minecraft:icon": "mymod_magic_food"

minecraft:hover_text_color ​

资源包组件

此组件需要写在资源包 netease_items_res/ 的物品 JSON 中。

设置物品名称的悬浮文本颜色，值为颜色名称（如 gold、red、aqua 等）。

json
"minecraft:hover_text_color": "gold"

网易组件（netease: components） ​

网易组件是以 netease: 为前缀的中国版特有组件，提供了额外的功能扩展。

netease:allow_offhand ​

设置物品是否可以放在副手。

json
"netease:allow_offhand": {
  "value": true
}

副手限制

基岩版原版副手功能较弱，大多数时候无法直接使用副手物品，主要用于装饰和在脚本中判断副手是否持有某物品。副手不支持 minecraft:foil 和 netease:render_offsets 等组件。

netease:cooldown ​

定义物品的冷却时间。同 category 的物品共享冷却。

字段类型默认值说明
categorystr"item"冷却类型，同种类型冷却会互相影响
durationint0再次使用前的冷却时间（tick）
json
"netease:cooldown": {
  "category": "item",
  "duration": 10
}

食物冷却

自定义食品（minecraft:food）的冷却时间应定义在 minecraft:food 的 cooldown_type 和 cooldown_time 中，而不是 netease:cooldown。

netease:customtips ​

定义物品的描述信息，显示在物品名称下方。

json
"netease:customtips": {
  "value": "§8右键可发射"
}

netease:enchant_material ​

设置物品是否可以作为附魔台的附魔材料。

json
"netease:enchant_material": {
  "value": true
}

netease:fire_resistant ​

设置物品是否防火。防火的物品与下界合金物品行为一致：不会被火焰烧毁，掉进岩浆时会弹走。

json
"netease:fire_resistant": {
  "value": true
}

netease:fuel ​

设置物品的燃料属性，允许其在熔炉中作为燃料燃烧。

字段类型默认值说明
durationfloat0.0可提供的熔炉燃烧时长（秒）
json
"netease:fuel": {
  "duration": 3.0
}

netease:compostable ​

设置物品是否可以堆肥（在堆肥桶中使用），值为堆肥成功概率（百分比）。

json
"netease:compostable": 48

netease:show_in_hand ​

设置物品拿在手上时是否显示。

json
"netease:show_in_hand": {
  "value": false
}

netease:render_offsets ​

设置右手物品的渲染偏移（位置、旋转、缩放）。

字段类型默认值说明
controller_position_adjustarray[0.0, 0.0, 0.0]物品位置偏移 [x, y, z]
controller_rotation_adjustarray[0.0, 0.0, 0.0]物品旋转偏移 [x, y, z]
controller_scalefloat1.0物品缩放大小
json
"netease:render_offsets": {
  "controller_position_adjust": [0.0, 0.1, 0.0],
  "controller_rotation_adjust": [0.0, -45.0, 0.0],
  "controller_scale": 1.0
}

netease:initial_user_data ​

定义物品的初始 userData，用于创建自带数据的物品（如初始附魔、死亡不掉落等）。

字段类型说明
displayobject显示信息，包含 Name(str)、Lore(array)、ShowInHand(bool)
encharray(object)附魔信息，每个 object 包含 id(short) 和 lvl(short)
minecraft:keep_on_deathbool死亡时是否保留
minecraft:item_lockbyte锁定模式。0：不锁定，1：无法移动，2：无法丢弃
json
"netease:initial_user_data": {
  "display": {
    "Name": "宝石剑",
    "Lore": ["第一行描述", "第二行描述"]
  },
  "ench": [
    {
      "id": {
        "__type__": 2,
        "__value__": 12
      },
      "lvl": {
        "__type__": 2,
        "__value__": 10
      }
    }
  ],
  "minecraft:keep_on_death": true
}

type 说明

byte 和 short 类型的值需要使用 __type__ 指定类型：byte 的 __type__ 为 1，short 为 2。

特殊类型专属组件 ​

以下组件需要搭配对应的 custom_item_type 使用，详见各专题页面：

组件所需 custom_item_type说明
netease:weaponweapon武器/工具属性（类型、攻击、挖掘等级）
netease:armorarmor盔甲属性（防御值、韧性、槽位）
netease:eggegg生物蛋（指定生成的生物 identifier）
netease:bucketbucket桶（指定倒出的流体方块）
netease:shieldshield盾牌（防御伤害类型列表）
netease:projectileprojectile_item抛射物（右键发射的实体 identifier）

资源包配置（netease_items_res 与 item_texture.json） ​

资源包侧需要配置两部分内容：贴图映射和物品表现 JSON。

第一步：放置贴图文件 ​

将物品的贴图文件（PNG 格式）放入资源包的 textures/items/ 目录中。

resource_pack/
  └── textures/
      └── items/
          └── magic_food.png    ← 你的物品贴图

贴图尺寸建议

推荐使用 16x16 像素的贴图（与原版物品一致）。也支持 32x32 或更大的尺寸，但过大的贴图会增加资源包体积，不建议超过 64x64。

第二步：配置 item_texture.json ​

在资源包的 textures/ 目录下创建或编辑 item_texture.json，建立资源名与贴图路径的映射关系。资源名必须全局唯一。

json
{
  "resource_pack_name": "my_mod",
  "texture_data": {
    "mymod_magic_food": {
      "textures": "textures/items/magic_food"
    }
  }
}

路径不需要扩展名

textures 字段中的贴图路径不需要写 .png 后缀，引擎会自动查找对应的图片文件。

第三步：配置物品表现 JSON ​

在资源包根目录下新建 netease_items_res/ 文件夹，在其中创建与行为包对应的物品 JSON 文件。这个 JSON 定义物品的客户端表现属性（贴图、动画等）。

category 一致性

资源包 JSON 中的 category 字段需要与行为包中的设置一致或者不填，否则可能出现错误。

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:magic_food",
      "category": "items"
    },
    "components": {
      "minecraft:icon": "mymod_magic_food",
      "minecraft:use_animation": "eat"
    }
  }
}

关键点：

  • identifier 必须与行为包中的一致
  • minecraft:icon 的值对应 item_texture.json 中的资源名
  • minecraft:use_animation、minecraft:hover_text_color 等资源包组件在这里配置

本地化（zh_CN.lang） ​

在资源包的 texts/zh_CN.lang 文件中配置物品的中文名称。键的格式为：

item.命名空间:物品名.name=显示名称

例如：

item.mymod:magic_food.name=魔法食物
item.mymod:basic_gem.name=基础宝石

多语言支持

如需支持英文，在 texts/en_US.lang 中添加对应的英文名称即可。格式相同。

常见组件速查表 ​

下表汇总了基础物品中常用的组件及其简要说明，方便快速查阅：

行为包组件（写在 netease_items_beh） ​

组件类型说明
minecraft:max_stack_sizeint最大堆叠数量，上限 64
minecraft:max_damageint耐久度上限，范围 0~32767
minecraft:hand_equippedbool是否竖直握持（武器持握方式）
minecraft:foilbool是否显示附魔光效
minecraft:use_durationint最大使用时长（tick）
minecraft:foodobject食物组件（营养值、饱和度等）
minecraft:seedobject农作物种植组件
minecraft:stacked_by_databool不同 aux 值是否分别堆叠
minecraft:tagsobject物品标签
netease:allow_offhandobject是否可放入副手
netease:cooldownobject使用冷却时间
netease:customtipsobject物品描述文本
netease:enchant_materialobject是否可作为附魔材料
netease:fire_resistantobject是否防火（类似下界合金）
netease:fuelobject燃料属性（熔炉燃烧时长）
netease:compostableint堆肥成功概率（百分比）
netease:show_in_handobject手持时是否显示
netease:render_offsetsobject右手渲染偏移（位置/旋转/缩放）
netease:initial_user_dataobject初始 userData（附魔、锁定等）

资源包组件（写在 netease_items_res） ​

组件类型说明
minecraft:iconstr物品贴图资源名
minecraft:use_animationstr使用动画（eat/drink/bow 等）
minecraft:hover_text_colorstr悬浮文本颜色
netease:frame_anim_in_sceneobject手持/掉落贴图序列帧动画
netease:frame_animationobject蓄力物品序列帧动画

附属功能 ​

自定义配方 ​

自定义物品的 identifier 可以用在自定义配方中，作为合成材料或合成产出。

村民交易 ​

可以将行为包中交易配置文件的 item 字段替换为自定义物品的 identifier，让村民出售你的自定义物品。

掉落表（loot_table） ​

自定义物品的 identifier 可用于 loot_table 配置掉落物，例如让僵尸掉落你的自定义物品。

Python 事件与接口 ​

自定义物品支持 Mod SDK 中所有与物品相关的事件及接口，包括但不限于：

  • ServerItemUseOnEvent — 物品对方块使用
  • ActorUseItemServerEvent — 实体使用物品
  • OnItemPutInEvent / OnItemTakeOutEvent — 容器物品变化
  • SpawnItemToPlayerInv — 生成物品到玩家背包

卸载行为 ​

若使用了自定义物品的存档卸载了 mod 后再进入游戏：

  1. 玩家背包中的自定义物品：物品会消失。若重新加载 mod，卸载期间登录过的玩家物品不会恢复；没有登录过的玩家物品可以保留。

  2. 地图上容器内的自定义物品：物品会消失。若重新加载 mod，卸载期间被探索过的区域内的容器物品不会恢复；未探索区域的容器物品可以保留。

  3. 地图上未捡起的掉落物：掉落物会消失。若重新加载 mod，卸载期间被探索过的区域掉落物不会恢复（除非 subchunk 内没有其他任何实体）；未探索区域的掉落物可以保留。

数据安全

在发布 mod 更新时，请谨慎处理物品 identifier 的变更。修改 identifier 等同于删除旧物品并添加新物品，玩家已有的旧物品将会丢失。

完整示例 ​

下面展示一个完整的自定义食物——"魔法苹果"，包括行为包和资源包的所有文件。

文件结构 ​

behavior_pack/
  └── netease_items_beh/
      └── magic_food.json

resource_pack/
  ├── textures/
  │   ├── items/
  │   │   └── magic_food.png
  │   └── item_texture.json
  ├── netease_items_res/
  │   └── magic_food.json
  └── texts/
      └── zh_CN.lang

行为包：netease_items_beh/magic_food.json ​

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:magic_food",
      "category": "items"
    },
    "components": {
      "minecraft:max_stack_size": 16,
      "minecraft:tags": {
        "tags": ["minecraft:is_food"]
      },
      "minecraft:use_duration": 32,
      "minecraft:food": {
        "nutrition": 6,
        "saturation_modifier": "good",
        "can_always_eat": false,
        "effects": [
          {
            "name": "regeneration",
            "chance": 1.0,
            "duration": 10,
            "amplifier": 1
          },
          {
            "name": "absorption",
            "chance": 1.0,
            "duration": 60,
            "amplifier": 0
          }
        ]
      },
      "netease:fire_resistant": {
        "value": true
      },
      "netease:customtips": {
        "value": "§a食用后获得生命恢复和伤害吸收"
      }
    }
  }
}

资源包：textures/item_texture.json ​

json
{
  "resource_pack_name": "my_mod",
  "texture_data": {
    "mymod_magic_food": {
      "textures": "textures/items/magic_food"
    }
  }
}

资源包：netease_items_res/magic_food.json ​

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "mymod:magic_food",
      "category": "items"
    },
    "components": {
      "minecraft:icon": "mymod_magic_food",
      "minecraft:use_animation": "eat"
    }
  }
}

资源包：texts/zh_CN.lang ​

item.mymod:magic_food.name=魔法苹果

测试方法 ​

进入游戏后，使用以下指令获取物品：

/give @s mymod:magic_food 16

你应该能看到一个最大堆叠 16、带有描述文本、食用后恢复生命的自定义食物。

常见问题 ​

JSON: xxx has an error ​

这是最常见的错误，通常是 JSON 格式有问题。请检查：

  • 是否漏写或多写了逗号
  • 括号 {} 和 [] 是否正确配对
  • 字符串是否都用双引号 "" 包裹
  • 文件编码是否为 UTF-8

排查建议

推荐使用 VS Code 等带有 JSON 校验功能的编辑器。打开 JSON 文件后，编辑器会自动高亮语法错误。

物品贴图显示为紫黑方格 ​

  • 检查 item_texture.json 中的资源名是否与 netease_items_res 中 minecraft:icon 的值一致
  • 检查贴图文件路径是否正确（路径不需要 .png 后缀）
  • 确认贴图文件确实存在于 textures/items/ 目录中

物品名称显示为 identifier ​

  • 检查 zh_CN.lang 中的键是否正确，格式为 item.命名空间:物品名.name=显示名称
  • 确认 zh_CN.lang 文件位于资源包的 texts/ 目录中
  • 确认文件编码为 UTF-8

物品不出现在创造模式物品栏 ​

  • 检查 category 是否设为 commands 或 none，这两个值不会在物品栏中显示
  • 确认行为包和资源包都已正确加载
  • 尝试使用 /give 指令直接获取测试

identifier 包含大写字母导致异常 ​

identifier 必须全部使用小写字母和下划线，不支持大写字母。如果使用了大写字母，可能导致物品无法正常注册或在部分功能中匹配失败。

行为包和资源包的 identifier 不一致 ​

两侧的 description.identifier 必须完全一致。如果不一致，物品的贴图、动画等表现效果将无法正确关联。

下一步 ​