主题

手搓：从零创建魔法权杖 ​

前面的教程都借助了编辑器的可视化配置或原版模板。这一节我们完全抛开编辑器，手动编写每一个 JSON 文件，从白纸开始创建一把全新的魔法权杖武器。

通过这个过程，你将彻底理解模组的文件结构和底层原理。

前置知识

本教程需要你已完成前面的入门教程，了解 MC Studio 的基本操作。你还需要一个文本编辑器（推荐 VS Code）。

你将学到

  • 附加包的完整文件结构（行为包 + 资源包）
  • 手写行为包 JSON（物品定义、武器组件、耐久度）
  • 手写资源包 JSON（贴图绑定、渲染方式、名称颜色）
  • 配置 item_texture.json（贴图映射表）
  • 配置 zh_CN.lang（中文本地化）
  • 理解 identifier、命名空间、组件的实际意义

项目目标 ​

创建一把「翡翠权杖」，具备以下属性：

属性值说明
攻击力10高于钻石剑（7）
耐久度500高于铁剑（250）
工具类型剑可以快速破坏蜘蛛网
附魔能力22高于钻石（10），容易出好附魔
修复材料绿宝石level 设为 3
特殊效果附魔光效始终闪闪发光
渲染方式竖直手持像剑一样握在手中
防火是掉进岩浆不会烧毁
名称颜色金色在物品栏中金色高亮显示

第一步：打开项目目录 ​

  1. 在 MC Studio 中创建一个新的「空白 AddOn」项目（或使用已有项目）
  2. 在作品列表中找到它，点击「更多」→「打开目录」
  3. 你会看到类似这样的文件夹结构：
我的作品/
├── behavior_pack_xxx/
│   ├── entities/
│   └── manifest.json
├── resource_pack_xxx/
│   ├── textures/
│   ├── texts/
│   └── manifest.json
└── ...

用 VS Code 打开这个作品目录（File → Open Folder）。

第二步：准备贴图 ​

  1. 准备一张 16×16 像素的 PNG 贴图作为权杖的图标（你可以用任何绘图工具绘制，或从网上找一张占位图）
  2. 在资源包中创建贴图目录（如果还没有的话）：
resource_pack_xxx/textures/items/
  1. 将贴图保存为 emerald_staff.png 放入该目录

第三步：创建行为包 JSON ​

行为包 JSON 定义了物品的游戏逻辑——攻击力、耐久度、武器类型等。

在行为包中创建文件夹和文件：

behavior_pack_xxx/netease_items_beh/emerald_staff.json

为什么是 netease_items_beh？

中国版自定义物品的行为包 JSON 统一放在 netease_items_beh 目录下（而不是原版的 items 目录）。这是网易中国版的约定。

写入以下内容：

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "magic_farm:emerald_staff",
      "custom_item_type": "weapon",
      "category": "equipment"
    },
    "components": {
      "minecraft:max_stack_size": 1,
      "minecraft:max_damage": 500,
      "minecraft:hand_equipped": true,
      "minecraft:foil": true,
      "netease:weapon": {
        "type": "sword",
        "level": 3,
        "speed": 0,
        "attack_damage": 10,
        "enchantment": 22
      },
      "netease:fire_resistant": {
        "value": true
      },
      "netease:customtips": {
        "value": "§a一把蕴含翡翠之力的魔法权杖"
      }
    }
  }
}

逐字段解释 ​

字段值作用
identifiermagic_farm:emerald_staff全局唯一 ID。magic_farm 是命名空间，emerald_staff 是物品名
custom_item_typeweapon告诉引擎这是武器类物品
categoryequipment在创造模式物品栏的「装备」分类下
minecraft:max_stack_size1武器不可堆叠
minecraft:max_damage500耐久度 500 次
minecraft:hand_equippedtrue竖直握在手中（像剑一样）
minecraft:foiltrue附魔光效，始终闪闪发光
netease:weapon.typesword剑类武器（可快速破坏蜘蛛网）
netease:weapon.level3钻石级，可用绿宝石在铁砧修复
netease:weapon.attack_damage10攻击伤害 10
netease:weapon.enchantment22附魔能力 22（金质=22，容易出好附魔）
netease:fire_resistanttrue防火，掉进岩浆不会烧毁
netease:customtips§a...物品描述文字（§a 是绿色格式代码）

中国版 vs 国际版武器组件差异

中国版使用 netease:weapon 组件定义武器属性（type / attack_damage / enchantment / level / speed），这是网易独有的组件。

国际版（Bedrock Wiki 中记录的方式）在 format_version 1.21.90 及以上使用完全不同的组件：

  • minecraft:damage（攻击伤害）
  • minecraft:durability（耐久度，替代 minecraft:max_damage）
  • minecraft:enchantable（附魔能力，含 slot 字段指定附魔槽位）
  • minecraft:repairable（修复材料和公式）
  • minecraft:display_name（显示名称，替代 lang 文件方式）

