§1 引言

原版模组指在不修改 Minecraft 游戏本体的前提下，通过命令方块、一键命令、数据包、资源包等方式对游戏的可玩性做出修改。之所以称之为原版模组，乃是为了和使用 Mod Loader/API 环境基于 Java 开发的 Mod 作区分，这些 Mod Loader/API 包括 Forge，Liteloader，Fabric 等。自 Minecraft Java 版 1.13 起的数据包概念问世之后，原版模组的制作已变得十分便捷。本文内的原版模组便是指利用数据包和可能的配套资源包对游戏的可玩性做出修改。

本文内容适用于 Minecraft Java 版 1.19 版本，但大部分内容也适合 1.13-1.18 版本，或只需要做简单修改，请读者自行区分。系统环境为 Windows 10，其它环境下有较小的差异。本文参考和吸取了大量其他玩家的意见、建议和教程等，无法一一列出，在此一并表示感谢。

本文更侧重教程而非开发手册，因此很多内容的完整格式并没有列出，此时请读者自行查阅相关的 wiki 链接。由于国内访问 Minecraft Wiki 速度较慢，因此本文中 wiki 页面链接均使用 biligame 的镜像。由于 Minecraft 英文 Wiki 往往更新更及时且内容更准确，因此有英文阅读能力的可直接查看英文 wiki 的相关内容。

本文中青铜色楷体表示其应当被替换为合适的字符串，绿色楷体表示JSON文件中的注释，点击左下角显/隐可切换显示或隐藏注释。

§1.1 命令基础

本文不会介绍命令的基础知识，相关内容请读者通过如下链接自行了解。

• 命令 此为官方 wiki 的命令页面，其中包括了命令的基本参数介绍：坐标、目标选择器、数据标签 (NBT) 、原始JSON文本、命名空间ID等内容。读者需在学习命令过程中逐步了解这些概念。

• 记分板 此为官方 wiki 的记分板页面，其中包括了记分板的所有准则和相关命令格式，也包含了标签 (tag) 和组 (team) 的相关内容。

• 实体格式和player.dat格式 这两个页面给出了所有物品和实体(含方块实体)的 NBT。在游戏中，实体的 NBT 可通过命令 data get entity/block 来获取，物品的 NBT 可通过手持并输入命令 data get entity @s SelectedItem 来获取，以避免记忆大量的 NBT。

• 新人手册-MC命令方块资源 该网站包含了很多基础的教程，不过很多内容会有些过时。还包含少量进阶的内容，对于初学者可能较为复杂，请以理解其逻辑为主。

• 命令进阶 该网站虽名为命令进阶，实际上比前一项页面更为初等，不过更为系统。

若你已对 1.18 之前版本的命令较为熟悉，可在Java版版本记录中查看各版本间差异。

§1.2 工具准备

§1.2.1 文本编辑器

原版模组涉及的文本文件，包括文本文档(.txt)、函数文件(.mcfunction)、JSON文件(.json, .mcmeta)、顶点着色器(.vsh)和片段着色器(.fsh)，均需使用 UTF-8 编码格式。注意不要误选了 UTF-8 with BOM 编码格式。文本编辑器多如瀚海，读者可自行选择一种。我仅列出本人常用的两个文本编辑器。

• Visual Studio Code 下载安装后，可以安装插件 Chinese (Simplified) Language Pack for Visual Studio Code 以支持中文语言，以及Data-pack Helper Plus 用于数据包各项内容的语法补全和纠错。

• 记事本为 Windows 系统自带的极简编辑器。Windows10 的记事本已经默认是 UTF-8 编码了。点击查看->状态栏可以在右下角状态栏看到，因此可以正常使用。旧版本 Windows 的记事本仍然不是，请勿使用。

编辑器右下角可以看到 LF 或 CRLF，分别表示两种换行符，二者均可正常使用，建议使用 LF。

为便于查看文件后缀，请将文件->文件夹选项->查看->隐藏已知文件类型的扩展名去掉勾选。我们可以在编辑器中新建文本文件，或者在文件夹中右键->新建->文本文档，除 txt 以外的文本文件可通过修改文件后缀得到。

§1.2.2 压缩软件

数据包和资源包均可以为文件夹或 zip 文件，zip 文件需要压缩软件来打开和制作。游戏本体和模组本体的 jar 文件也需要使用压缩软件来打开。常见的压缩软件有：

• 7-Zip 是一款免费的压缩软件。jar 文件可以通过右键->7-zip->打开压缩包来打开。

• WinRAR 是一款付费的压缩软件。

• Windows 资源管理器是 Windows10 系统自带的软件。它可以使得 zip 文件如同文件夹般直接打开，压缩则用选择->右键->发送到->压缩文件夹，但它的压缩速度十分缓慢。

§1.2.3 NBT 编辑器

我们可以使用 NBTStudio 来打开 dat 文件和其它 NBT 格式文件。

§1.2.4 绘图工具

我们可以使用 Adobe Photoshop 或其它绘图工具来绘制纹理。Windows 自带的画图由于无法生成透明背景，因此不建议使用。

§1.3 游戏文件夹

本节中我们将对游戏文件夹的结构做简单的介绍，我们只介绍原版模组开发中涉及的内容。.minecraft 文件夹是 Minecraft 创建的并用于游戏运行的文件夹，它包含了游戏的所有内容。在第一次启动启动器时，会自动创建 .minecraft 文件夹。参考 .minecraft。

