minecraft-datapack

Minecraft Datapack Skill

编辑前，请检查 pack.mcmeta 和目标 Minecraft 版本。除非用户要求迁移，否则保留现有目标版本；仅修改元数据数字并不能让旧版命令或注册表架构变得兼容。使用随附的验证器检查编辑后的文件，并在条件允许时进行游戏内测试。

Skill Scope

Routing Boundaries

• Use when：交付内容是数据包文件（pack.mcmeta、data/...）以及 .mcfunction/JSON 内容。
• Do not use when：请求仅涉及未关联到数据包文件树的命令片段（minecraft-commands-scripting）。
• Do not use when：请求需要加载器 API、Java 代码或运行时模组行为（minecraft-modding）。

---

Pack Metadata

Minecraft 版本	首选 pack 元数据
1.21 / 1.21.1	pack_format: 48
1.21.2 / 1.21.3	pack_format: 57
1.21.4	pack_format: 61
1.21.5	pack_format: 71
1.21.6	pack_format: 80
1.21.7 / 1.21.8	pack_format: 81
1.21.9 / 1.21.10	min_format: [88, 0], max_format: [88, 0]
1.21.11	min_format: [94, 1], max_format: [94, 1]
26.1	min_format: [101, 1], max_format: [101, 1]
26.2	min_format: [107, 1], max_format: [107, 1]

对于仅面向旧版、数据包格式不高于 81 的目标，请使用 pack_format。从 1.21.9 的数据包格式 82 开始，请同时定义明确的 min_format 和 max_format 值。若范围包含低于 82 的旧版格式，则还必须保留 pack_format 和 supported_formats；仅面向现代版本的范围则不要包含 supported_formats。 对于兼容旧版的范围，supported_formats 可以是一个整数、两个整数构成的闭区间，或包含整数 min_inclusive 和 max_inclusive 字段的对象。 若要精确指定补丁版本，请在 min_format 和 max_format 中都使用 [major, minor] 数组，包括 [88, 0] 这类 .0 版本。对于 min_format，单个整数等同于 [major, 0]；对于 max_format，单个整数则允许该主版本线上的任意次版本。不要使用 94.1 这样的 JSON 小数。

请针对目标补丁版本准确设置 pack.mcmeta，不要尝试用一个元数据块涵盖多个 Minecraft 版本。

---

Directory Layout

my-datapack/
├── pack.mcmeta
└── data/
    ├── <namespace>/           ← use your pack's name (e.g., mypack)
    │   ├── function/
    │   │   ├── main.mcfunction
    │   │   └── tick.mcfunction
    │   ├── advancement/
    │   │   └── custom_advancement.json
    │   ├── recipe/
    │   │   └── custom_recipe.json
    │   ├── loot_table/
    │   │   └── custom_loot.json
    │   ├── predicate/
    │   │   └── is_night.json
    │   ├── item_modifier/
    │   │   └── add_name.json
    │   └── tags/
    │       ├── block/
    │       │   └── climbable.json
    │       ├── entity_type/
    │       │   └── bosses.json
    │       └── function/
    │           └── custom_flow.json  ← manually invoked tag
    └── minecraft/
        └── tags/function/
            ├── load.json             ← engine tag; runs on /reload
            └── tick.json             ← engine tag; runs every game tick

---

pack.mcmeta

1.21.8 及更早版本

{
  "pack": {
    "pack_format": 81,
    "description": "My Custom Datapack v1.0"
  }
}

有意设置的旧版到现代版本兼容范围

仅当数据包确实同时支持格式 82 两侧的版本时，才使用此形式。Mojang 要求此范围保留旧版字段。

{
  "pack": {
    "pack_format": 81,
    "supported_formats": [81, 88],
    "min_format": [81],
    "max_format": [88],
    "description": "My compatible datapack"
  }
}

1.21.9 / 1.21.10

{
  "pack": {
    "min_format": [88, 0],
    "max_format": [88, 0],
    "description": "My Custom Datapack v1.0"
  }
}

1.21.11

{
  "pack": {
    "min_format": [94, 1],
    "max_format": [94, 1],
    "description": "My Custom Datapack v1.0"
  }
}

26.2

{
  "pack": {
    "min_format": [107, 1],
    "max_format": [107, 1],
    "description": "My Custom Datapack v1.0"
  }
}

---

函数标签（load / tick）

引擎识别 minecraft:load 和 minecraft:tick 标签，因此这些文件必须使用 minecraft 命名空间。自定义命名空间中的 load.json 或 tick.json 是有效的自定义标签名，但不会触发任何自动行为。

data/minecraft/tags/function/load.json

{
  "values": [
    "<namespace>:setup"
  ]
}

data/minecraft/tags/function/tick.json

{
  "values": [
    "<namespace>:tick"
  ]
}

data/<namespace>/function/setup.mcfunction

# Runs once on /reload
scoreboard objectives add deaths deathCount
scoreboard objectives add kills playerKillCount
tellraw @a {"text":"[MyPack] Loaded!","color":"green"}

data/<namespace>/function/tick.mcfunction