两套体系不可混用。在中国版开发中，武器类物品始终使用 netease:weapon + minecraft:max_damage 的组合。

第四步：创建资源包 JSON ​

资源包 JSON 定义了物品的视觉表现——使用什么贴图、名称什么颜色。

4.1 物品资源定义 ​

创建文件：

resource_pack_xxx/netease_items_res/emerald_staff.json

写入：

json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "magic_farm:emerald_staff",
      "category": "equipment"
    },
    "components": {
      "minecraft:icon": "magic_farm_emerald_staff",
      "minecraft:hover_text_color": "gold"
    }
  }
}
字段说明
identifier必须与行为包中的一致
minecraft:icon指向 item_texture.json 中的资源名
minecraft:hover_text_color物品名称在物品栏中的颜色（金色）

4.2 贴图映射表 ​

打开或创建文件：

resource_pack_xxx/textures/item_texture.json

注意

如果这个文件已经存在（比如之前的教程已经创建过），不要覆盖它，而是在 texture_data 中追加新条目。

json
{
  "resource_pack_name": "vanilla",
  "texture_name": "atlas.items",
  "texture_data": {
    "magic_farm_emerald_staff": {
      "textures": "textures/items/emerald_staff"
    }
  }
}

这里的 magic_farm_emerald_staff 就是资源包 JSON 中 minecraft:icon 引用的资源名，它指向了 textures/items/emerald_staff.png 这张贴图（注意路径不需要写 .png 后缀）。

4.3 中文名称 ​

打开或创建文件：

resource_pack_xxx/texts/zh_CN.lang

追加一行：

item.magic_farm:emerald_staff.name=翡翠权杖

格式为 item.{identifier}.name=中文名称。

第五步：完整文件结构回顾 ​

到这里，我们手动创建了以下文件：

我的作品/
├── behavior_pack_xxx/
│   ├── netease_items_beh/
│   │   └── emerald_staff.json          ← 行为定义（攻击力、耐久、武器类型）
│   ├── entities/
│   └── manifest.json
├── resource_pack_xxx/
│   ├── netease_items_res/
│   │   └── emerald_staff.json          ← 资源定义（贴图、名称颜色）
│   ├── textures/
│   │   ├── items/
│   │   │   └── emerald_staff.png       ← 贴图文件（16×16）
│   │   └── item_texture.json           ← 贴图映射表
│   ├── texts/
│   │   └── zh_CN.lang                  ← 中文名称
│   └── manifest.json

这就是一个自定义武器物品的完整文件结构。每一个文件都有明确的职责，通过 identifier 和贴图资源名将它们串联起来：

行为包 JSON (identifier) ←→ 资源包 JSON (identifier)
                                    ↓ (minecraft:icon)
                          item_texture.json (资源名)
                                    ↓ (textures 路径)
                          textures/items/emerald_staff.png

第六步：测试 ​

  1. 回到 MC Studio，找到作品，点击「开发测试」
  2. 进入游戏后，在聊天栏输入：
/give @s magic_farm:emerald_staff
  1. 检查以下效果：
检查项预期效果
物品名称「翡翠权杖」，金色显示
物品描述绿色文字「一把蕴含翡翠之力的魔法权杖」
附魔光效始终闪闪发光
手持渲染竖直握在手中（像剑一样）
攻击伤害对生物造成 10 点伤害（5 颗心）
耐久度物品显示耐久条，最大 500
防火丢进岩浆后不会烧毁
创造物品栏在「装备」分类下找到

如果物品不显示

  • 检查所有 JSON 文件的 identifier 是否完全一致
  • 检查 item_texture.json 中的资源名是否与资源包 JSON 的 minecraft:icon 一致
  • 检查贴图文件是否放在了正确的路径
  • 打开「脚本测试日志」窗口查看是否有 JSON 格式报错

对比：编辑器配置 vs 手写 JSON ​

方式优点缺点
编辑器配置可视化操作、不易出错、自动管理文件部分高级功能不支持（如名称颜色、防火、自定义描述）
手写 JSON完全控制、支持所有功能需要了解文件结构、容易拼写错误
混合使用兼顾效率和灵活性需要理解两者的关系

推荐工作方式

实际开发中，推荐先用编辑器创建基础配置，然后用 VS Code 手动修改 JSON 添加高级属性。编辑器和手写 JSON 的结果会自动同步。

小结 ​

在这一节中，你完全脱离了编辑器的模板和可视化操作，手动创建了：

  • 行为包 JSON：定义了武器的 identifier、攻击力、耐久度、武器类型、附魔能力、防火属性、物品描述
  • 资源包 JSON：定义了贴图引用和名称颜色
  • 贴图映射表：将资源名映射到实际的贴图文件
  • 中文本地化：配置物品的中文显示名

你现在已经理解了自定义物品从注册到渲染的完整数据链路。这些知识适用于所有类型的自定义内容——物品、方块、生物的底层原理都是一样的：行为包定义逻辑，资源包定义表现，通过 identifier 串联。