数据包

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

使用数据包

数据包是可被添加到<存档根目录>/datapacks/目录下的文件夹或.zip压缩包或文件夹。

在“创建新世界”页面中选择数据包将会缓存至Java临时文件目录/mcworld-[19~20位数字]目录下。

添加数据包

在创建新世界界面中添加数据包

默认的数据包配置

在创建世界前，玩家可以在创建新的世界屏幕的“更多”选项卡中配置数据包。与配置资源包的界面类似，玩家可以自由选择数据包的加载顺序和启用情况，并可以搜索数据包。

加载数据包

玩家每次加载存档时游戏都会尝试加载一次数据包。

在正在运行的游戏存档中，可以使用命令/reload来重新加载数据包。

• 数据包中的进度、配方、函数、战利品表、谓词和物品修饰器目录的文件会被重新加载。
• 对于剩余数据包目录的文件，例如世界生成、魔咒、盔甲纹饰和唱片机曲目等，游戏仅会在服务端启动时加载一次，也即必须重新进入存档时游戏才会重新加载这些文件，命令/reload无法重新加载。
  • 这些目录的文件若出现语法错误或无注册元素等情况，可能导致进入存档时出现“安全错误”提醒，在禁用这些数据包前游戏拒绝加载存档。

不论是哪种加载方式，只有有效的数据包才会被加载。这要求数据包：

• 数据包元数据被游戏正确加载。
• 数据包中的任何文件均无语法错误且能被成功解析，若文件无法被正常解析则对应文件不会生效或在进入存档时出现“安全错误”提醒。

加载顺序

在创建存档之前，配置数据包的界面中的数据包顺序就是游戏加载存档时使用的顺序。

在存档被创建后，玩家可以使用命令/datapack list来获取数据包加载顺序。数据包加载顺序存储在存档的level.dat的DataPacks标签内。

禁用数据包

• 在已经载入的世界中，玩家可以使用命令/datapack disable来手动禁用一个数据包。执行成功后，游戏会自动重新加载一次数据包。

启用数据包

• 在已经载入的世界中，玩家可以使用命令/datapack enable来手动启用一个已经被禁用了的数据包。执行成功后，游戏会自动重新加载一次数据包。

实验性设置

实验性设置警告屏幕

一些数据包内容被游戏标记为实验性，如果存档启用了这些数据包，则玩家在尝试加载存档时会弹出实验性设置警告屏幕。

目前会触发实验性设置的数据包内容都是不可热重载的内容，即必须通过重新加载存档来加载的内容。只要客户端接收到的数据包内容和原版数据包内容不同，就会触发实验性设置屏幕。

目录结构

