附加包开发

附加包（Add-on）是我的世界基岩版对 Mod 的官方支持方式。通过编写 JSON 配置文件和 Python 脚本，你可以自定义物品、方块、生物、配方等几乎所有游戏内容。本文将详细介绍附加包的组成结构、文件规范和工作机制。

什么是附加包

在我的世界中国版资源中心，组件分为游戏地图、功能玩法、材质光影和皮肤。其中功能玩法和材质光影都是通过附加包来实现的。在后续文档中，我们统一使用"Mod"来指代基岩版的 Add-on。

附加包可以做以下事情：

• 修改原版内容 — 替换贴图、修改生物属性、调整配方，各种材质包就是典型例子
• 添加新内容 — 自定义物品、方块、生物、维度、生物群系等
• 脚本化逻辑 — 通过 Python 脚本实现复杂的玩法逻辑

每个附加包由两部分组成：行为包（Behavior Pack） 和 资源包（Resource Pack）。这对应了 Client-Server 架构——服务端处理游戏逻辑和数据，客户端处理渲染和展示。

包类型	英文名	运行端	职责
行为包	Behavior Pack	服务端	实体行为、生成规则、战利品表、配方、脚本逻辑
资源包	Resource Pack	客户端	贴图、模型、动画、音效、UI、语言文件

行为包详解

行为包存放在 behavior_packs/ 目录下，包含所有与游戏逻辑相关的定义。引擎在服务端启动时读取这些文件并加载对应功能。

一个完整的行为包结构：

behavior_pack_YourMod/
├── manifest.json              # 行为包描述文件（必须）
├── entities/                  # 实体/生物行为定义（必须存在）
│   ├── zombie.json
│   └── custom_mob.json
├── netease_items_beh/         # 自定义物品定义（中国版）
│   └── my_sword.json
├── netease_blocks/            # 自定义方块定义（中国版）
│   └── my_block.json
├── recipes/                   # 配方定义
│   └── my_recipe.json
├── loot_tables/               # 战利品表
│   └── entities/
│       └── zombie.json
├── spawn_rules/               # 生成规则
│   └── zombie.json
├── trading/                   # 村民交易表
│   └── farmer.json
└── YourModScripts/            # Python 脚本目录
    ├── modMain.py             # 脚本入口文件
    ├── server/                # 服务端脚本
    │   └── serverSystem.py
    └── client/                # 客户端脚本
        └── clientSystem.py

entities 文件夹必须存在

中国版要求行为包中必须包含 entities/ 文件夹，否则引擎不会将其识别为有效的行为包。即使你不定义任何实体，也要保留这个空文件夹。

中国版特有目录

• 自定义物品放在 netease_items_beh/，而非国际版的 items/
• 自定义方块放在 netease_blocks/
• Python 脚本放在 behavior_pack/xxxScripts/ 目录下

MC Studio 编辑器的"配置"功能本质上是在可视化编辑这些 JSON 文件，所有编辑器中的新建、修改、删除操作都会实时同步到对应的 JSON 文件。

下表列出了编辑器支持的配置类型及其对应的行为包路径：

配置类型	行为包路径
实体	entities/名称.json
物品	netease_items_beh/名称.json
方块	netease_blocks/名称.json
配方	netease_recipes/名称.json
交易表	trading/名称.json
掉落表	loot_tables/名称.json
生成规则	spawn_rules/名称.json
维度	netease_dimension/名称.json
生物群系	netease_biomes/名称.json
特征	netease_features/名称.json
特征生成	netease_feature_rules/名称.json

资源包详解

资源包存放在 resource_packs/ 目录下，包含所有与客户端渲染相关的资源。引擎在客户端启动时读取并加载。

一个完整的资源包结构：

