数据包基础

数据包（Data Pack）为玩家自定义Minecraft的游戏内容提供了更多新方法，包括但不限于配置进度、配方、战利品表、魔咒、伤害类型、生物变种和世界生成等。对数据包的修改并不等于修改了包含相同逻辑部分的游戏代码。

建议在你在看完本站的数据包制作文档可以学会查阅 Minecraft Wiki 文档。

对于我们想要修改的规则，在 参见 Minecraft Wiki - 数据包 中的目录结构处寻找，每个目录都对应一个游戏规则，具体有该方法点击文件名的超连接即可跳转到定义格式页面。

参见 Minecraft Wiki - 数据包

什么是数据包？

在每个版本的根目录下，都会有一个以版本名为名称的 jar 文件，存放着游戏的资源、行为等，而数据包与此文件目录有着相同的结构，负责覆盖原版 jar 文件中 data 目录的游戏行为数据。

数据包结构

一个数据包的结构如下：

数据包根目录/
├── pack.mcmeta                    # 数据包元数据，包含版本号和描述
├── pack.png                       # 数据包图标，64x64 像素
└── data/
    └── <命名空间>/
        ├── advancements/          # 玩家进度 / 成就定义文件目录
        ├── banner_pattern/        # 旗帜图案样式文件目录
        ├── cat_variant/           # 猫的外观变种文件目录
        ├── chat_type/             # 聊天类型文件目录
        ├── damage_type/           # 伤害类型文件目录
        ├── dimension/             # 维度文件目录
        ├── dimension_type/        # 维度环境参数文件目录
        ├── enchantment/           # 附魔效果文件目录
        ├── functions/             # 命令函数文件文件目录
        ├── frog_variant/          # 青蛙的外观变种文件目录
        ├── instrument/            # 山羊号角音效文件目录
        ├── jukebox_song/          # 唱片音乐曲目文件目录
        ├── loot_tables/           # 掉落物和战利品配置文件目录
        │   ├── archaeology/       # 考古战利品文件目录
        │   ├── blocks/            # 方块掉落文件目录
        │   ├── chests/            # 宝箱战利品文件目录
        │   ├── entities/          # 实体掉落文件目录
        │   └── gameplay/          # 游戏玩法战利品文件目录
        ├── predicates/            # 条件判断逻辑文件目录
        ├── recipes/               # 合成 / 冶炼配方文件目录
        ├── structures/            # 建筑结构 NBT 文件目录
        ├── tags/                  # 各类分组标签文件目录
        │   ├── blocks/            # 方块标签文件目录
        │   ├── entities/          # 实体标签文件目录
        │   ├── fluid/             # 流体标签文件目录
        │   ├── functions/         # 函数标签文件目录
        │   ├── game_events/       # 游戏事件标签文件目录
        │   ├── items/             # 物品标签文件目录
        │   └── worldgen/          # 世界生成标签文件目录
        ├── trim_material/         # 盔甲纹饰材料文件目录
        ├── trim_pattern/          # 盔甲纹饰图案文件目录
        ├── wolf_variant/          # 狼的外观变种文件目录
        └── worldgen/              # 世界生成配置文件目录
            ├── biome/             # 生物群系定义文件目录
            ├── configured_carver/ # 地形雕刻器文件目录
            ├── configured_feature/# 世界特征配置文件目录
            ├── density_function/  # 地形密度函数文件目录
            ├── noise/             # 噪声参数文件目录
            ├── noise_settings/    # 噪声整体设置文件目录
            ├── placed_feature/    # 特征放置规则文件目录
            ├── processor_list/    # 结构处理器文件目录
            ├── structure/         # 结构生成定义文件目录
            ├── structure_set/     # 结构生成集合文件目录
            └── template_pool/     # 结构模板池文件目录

在编写数据包时，仅创建和编写需要的文件和目录即可。

TIP

这里的数据包根目录并不是原版存档文件的 datapacks 目录，而是你创作的数据包文件的根目录。

了解 JSON

数据包的编写要用到 JSON 文件。在开始之前，你需要了解 JSON 格式。

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，常用于数据传输与存储。它以键值对的形式组织数据，结构清晰、可读性强，并且与多种编程语言高度兼容。

JSON 数据类型与格式

JSON 支持的数据类型包括：{} 对象、[] 数组、"" 字符串、number 数值、true / false 布尔值。

• 对象：由 {} 包裹，是一个无序的 键 / 值 对集合。每个键（Key）后跟一个冒号 :，多个键值对之间使用逗号 , 分隔。
• 数组：由 [] 包裹。
• 命名规则：键名必须被双引号 "" 包裹。
• 布尔值：表示“是”或“否”，填写 true 或 false。

例如，关于柏茯灵的数据可以用以下 fovlin.json 文件表示：