• / <数据包名称>：根目录。
  •  pack.mcmeta：数据包元数据。
  •  pack.png：数据包图标。
  •  data
    •  <命名空间>
      •  datapacks：实验性内容的内置数据包目录，仅限于游戏内部使用，无法由自定义数据包提供。
      •  function：函数文件目录。
      •  structure：结构模板文件目录。
      • 以下所有文件均为JSON文件：
      •  advancement：进度文件目录。
      •  banner_pattern：旗帜图案文件目录。
      •  cat_variant：猫变种文件目录。
      •  chat_type：聊天类型文件目录。
      •  chicken_variant：鸡变种文件目录。
      •  cow_variant：牛变种文件目录。
      •  damage_type：伤害类型文件目录。
      •  decorated_pot_pattern^{[新增：JE 26.3]}：饰纹陶罐图案文件目录。
      •  dialog：对话框文件目录。
      •  dimension：维度文件目录。
      •  dimension_type：维度类型文件目录。
      •  enchantment：魔咒文件目录。
      •  enchantment_provider：魔咒提供器文件目录。
      •  frog_variant：青蛙变种文件目录。
      •  instrument：山羊角乐器文件目录。
      •  item_modifier：物品修饰器文件目录。
      •  jukebox_song：唱片机曲目文件目录。
      •  loot_table：战利品表文件目录。
      •  number_provider^{[新增：JE 26.3]}：数值提供器文件目录
      •  painting_variant：画变种文件目录。
      •  predicate：谓词文件目录。
      •  pig_variant：猪变种文件目录。
      •  recipe：配方文件目录。
      •  slot_source^{[新增：JE 26.3]}：槽位源文件目录。
      •  sulfur_cube_archetype：硫方怪原型文件目录。
      •  tags：数据包标签根目录。
        •  function：函数标签目录。
        •  <注册名>：此注册项的标签目录。绝大多数注册项都可以定义标签。
      •  timeline：时间线文件目录。
      •  test_environment：测试环境文件目录。
      •  test_instance：测试实例文件目录。
      •  trade_set：交易集文件目录。
      •  trial_spawner：试炼刷怪笼配置文件目录。
      •  trim_material：纹饰材料文件目录。
      •  trim_pattern：纹饰图案文件目录。
      •  villager_trade：村民交易文件目录。
      •  wolf_sound_variant：狼音效变种文件目录。
      •  wolf_variant：狼变种文件目录。
      •  world_clock：世界时钟文件目录。
      •  worldgen：世界生成根目录。
        •  biome：生物群系文件目录。
        •  carver^{[新增：JE 26.3]}：已配置的雕刻器文件目录。
        •  configured_carver^{[失效：JE 26.3]}：已配置的雕刻器文件目录。
        •  configured_feature^{[失效：JE 26.3]}：已配置的地物文件目录。
        •  density_function：密度函数文件目录。
        •  feature^{[新增：JE 26.3]}：已配置的地物文件目录。
        •  flat_level_generator_preset：超平坦世界生成预设文件目录。
        •  material_condition^{[新增：JE 26.3]}：材料规则文件目录。
        •  material_rule^{[新增：JE 26.3]}：材料条件文件目录。
        •  multi_noise_biome_source_parameter_list：多噪声生物群系源参数列表文件目录。
        •  noise：噪声文件目录。
        •  noise_settings：噪声设置文件目录。
        •  placed_feature：已放置的地物文件目录。
        •  processor_list：处理器列表文件目录。
        •  structure：结构文件目录。
        •  structure_set：结构集文件目录。
        •  template_pool：模板池文件目录。
        •  world_preset：世界预设文件目录。
      •  zombie_nautilus_variant：僵尸鹦鹉螺变种文件目录。

数据包基础结构

数据包元数据

数据包需要指定元数据才能被游戏识别为一个数据包。数据包元数据位于数据包根目录，其名称为pack.mcmeta，使用JSON格式，内部元素如下：

• ：根对象。
  • *pack：存放数据包信息。
    • *description：（文本组件）数据包的描述信息。在创建世界的数据包页面，或光标在/datapack list命令列出的数据包名称上悬停时，会显示此描述。
    • *min_format：数据包兼容的最低版本号，为两个整数组成的数组，依次为主要版本号和次要版本号。单个整数被视为次要版本号0，如94、[94]等价于[94, 0]。
    • *max_format：数据包兼容的最高版本号，为两个整数组成的数组，依次为主要版本号和次要版本号。单个整数被视为次要版本号0x7fffffff。
    • pack_format：已弃用，为兼容性而保留。数据包的基础版本。
    • supported_formats：已弃用，为兼容性而保留。此数据包支持的数据包版本范围。
      • 整数范围，见Template:Nbt inherit/int inclusive range/source
  • overlays：指定要覆盖的部分，即应用在“标准”包内容上的子包。其目录是其自己的资源和data目录（存放于包的根目录下）。
    • *entries：覆盖列表。其顺序很重要，列表中的第一个对象将被首先应用。
      • 
        • *directory：此子包所在的相对路径。允许的字符：a-z、0-9、_和-。
        • min_format：此叠加数据包生效的最低版本号。
        • max_format：此叠加数据包生效的最高版本号。
        • *formats：已弃用，为兼容性而保留。此叠加数据包生效的数据包版本范围。
          • 整数范围，见Template:Nbt inherit/int inclusive range/source
  • filter：包过滤器，用于指定数据包要忽略的文件。在block内被匹配到的任何模式都将形如其不在该数据包中存在。
    • block：模式列表。
      • ：
        • namespace：一个正则表达式，表示要滤除文件的命名空间。若省略则匹配所有命名空间。
        • path：一个正则表达式，表示要滤除文件的路径。若省略则匹配所有文件。
  • features：要启用的实验性内容。注意：如果添加了该字段，则该数据包需要在创建新世界的时候添加，否则在更改旧世界的level.dat前无法添加。
    • *enabled：启用的内容。
      • ：（命名空间ID）一项实验性内容。可用值见实验性内容 § 数据值。