.minecraft 文件夹通常位于你的启动器目录下。如果启动器中设置为各版本独立，则位于 versions/版本号下。另一种方式是在游戏内点击选项->资源包->打开压缩包文件夹并返回上级目录，或者点击单人游戏->选中世界->编辑->打开世界文件夹并返回上上级目录。

游戏本体位于 versions/版本号/版本号.jar。该文件包含了对应版本的游戏资源和数据文件，使用压缩软件打开后，可以看到

• 原版资源包位于 assets 文件夹内，其中 minecraft 文件夹为命名空间 minecraft 下的资源文件。

• 原版数据包位于 data 文件夹内，其中 minecraft 文件夹为命名空间 minecraft 下的数据文件。

• pack.mcmeta 为原版资源包和数据包的元信息，1.17版本起不再包含该文件。

• pack.png 为原版资源包和数据包的图标。

资源包文件夹位于 resourcepacks，其下方子文件夹或 zip 文件即为一个资源包，具体结构见资源包。服务器下载的资源包位于 server-resource-packs/服务器，可使用压缩软件打开。

资源文件 部分资源文件不被包含在原版资源包内，而是位于资源文件夹下，这主要包括各种语言文本和音效文件。资源文件索引位于 assets/indexes/版本号.json，打开后通过键值可知相应资源的 hash 值，对应的资源位于 assets/objects/hash前2位/hash。例如打开 assets/indexes/1.17.json，找到键 minecraft/lang/zh_cn.json 的 hash 为 8fb4f6725d8317a37e7f823ff424e66a46b9ef75，因此简体中文的语言文本位于文件夹 assets/objects/8f/8fb4f6725d8317a37e7f823ff424e66a46b9ef75，使用文本编辑器打开即可看到游戏内的所有名称的中文译名。注意该文件中的中文均被转化成了相应的 Unicode 表达方式，参考字体。

日志位于 logs/latest.log，可由此实时查看游戏运行中的各种反馈。对于我们而言，它可以在加载资源包和数据包时告诉我们它们是否有错误以及错误信息，包括错误的文件名称、位置、错误的行列数等，因此这对于我们调试非常重要。简体中文下需要设置文件编码为 gbk，否则除 ASCII 外的字符会显示乱码。历史日志位于 logs/年-月-日-序号.log.gz，使用压缩软件打开后使用文本编辑器打开即可查看。崩溃报告位于 crash-reports/crash-年-月-日_时.分.秒-server.txt，如果是由于资源包或数据包引起的崩溃，可以在该文件中看到原因。

存储的物品栏位于 hotbar.nbt，存储了游戏内使用 C+数字 存储、X+数字 取出的创造模式物品快捷栏。

存档文件位于 saves/世界名称，由于世界格式上该内容已较为详尽且与原版模组联系甚远，因此我们仅提及部分内容。该文件夹包含的区块文件、地图文件等内容虽然也可以使用 NBT 编辑器来编辑，但较为不便，我们建议使用 MCEdit、地图文件生成工具等专门的工具来编辑。存档的备份文件位于 backups/年-月-日_时.分.秒_世界名称.zip，为存档的备份文件，解压后复制到 saves 即可使用。

• 进度位于 advancements/玩家UUID.json，记录了玩家已完成的进度和进度判据的完成时间。对于需要完成多个判据才能达成的进度，该文件中记录了已完成的那些判据的完成时间。

• 区块、实体、实体兴趣点、袭击等信息分维度存储，主世界、下界、末地、自定义维度的相应文件分别位于根文件夹、DIM-1、DIM1、dimensions/命名空间/路径下。

• 世界信息文件 level.dat 中 WorldGenSettings 包含了世界生成时的所有维度的生成信息，玩家可以在创建新的世界->更多世界的选项->导入设置使用JSON文件导入，格式见自定义世界。之后还会加入数据包中的自定义维度。

• 数据包文件夹位于 datapacks，其下方子文件夹或 zip 文件即为一个数据包，具体结构见数据包。

• 结构位于 generated/命名空间/structures/文件.nbt，其记录了游戏内使用结构方块保存的结构，将其移动至数据包内方可使用。

§1.4 JSON文件

参考JSON。数据包的进度、战利品表、战利品表谓词、物品修饰器、配方、标签、维度、维度类型、自定义世界生成，资源包的语言文件、模型、音效、字体、credits.json 等文件均为JSON文件。.mcmeta 文件也是JSON文件，因此格式也是相同的。

JSON文件中用于分割的空格、制表符(Tab)、回车和换行符都是可去的，它们仅用于提高可读性。编写时，使用空格或制表符缩进，以便于查看括号匹配和层次。JSON文件通常包含用于封装文件数据的一对大括号{}，即它是一个JSON对象，但战利品表谓词和物品修饰器文件的根数据类型还可以为JSON数组。它包含类似 "abc": "def" 这样的 "键": 值 对，一般使用单引号也可以。同一个文件中如果允许有相同的键，则后者会覆盖前者。

JSON数据类型有下述几种。Wiki 上有关页面使用了 NBT 的数据类型标注，但其实并不适用于JSON文件，我们应当将其视为相应内容的可取值范围。

布尔型，值为 true 和 false。

数值，值为任何数字。2 和 2.0 没有差异。

字符串，值使用双引号/单引号圈住，可以使用颜色代码如 §6、换行符 \n。

数组，值使用中括号圈住。

对象，使用大括号圈住。整个JSON文件内容本身就是一个JSON对象。

JSON中没有注释的语法，但可以使用不被使用的键来表示注释。通常使用 "_comment", "_comment1", "_comment2" 这种键。

我们常常在JSON中用整数来表示RGB格式颜色，对应值为: 65536×R+256×G+B。