{
  "name": "柏茯灵",
  "identity": "Developer",
  "is_human": true,
  "skills": ["Data Pack", "Linux", "Minecraft"]
}

如上表示了关于 Fovlin 的数据。

DANGER

JSON 文件不支持注释，上述注释仅为描述各项含义。

了解命名空间:ID

命名空间ID主要由以下两部分组成：

• 命名空间（Namespace）：一个字符串，用于标识资源的唯一性。游戏的默认命名空间为 minecraft，另外 Realms 也使用单独的命名空间realms。

• 路径（Path）：一个字符串。在数据包中，一般也反应了该资源的文件路径。有时也仅作为一种标识名。

在转换为字符串形式时，命名空间和路径之间使用:作为分隔符。

如原版 MC 中的苹果，命名空间ID为 minecraft:apple，原版主世界维度命名空间ID为 minecraft:overworld，数据包中定义的自定义维度命名空间ID则为 <命名空间>:<维度名称>

这意味着你也可以通过创建 minecraft 原版命名空间来修改原版的一些数据/行为。

数据包根目录/
├── pack.mcmeta                    # 数据包元数据，包含版本号和描述
├── pack.png                       # 数据包图标，64x64 像素
└── data/
    └── <命名空间>/
        └── ...

示例

现假设创建一个名为 floating_islands 的数据包，为原版追加浮空岛维度。

创建一个目录作为根目录，取名 floating_islands。

创建并编辑元数据文件

在根目录下一个名为 pack.mcmeta 的文件，以及一个名为 data 的目录。

在 data 目录下创建目录 minecraft 这将引用原版的命名空间，你也可以自定义命名空间并创建维度，此处自定义 example 命名空间作为演示。

{
    "pack": {
        "min_format": 0,
        "max_format": [100, 0],
        "description": "Another world",
        "supported_formats": [0, 100],
        "pack_format": 100
    }
}

其中各键的作用详见 Minecraft 中文 Wiki 数据包#数据包元数据。

创建维度定义文件

根据 Minecraft 中文 Wiki 维度定义格式 可知，定义一个新维度的方法如下:

创建新维度需要在 floating_islands/data/example/ 目录下创建 dimension 目录，并创建以维度名称为命名的 JSON 文件。

{
    "type": "minecraft:overworld",
    "generator": {
        "type": "minecraft:noise",
        "settings": "minecraft:floating_islands",
        "biome_source": {
            "type": "minecraft:multi_noise",
            "preset": "minecraft:overworld"
        }
    }
}

其中各键的作用详见

创建维度类型文件

根据 Minecraft Wiki - 维度类型 可知:

定义维度中的一些规则，需要在 floating_islands/data/example/ 目录下创建 dimension_type 目录，并创建以维度名称为命名的 JSON 文件。

{
    "ultrawarm": false,
    "natural": true,
    "coordinate_scale": 1,
    "has_skylight": true,
    "has_ceiling": false,
    "ambient_light": 0,
    "monster_spawn_light_level": 0,
    "monster_spawn_block_light_limit": 0,
    "piglin_safe": true,
    "bed_works": true,
    "respawn_anchor_works": true,
    "has_raids": true,
    "logical_height": 512,
    "min_y": -256,
    "height": 512,
    "infiniburn": "#minecraft:infiniburn_overworld",
    "effects": "minecraft:overworld"
}

编辑噪声设置文件

原版中已经预设 floating_islands 噪声设置参数，直接在 floating_islands/data/example/dimension/floating_islands 文件中的 generator.settings 处引用 minecraft:floating_islands 原版噪声设置的命名空间ID即可。

如果执意自定义维度中的地形生成规则，需要在 floating_islands/data/example/ 目录下创建 worldgen 目录，并创建 noise_settings 目录，在此目录下创建以维度名称为命名的 JSON 文件，在 floating_islands/data/example/dimension/floating_islands 文件中的 generator.settings 处引用 example:<维度名称>。

关于噪声设置文件格式详见 Minecraft Wiki 噪声设置

整个文件的目录结构如下

floating_islands
 └─data
    └─example
       ├─dimension
       └─dimension_type

随后可以打开游戏-创建新世界-选择数据包，将整个 floating_islands 文件夹复制到目标文件夹，在左侧栏中选择启用，开始游戏，使用指令进入此维度。

execute in example:floating_islands run tp ~ 128 ~

打包数据包

DANGER

请不要右键直接压缩打包！直接压缩会添加数据包本体到压缩文件中，而不会使压缩包成为根目录，游戏无法识别。

正确的打包方式为

• 右键创建新压缩(zipped)文件夹

• 选中数据包根目录下的所有文件，复制

• 选择新建的压缩文件夹，粘贴

• 重命名压缩文件夹为你想要的名字

至此打包完成！