示例

以下为pack.mcmeta的编写示例：

{
    "pack": {
        "description": "示例数据包",
		"pack_format": 81,
        "supported_formats": [48, 81]
    }
}

{
    "pack": {
        "description": "示例数据包",
		"min_format": [88, 0],
        "max_format": [107, 1]
    }
}

{
    "pack": {
        "description": "示例数据包，同时支持旧版与新版格式",
		"pack_format": 107,
        "supported_formats": [48, 107],
		"min_format": 48,
        "max_format": [107, 1]
    }
}

数据包图标

默认数据包纹理

数据包根目录下可以添加一个pack.png作为数据包的图标，这个图标会在创建新的世界屏幕中的数据包列表中渲染。

如果数据包没有图标，或图标加载错误，游戏会使用默认资源包纹理assets/minecraft/textures/misc/unknown_pack.png作为此数据包的图标。

数据包内容

数据包的具体内容详见§ 目录结构，以下介绍内容的加载。

数据包的data下包含了不同的命名空间目录，每个命名空间目录下的每个文件夹都对应了一个注册项，以存储不同的数据包内容。在加载数据包时：

• 每个位于数据包data/<命名空间>/<注册名>/<路径>.json的文件会在对应的注册项下注册ID为<命名空间>:<路径>的内容。
  • 尽管函数和结构模板不属于注册项，但加载过程类似。
• 每个位于数据包data/<命名空间>/tags/<注册名>/<路径>.json的文件会在对应的注册项下注册ID为<命名空间>:<路径>的标签。引用标签时通常会带上#前缀，即#<命名空间>:<路径>。
  • 结构模板、进度和配方不具有标签。

如果加载了多个数据包，且不同的数据包对同一个文件进行了定义，则上层数据包的文件优先级高于下层数据包的文件。

如果数据包具有叠加目录，则叠加目录的内容会覆盖数据包本体的对应内容。此覆盖是完全覆盖，即使对应文件的加载行为是默认合并，此数据包也只会加载最后一个叠加数据包的数据。

数据包版本

下表粗略描述了各正式版的数据包版本编号及其数据包内容的变化：

数据包版本

