Data Pack
数据包是 Java 版用于按存档或服务器加载自定义游戏数据的机制。它通过 pack.mcmeta、data 命名空间目录和一组 JSON 或函数文件，让进度、配方、战利品表、标签、世界生成等内容可以在不修改游戏代码的情况下被替换或扩展。
数据包可以作为文件夹或 .zip 压缩包放入存档根目录下的 datapacks 目录，也可以在创建世界前通过创建世界界面的数据包配置入口加入。创建世界界面中选中的数据包会先缓存到 Java 临时文件目录下的 mcworld 临时目录。
每次加载存档时，游戏都会尝试读取启用的数据包。已经载入的世界可以使用 /reload 重新加载部分数据，但并不是所有目录都支持热重载；无法热重载的内容出现语法错误时，可能让存档在安全提示前停止加载，直到禁用有问题的数据包。
有效数据包必须让 pack.mcmeta 被正确读取，并且所有参与加载的文件能够通过语法和注册校验。文件无法解析时，轻则对应内容不生效，重则触发安全错误或让游戏回退到旧的数据包状态。
数据包加载顺序决定覆盖优先级。创建世界前，界面中的顺序就是初始加载顺序；世界创建后，顺序会写入 level.dat 的 DataPacks 标签，也可以通过 /datapack list 查看。
同一命名空间和路径下的内容如果被多个数据包定义，上层数据包优先。pack.mcmeta 中的 overlays 可以让一个数据包按版本加载不同子目录；叠加目录会完整覆盖本体中对应内容。
数据包的启用通常发生在两个位置：创建世界前的数据包选择界面，或世界已经运行后的 /datapack 命令。创建世界前选择的数据包会随世界保存；运行中的世界启用或禁用数据包后，游戏会自动执行一次数据包重载。
热重载适合调试进度、配方、函数、战利品表、谓词和物品修饰器等内容。世界生成、维度、魔咒、盔甲纹饰和唱片机曲目一类注册内容更接近启动期数据，需要重新进入存档才会完整刷新。
数据包根目录通常包含 pack.mcmeta、可选的 pack.png，以及 data 目录。data 下按命名空间组织内容，命名空间目录中的各注册目录负责存放不同类型的数据。
普通数据文件通常以 data/<命名空间>/<注册名>/<路径>.json 形式注册为 <命名空间>:<路径>。标签文件放在 data/<命名空间>/tags/<注册名>/<路径>.json，引用时通常带 # 前缀。函数文件和结构模板不是普通注册项，但加载方式和命名空间路径规则相近。
pack.mcmeta 的 pack 对象描述数据包信息和版本范围。旧版数据包主要依赖 pack_format 或 supported_formats；从 1.21.9 开始，数据包格式引入主版本和次版本概念，min_format 与 max_format 成为更明确的兼容范围写法。
如果要同时支持 1.21 到 26.1.2 一类跨度较大的版本，可在保留 pack_format 与 supported_formats 的同时写入 min_format 和 max_format，让新版和旧版都能识别到合适的兼容范围。
部分数据包内容会改变客户端接收到的原版数据内容，并触发实验性设置警告。当前会触发警告的内容多属于不可热重载范围，也就是说玩家通常需要重新加载存档才能让这些变化生效。
如果不可热重载目录内的文件语法错误、引用缺失或注册失败，游戏可能在进入存档时显示安全错误，并要求玩家先禁用相关数据包。服务器或整合包维护时，建议先在测试世界验证再部署到正式存档。
| 操作 | 入口 | 会发生什么 | 适用内容 | 注意事项 |
|---|---|---|---|---|
| 创建世界前添加 | 创建世界 > 更多 > 数据包 | 将数据包加入新世界配置并写入初始加载顺序 | 新世界默认规则、初始世界生成、配方、进度等 | 适合需要从世界创建时就生效的世界生成或实验性内容 |
| 载入存档 | 打开世界或启动服务器 | 游戏尝试读取启用的数据包并注册内容 | 所有有效数据包目录 | 只有 pack.mcmeta 正确且文件能解析的数据包才会生效 |
| 热重载 | 打开词条 | 重新读取可热重载目录 | 进度、配方、函数、战利品表、谓词、物品修饰器 | 不会完整刷新世界生成、魔咒、盔甲纹饰等启动期注册内容 |
| 启用数据包 | 打开词条 | 启用指定数据包并自动重载 | 已存在但未启用的数据包 | 启用顺序会影响覆盖优先级 |
| 禁用数据包 | 打开词条 | 禁用指定数据包并自动重载 | 当前已启用的数据包 | 禁用提供关键世界数据的数据包前应备份存档 |
| 路径 | 类型 | 作用 | 是否必需 | 备注 |
|---|---|---|---|---|
| pack.mcmeta | JSON 文件 | 声明数据包说明、兼容格式和可选过滤/叠加配置 | 必需 | 无法正确读取时数据包不会被识别 |
| pack.png | PNG 图片 | 显示在数据包列表中的图标 | 可选 | 缺失或加载失败时使用默认数据包图标 |
| data/ | 目录 | 按命名空间存放数据包内容 | 通常必需 | 内容实际注册和覆盖都从命名空间目录开始 |
| data/<命名空间>/ | 目录 | 隔离自定义或原版命名空间内容 | 按内容需要 | 常见命名空间包括 minecraft 和作者自定义命名空间 |
| data/<命名空间>/tags/ | 目录 | 存放注册项标签 | 按内容需要 | 引用标签时通常写作 #<命名空间>:<路径> |
| 目录 | 内容类型 | 热重载 | 常见用途 | 版本提示 |
|---|---|---|---|---|
| advancement | 进度 JSON | 支持 | 自定义进度树、触发条件与奖励 | 旧版目录名曾使用复数 |
| recipe | 配方 JSON | 支持 | 合成、熔炼等配方定义 | 1.21 起多个旧目录改为单数 |
| function | 函数文件 | 支持 | 批量命令逻辑、标签调用、服务器自动化 | 函数标签位于 tags/function |
| loot_table | 战利品表 JSON | 支持 | 方块、生物、箱子和钓鱼等掉落规则 | 旧版目录名曾为 loot_tables |
| predicate | 谓词 JSON | 支持 | 战利品表、进度和命令中的条件判断 | 1.15 加入 |
| item_modifier | 物品修饰器 JSON | 支持 | 调整战利品生成后的物品数据 | 1.17 前后加入相关能力 |
| structure | 结构模板 | 部分 | 保存和加载结构模板 | 不属于普通注册项，但按命名空间路径加载 |
| dimension / dimension_type | 维度与维度类型 | 需重进存档 | 自定义维度、天空光照和时间规则 | 1.16 以后逐步开放 |
| worldgen/* | 世界生成 JSON | 需重进存档 | 群系、噪声、结构、地物、预设等 | 1.16.2 与 1.18.2 后能力明显扩展 |
| enchantment / enchantment_provider | 魔咒与提供器 | 需重进存档 | 自定义魔咒和魔咒来源 | 1.21 起数据驱动 |
| trim_material / trim_pattern | 盔甲纹饰 | 需重进存档 | 纹饰材料和图案 | 与锻造系统关联 |
| jukebox_song / instrument | 音乐与乐器 | 需重进存档 | 唱片机曲目和山羊角乐器 | 1.21 后持续扩展 |
| cat_variant、wolf_variant 等 | 生物变种 | 需重进存档 | 猫、狼、猪、牛、鸡、青蛙等变种 | 1.21.5 前后大量扩展 |
| dialog / timeline / world_clock | 玩法系统数据 | 需重进存档 | 对话框、时间线和世界时钟 | 1.21.6 后至 26.1 扩展 |
| villager_trade / trade_set | 交易数据 | 需重进存档 | 村民交易与交易集 | 26.1 加入 |
| 字段 | 类型 | 状态 | 用途 | 写法提示 |
|---|---|---|---|---|
| pack.description | 字符串或文本组件 | 常用 | 数据包列表中的说明文本 | 保持简短，便于玩家识别 |
| pack.pack_format | 整数 | 旧版核心 / 新版可选 | 声明基础数据包格式版本 | 兼容 1.21.8 及以前时仍建议保留 |
| pack.supported_formats | 整数、数组或对象 | 旧版可选 / 新版弃用 | 声明支持的旧版格式范围 | 新版可用 min_format 与 max_format 替代 |
| pack.min_format | 整数或 [主版本, 次版本] | 新版必需 | 声明最低兼容格式 | 1.21.9 及以后用于精确表达次版本 |
| pack.max_format | 整数或 [主版本, 次版本] | 新版必需 | 声明最高兼容格式 | 与 min_format 配合表达兼容区间 |
| filter | 对象 | 可选 | 按命名空间和正则过滤低优先级内容 | 用于避免下层数据包的特定内容被合并或继承 |
| overlays.entries | 对象数组 | 可选 | 按版本选择叠加子包 | 叠加目录会覆盖本体对应内容 |
| 编号 | 正式版本 | 关键变化 | 影响 |
|---|---|---|---|
| 4 | 1.13-1.14.4 | 加入初始数据包版本编号 | 数据包成为 Java 版自定义世界数据的基础入口 |
| 5 | 1.15-1.16.1 | 加入谓词 | 战利品表和条件判断能力增强 |
| 6 | 1.16.2-1.16.5 | 为自定义世界生成加入实验性支持 | 数据包开始承担更多世界生成配置 |
| 8-9 | 1.18-1.18.2 | 世界生成数据和密度函数扩展 | 洞穴、结构和生成规则的可配置能力增强 |
| 10-12 | 1.19-1.19.4 | pack.mcmeta filter、locate 语法、伤害类型等变化 | 旧数据包需要关注命令和谓词结构调整 |
| 15-18 | 1.20-1.20.2 | 告示牌 NBT、函数宏、状态效果 ID 等变化 | 命令、NBT 和函数数据需要迁移 |
| 26-41 | 1.20.3-1.20.6 | 文本组件更严格，物品堆叠组件替代非结构化 NBT | 物品、配方和谓词相关数据变化较大 |
| 48 | 1.21-1.21.1 | 加入魔咒和画变种定义，多个旧目录改为单数 | 旧目录名如 loot_tables、tags/items 需要迁移 |
| 57-81 | 1.21.2-1.21.8 | 加入 instrument、trial_spawner、dialog 等目录 | 数据驱动范围继续扩展到乐器、试炼刷怪笼和对话框 |
| 88.0 | 1.21.9-1.21.10 | 引入主版本和次版本，min_format / max_format 成为核心 | 跨版本数据包应调整 pack.mcmeta 兼容写法 |
| 94.1 | 1.21.11 | 新增多种物品组件和 zombie_nautilus 变种组件 | 物品检测和武器范围相关数据更细 |
| 101.1 | 26.1 | 加入世界时钟、生物音效变种和交易相关能力 | 世界规则、音效变种和交易数据可由数据包进一步控制 |
下列词条与当前机制直接相关，已优先关联到站内本地百科页面。