# Runs every tick — KEEP THIS SHORT
# Only put fast, targeted operations here
execute as @a[scores={deaths=1..}] run function mypack:on_death_check

---

命令和函数语法

Execute 子命令（数据包专用模式）

# Chained execute — common datapack pattern for conditional per-player logic
execute as @a[gamemode=!spectator] at @s if block ~ ~-1 ~ #minecraft:logs run give @s minecraft:apple

# store result into score (bridge between NBT world and scoreboard state)
execute store result score @s mypack.health run data get entity @s Health

# in: run logic in another dimension
execute in minecraft:the_nether run say This runs in the Nether

存储 NBT（数据包专用全局状态）

# Storage is the datapack-native key-value store — persists across /reload
data modify storage mypack:data config.difficulty set value "hard"
data get storage mypack:data config.difficulty

# Copy live entity data into storage for macro use or cross-function state
data modify storage mypack:log last_player_pos set from entity @s Pos

有关完整的命令语法、选择器和计分板操作，请参阅 Minecraft Wiki — Commands。 minecraft-commands-scripting skill 深入介绍仅涉及命令的工作。

---

宏（1.20.2+）

宏函数允许向函数传递动态参数。

定义宏函数（data/mypack/function/greet.mcfunction）

# Macro argument: $(name)
$tellraw @a {"text":"Welcome $(name)!","color":"gold"}
$scoreboard players set $(name) points 0

使用 run function + with 调用

# Pass values from storage
data modify storage mypack:tmp input set value {name:"Steve"}
function mypack:greet with storage mypack:tmp input

# Pass values from entity NBT
function mypack:greet with entity @p {}

# Pass value from block NBT
function mypack:greet with block 0 64 0 {}

---

注册表数据示例

编写进度、配方、战利品表、谓词或标签时，请阅读 references/data-examples.md。 仅加载相关章节，并保留现有命名空间和版本目标。

世界生成覆盖项

覆盖生物群系噪声（data/minecraft/worldgen/noise_settings/overworld.json）

在现有副本中编辑 — 不要在没有完整 JSON 的情况下从头创建。 从 Minecraft jar 中获取原版版本：jar xf minecraft.jar data/

覆盖生物群系的生成消耗

{
  "spawn_costs": {
    "minecraft:zombie": {
      "energy_budget": 0.12,
      "charge": 0.7
    }
  }
}

---

安装与测试

将数据包文件夹或 ZIP 放在世界的 datapacks/ 目录下，并确保 pack.mcmeta 位于其根目录。然后使用以下游戏内命令：

/datapack list
/datapack enable "file/my-datapack"
/datapack disable "file/my-datapack"
/reload

开发工作流

1. 编辑 .mcfunction 或 .json 文件
2. 运行捆绑的验证器，在加载前检查 JSON 和路径错误：

   ./scripts/validate-datapack.sh --root /path/to/datapack
   

3. 如果有错误，请修复并重新验证，直至无误
4. 在游戏内运行 /reload（如果某个模组拦截了该命令，则运行 /minecraft:reload）
5. 使用目标命令进行测试（例如，运行 /function mypack:setup、触发一项进度）
6. 检查 latest.log 中的运行时错误（缺少引用、错误的选择器）

---

常见错误

错误	原因	修复方法
Unknown or invalid command	函数中的语法错误	检查空白、选择器和尾随空格
Datapack did not load	任意文件中的 JSON 无效	使用 jq . < file.json 验证
pack metadata mismatch	pack_format 或 min_format / max_format 值错误	根据准确的 1.21.x 补丁版本更新 pack.mcmeta
函数未在刻时运行	缺少引擎刻标签或命名空间错误	检查 data/minecraft/tags/function/tick.json
宏错误	存在 $ 行，但没有 with	提供 with storage/entity/block

验证器脚本

发布数据包更新前，请使用捆绑的验证器脚本：

# Run from the installed skill directory (for example `.codex/skills/minecraft-datapack`):
./scripts/validate-datapack.sh --root /path/to/datapack

# Strict mode treats warnings as failures:
./scripts/validate-datapack.sh --root /path/to/datapack --strict

检查内容：

• pack.mcmeta 和 data/**/*.json 的 JSON 有效性
• 战利品表、函数和方块／物品／函数标签路径中的旧式复数化错误
• data/minecraft/tags/function/load.json 和 tick.json 中的引用是否指向本地 .mcfunction 文件
• 自定义命名空间中的 load.json 和 tick.json 名称；这些名称有效，但不会自动运行

---

参考资料

• Minecraft Wiki — 数据包：https://minecraft.wiki/w/Data_pack
• Minecraft Java Edition 1.21.9 发布说明：https://www.minecraft.net/en-us/article/minecraft-java-edition-1-21-9
• Minecraft Wiki — 函数：https://minecraft.wiki/w/Function_(Java_Edition)
• Minecraft Wiki — 命令：https://minecraft.wiki/w/Commands
• 数据包格式历史：https://minecraft.wiki/w/Pack_format
• NBT 格式：https://minecraft.wiki/w/NBT_format
• 谓词条件：https://minecraft.wiki/w/Predicate
• 战利品表格式：https://minecraft.wiki/w/Loot_table