编号	正式版本	标志性/破坏性更改
4	1.13–1.14.4	加入了初始的数据包版本编号4。
5	1.15–1.16.1	加入了谓词。
6	1.16.2–1.16.5	为自定义世界生成加入了实验性支持。
7	1.17–1.17.1	/replaceitem命令变为了/item命令。set_damage战利品函数现在需要一个有效的type字段。
8	1.18–1.18.1	加入了一系列实验性快照中世界生成的新特性。 战利品表现在需要一个type字段。 移除了对记分板、分数持有者和队伍名的长度限制。
9	1.18.2	加入了实验性数据包加入自定义结构和配置洞穴生成机制的支持。 加入了密度函数，对自定义世界生成进行了更新。现在/locate命令第一个参数为已配置的结构，而非一个结构类型，故对于那些成组的结构现在需要使用结构类型标签。例如/locate village现在变为/locate #village。
10	1.19–1.19.3	数据包元数据文件pack.mcmeta现在带有一个filter字段。 以/locate命令合并了/locatebiome，同时改变了其语法。
12	1.19.4	加入了伤害类型。 移除了伤害谓词中的所有的布尔型标志，取而代之的是伤害类型标签。 生物群系字段precipitation变为has_precipitation。
15	1.20–1.20.1	改变了告示牌的NBT。例如Text1现在应为front_text.messages[0]。 所有在placed_block、item_used_on_block以及allay_drop_item_on_block进度触发器中的字段，都已经被折叠到位置（location）字段中。 重命名alternative谓词为any_of。
18	1.20.2	加入了函数宏。NBT中的状态效果现在为命名空间ID而非数值。例如1现在为minecraft:speed。
26	1.20.3–1.20.4	文本组件的解析变得更加严格。重命名grass方块及物品为short_grass。记分板可设置显示名称和数字格式。
41	1.20.5–1.20.6	重命名sweeping魔咒为sweeping_edge。 改变了item_used_on_block进度触发器的行为。 将一些倍率超过127的状态效果的行为使用属性来替代。 物品堆叠（Item Stack）相关的非结构化NBT数据被结构化的物品堆叠组件取代。 重命名了谓词中的durability、potions、nbt以及enchantments字段。 配方的合成物现在可以指定物品组件。 世界生成数据格式中的整型和浮点型提供器不再包裹于靠近type字段的额外字段value中。 加入了一个物品子谓词以及新的战利品函数。
48	1.21–1.21.1	加入了魔咒定义格式和画变种定义格式。 重命名物品子谓词中的enchantment字段为enchantments重命名诸如loot_tables和tags/items的旧版文件夹名为loot_table和tags/item。 移除了火球power标签，并将其替换为acceleration_power。 属性现在有单独的命名空间ID字段id，而非一个name和uuid。
57	1.21.2–1.21.3	加入了trial_spawner和instrument子文件夹以用于配置试炼刷怪笼和山羊角乐器。 为玩家子谓词加入了input字段。加入了新的实体子谓词，将进度触发器killed_by_crossbow重命名为killed_by_arrow，并加入了新可选物品谓词字段fired_from_weapon，用于匹配发射箭的物品。 加入了配方类型crafting_transmute，移除了配方类型crafting_special_shulkerboxcoloring。 魔咒效果damage_item被重命名为change_item_damage，以允许负值。
61	1.21.4	移除了“冬季小更新”内置数据包和winter_drop功能开关。
71	1.21.5	大幅更改了SNBT格式与文本组件的格式。加入了/test命令。更改了大量实体保存，移除，与更改其NBT时的行为。
80	1.21.6	添加了由服务器授权的路径点广播系统以用于配置玩家的定位栏行为。添加了dialog子文件夹以用于配置对话框。 添加了文本组件的点击事件custom，点击带有此组件的文本时会使客户端向服务端发送minecraft:custom_click_action专用数据包。 为维度类型定义文件添加了一个新的可选字段cloud_height，用以指定维度中云层渲染的起始高度。
81	1.21.7–1.21.8
88.0	1.21.9–1.21.10	修改了数据包的格式，弃用了supported_formats。pack_format现在是可选的；加入了必选字段min_format和max_format。
94.1	1.21.11	加入了物品组件use_effect、minimum_attack_charge、damage_type、kinetic_weapon、piercing_weapon、swing_animation、attack_range，组件zombie_nautilus/variant。 将字段min_reach、max_reach和hitbox_margin从物品组件piercing_weapon和kinetic_weapon移到新组件attack_range中，使得所有近战武器都能使用上述字段。 支持对某一物品是否带有某物品组件进行检测。
101.1	26.1	加入了世界时钟和生物的音效变种定义格式。 加入了物品组件dye。 加入了minecraft:crafting_dye和minecraft:crafting_imbue配方类型，移除了crafting_special_armordye、minecraft:crafting_special_mapcloning和minecraft:crafting_special_tippedarrow配方类型。 除物品修复配方外，所有的定制配方现在均可以一定程度地控制输入与输出。 更改了存档格式和存档基础数据存储格式。 猪灵和村民的物品栏可以使用mob.inventory.*访问，移除了villager.*。
107.1	26.2

历史

Java版
1.13			17w43a				加入了数据包。
			17w46a				加入了/datapack命令，用于控制加载的数据包。
			17w48a				现在数据包可读取自定义配方。
			18w01a				崩溃报告中现在会列出启用的数据包。
1.15			19w38a				加入了predicates文件夹，可以在此处定义战利品表谓词。
			pre1				数据包版本号更改为5。