resource_pack_YourMod/
├── manifest.json              # 资源包描述文件（必须）
├── textures/                  # 贴图文件（必须存在）
│   ├── blocks/                # 方块贴图
│   ├── entity/                # 实体贴图
│   ├── items/                 # 物品贴图
│   ├── terrain_texture.json   # 方块贴图索引
│   └── item_texture.json      # 物品贴图索引
├── entity/                    # 实体资源定义（模型、动画绑定）
│   └── custom_mob.json
├── models/                    # 模型文件（geometry）
│   └── entity/
│       └── custom_mob.geo.json
├── animations/                # 动画文件
│   └── custom_mob.animation.json
├── materials/                 # 渲染材质/着色器
├── effects/                   # 粒子特效
├── sounds/                    # 音效文件
│   └── sound_definitions.json
├── ui/                        # UI 界面定义
├── netease_items_res/         # 自定义物品资源定义（中国版）
│   └── my_sword.json
├── blocks.json                # 方块渲染定义
└── texts/                     # 语言文件
    └── zh_CN.lang

textures 文件夹必须存在

中国版要求资源包中必须包含 textures/ 文件夹，否则引擎不会将其识别为有效的资源包。

需要特别注意：texts/zh_CN.lang 和 textures/item_texture.json 这两个文件是多个配置共享的。如果你有多个自定义物品或方块，它们的语言文本和贴图索引都会写入同一个文件。因此编辑这些文件时应该合并内容，而非覆盖。

原版数据包

原版游戏内容（生物群系、生物、光影材质等）也是通过与附加包完全相同的格式存放在游戏安装目录中的。研究这些原版数据包，可以帮助你理解如何修改原版内容，以及如何制作自定义内容。

原版数据包位置

原版数据包位于 Mod PC 开发包的安装目录：

MCStudioDownload\game\MinecraftPE_Netease\{版本号}\data\behavior_packs\vanilla   # 原版行为包
MCStudioDownload\game\MinecraftPE_Netease\{版本号}\data\resource_packs\vanilla   # 原版资源包

其中 {版本号} 为当前安装的游戏版本文件夹。

如何利用原版数据包

• 查看原版生物的 entities/ 定义，学习实体组件的用法
• 查看原版 textures/ 目录下的贴图，了解资源格式要求
• 复制原版 JSON 作为模板，修改后放入你的附加包中

manifest.json 详解

manifest.json 是每个附加包的描述文件，行为包和资源包各有一个。它包含了包的唯一标识、版本号和模块定义。

完整示例

{
    "format_version": 2,
    "header": {
        "name": "我的示例Mod - 行为包",
        "description": "一个示例行为包",
        "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "version": [1, 0, 0],
        "min_engine_version": [1, 16, 0]
    },
    "modules": [
        {
            "type": "data",
            "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "version": [1, 0, 0]
        }
    ]
}

字段说明

字段	说明
format_version	manifest 格式版本，目前使用 2
header.name	包名称，显示在游戏中
header.description	包的简要描述
header.uuid	包的唯一标识符（UUID），生成后不可修改
header.version	包版本号，格式为 [主版本, 次版本, 修订号]
header.min_engine_version	支持的最低引擎版本
modules[].type	模块类型。行为包用 "data"，资源包用 "resources"
modules[].uuid	模块的唯一标识符，与 header.uuid 不同
modules[].version	模块版本号

UUID 规则

• manifest 文件中有两个 UUID 字段（header.uuid 和 modules[].uuid），它们必须是不同的值
• UUID 一旦生成就不要修改，否则会导致多人联机时出现问题
• 如果从官方示例或其他 Mod 复制模板，必须重新生成 UUID
• 可以在 MC Studio 启动器中选择作品 → 更多菜单 → 配置，进行 UUID 更换

在旧版 MCStudio 中

旧版创建的附加包中该文件可能叫 pack_manifest.json，本质相同。

版本号递增

每次发布新版本时，必须递增版本号（例如将 [1, 0, 0] 改为 [1, 0, 1]）。

原因：玩家联机时会检查本地 Mod 版本是否与房主一致。如果版本号没有变化，拥有新旧版本 Mod 的玩家可能互相联机，导致不可预期的 Bug。