1.16			20w22a				稍微修改了数据包的加载机制，防止数据包带来的崩溃。
							游戏将会检测严重的数据包问题，比如关键标签的缺失，将会阻止世界的加载。
							如果数据包加载失败，那么修改将不会被应用，游戏将会使用旧的数据包。
							数据包列表仅在数据包成功加载后才会更改。
							服务器添加了--safeMode选项让游戏只加载原版数据包。
			pre1				现在可以在创建世界之前加载数据包。
							数据包现在可以添加和修改维度。
1.16.2			20w28a				现在数据包可配置自定义世界生成。
			rc1				数据包版本号更改为6。
1.17			20w45a				pack_version被拆分，数据包和资源包现在使用相互独立的版本数字。
			20w46a				由于MC-204861，数据包版本号更改为7。
							加入了item_modifiers子文件夹。
1.18			21w37a				由于加入了一系列实验性快照中世界生成的新特性，数据包版本号更改为8。
1.18.2			pre1				现在可在实验性数据包中添加自定义结构，即游戏现在可生成并存储由数据驱动的配置的结构。
							现在可通过数据包对一些洞穴生成机制进行配置。
							由于对数据包加入了以上新功能，数据包版本号更改为9。
1.19			22w11a				在pack.mcmeta中加入了filter字段，用于按命名空间和正则表达式忽略低优先级数据包中的匹配内容。
							由于对数据包加入了以上新功能，数据包版本号更改为10。
			22w18a				加入了chat_type子文件夹。
1.19.3			22w42a				加入了datapacks子文件夹，包含用于启用特定功能的原版数据包（功能数据包）。
							原版世界生成数据包现在在游戏的jar文件中可见。故诸如dimension_type、worldgen之类的内容都可见。
1.19.4			23w06a				加入了damage_type子文件夹。
1.20.2			23w31a				现在数据包可以与多个游戏版本兼容。
							加入了对叠加目录的支持，允许同一数据包在不同的游戏版本中加载不同的资源，并需要pack.mcmeta中的overlays部分来定义。
1.20.5			24w05a				物品或实体中的状态效果实例数据不再编码默认值。
			24w10a				加入了banner_pattern和​wolf_variant子文件夹。
1.21			24w18a				加入了enchantment、​enchantment_provider和​painting_variant子文件夹。
			24w21a				将structures、​advancements、​recipes、​loot_tables、​predicates、​item_modifiers和​functions文件夹重命名为对应的单数形式。
							加入了jukebox_song子文件夹。
1.21.2			24w33a				加入了instrument子文件夹。
			24w35a				加入了trial_spawner子文件夹。
1.21.5			25w02a				加入了pig_variant子文件夹。
			25w03a				加入了test_environment和test_instance子文件夹。
			25w04a				加入了cat_variant和frog_variant子文件夹。
			25w05a				加入了cow_variant子文件夹。
			25w06a				加入了chicken_variant子文件夹。
			25w08a				加入了wolf_sound_variant子文件夹。
1.21.6			25w20a				加入了dialog子文件夹。
1.21.9			25w31a				为数据包版本号引入了次要版本的概念，一并修改了pack.mcmeta的格式。
1.21.11			25w45a				加入了zombie_nautilus_variant和timeline子文件夹。
26.1			snapshot-1				加入了villager_trade和trade_set子文件夹。
			snapshot-3				加入了world_clock子文件夹。
			snapshot-7				加入了pig_sound_variant、​cat_sound_variant、​cow_sound_variant和​chicken_sound_variant子文件夹。
26.2			snapshot-1				加入了sulfur_cube_archetype子文件夹。
Java版（即将到来）
26.3			snapshot-1				加入了decorated_pot_pattern、​slot_source、​worldgen/material_condition和​worldgen/material_rule子文件夹。加入了carver、feature子文件夹。以替换先前的configured_carver、configured_feature子文件夹
			snapshot-3				加入了number_provider子文件夹。

参见

• 附加包
• 资源包
• Tutorial:制作数据包
• Tutorial:优化数据包

外部链接

• misode.github.io，一个数据包生成器。
• Pack.mcmeta Generator on misode.github.io，pack.mcmeta生成器。