制作规范

命名规范

为了让你的 Mod 与其他开发者的 Mod 区分开、避免同时加载时发生冲突，命名时应有足够的辨识度。推荐使用驼峰命名法（CamelCase）：

项目	推荐格式	示例
Mod 名称	[团队名][Mod名]	NeteaseTutorialMod
行为包文件夹	[团队名][Mod名]BehaviorPack	NeteaseTutorialModBehaviorPack
资源包文件夹	[团队名][Mod名]ResourcePack	NeteaseTutorialModResourcePack
脚本文件夹	[团队名][Mod名]Scripts	NeteaseTutorialModScripts

简而言之，命名时带上团队名和游戏内容，基本可以保证唯一性。

命名空间规范

命名空间 用于区分不同来源的内容，避免标识符冲突。

• 原版命名空间为 minecraft（如 minecraft:dirt）
• 自定义命名空间推荐格式：[团队名]_[作品名]，如 sdkteam_test
• 在 MC Studio 编辑器中通过 作品 → 命名空间 进行设置
• 命名空间一旦设定，不建议更改，否则已有的自定义物品和方块标识符会失效

必要文件夹

包类型	必要文件夹	说明
行为包	entities/	即使为空也必须存在，否则引擎不识别
资源包	textures/	即使为空也必须存在，否则引擎不识别

通过 MC Studio 创建的附加包会自动包含这些文件夹。如果手动构造目录结构，切记不要遗漏。

图片资源规范

附加包中涉及的图片资源主要包括 UI 贴图、模型贴图和特效贴图。制作时需要遵守以下规范：

图像模式

引擎不支持灰度模式的贴图，必须统一使用 RGB 模式。如果在 Photoshop 等工具中编辑，请确认图像模式为 RGB。

通道要求

• 皮肤贴图：必须使用 32 位 4 通道（RGBA），需要包含 Alpha 通道
• 其他贴图：无通道限制，可以使用 24 位 RGB 或 32 位 RGBA

内存限制

图片资源加载后占用的总内存不能超过 100 MB。

内存计算公式：

内存 = 宽度 × 高度 × 位深度 / 8

以一张分辨率 1024 x 1024 的 32 位 PNG 图片为例：

1024 × 1024 × 32 / 8 = 4,194,304 Bytes = 4 MB

制作贴图时应合理控制分辨率。对于不需要高清的元素（如远景方块），使用较小的分辨率可以显著节省内存。

数据覆盖机制

附加包的核心工作原理是路径覆盖：引擎在启动加载阶段，会同时读取原版数据包和附加包。附加包与原版数据包拥有同等地位，但附加包优先级更高。

规则很简单——只要在附加包中放置一个与原版相同路径和文件名的文件，引擎就会使用你的文件来替代原版文件。

示例：修改泥土方块贴图

1. 在原版资源包中找到泥土贴图：textures/blocks/dirt.png
2. 准备一张新的贴图，命名为 dirt.png
3. 放入你的资源包的相同路径：resource_pack_YourMod/textures/blocks/dirt.png
4. 启动游戏，原版泥土的贴图就会被替换

示例：修改僵尸行为

1. 在原版行为包中找到僵尸定义：entities/zombie.json
2. 复制该文件到你的行为包的 entities/zombie.json
3. 修改其中的属性（如移动速度、攻击力等）
4. 启动游戏，僵尸的行为就会按照你的定义执行

覆盖 vs 合并

大多数文件是整体覆盖——你的文件会完全替代原版文件。这意味着你需要保留原版文件中你不想改动的部分。少数文件（如 zh_CN.lang、item_texture.json）是合并的，新内容会追加到原版内容之后。

下一步

• 想了解更多自定义内容的制作方法，请查阅 自定义游戏内容 相关文档
• 想了解脚本开发，请查阅 Python 脚本开发 文档
• 想深入理解附加包的 JSON 格式，可以参考 官方 Wiki - 基岩版附加包文档