minecraft-datapack

Minecraft データパックスキル

編集前に pack.mcmeta と対象の Minecraft バージョンを確認してください。移行が依頼されていない場合は、既存の対象バージョンを維持してください。メタデータの数値だけを変えても、古いコマンドやレジストリのスキーマに互換性が生じるわけではありません。編集したファイルは同梱のバリデーターで確認し、可能な場合はゲーム内でもテストしてください。

スキルの対象範囲

振り分けの境界

• Use when：成果物がデータパックのファイル（pack.mcmeta、data/...）および .mcfunction／JSON コンテンツである場合に使用します。
• Do not use when：データパックのファイルツリーに関連付けられていない、コマンドのみのスニペットを依頼された場合（minecraft-commands-scripting）。
• Do not use when：ローダー API、Java コード、または実行時の MOD 動作が必要な場合（minecraft-modding）。

---

パックのメタデータ

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 に整数を 1 つ指定するか、2 つの整数による包括範囲を指定するか、整数の min_inclusive フィールドと max_inclusive フィールドを持つオブジェクトを指定できます。 特定のパッチバージョンを対象にする場合は、.0 のバージョン（[88, 0] など）も含め、min_format と max_format の両方に [major, minor] 配列を使用してください。min_format の単一の整数は [major, 0] と同等ですが、max_format に単一の整数を指定すると、そのメジャーバージョン系列の任意のマイナーバージョンが許可されます。94.1 のような小数の JSON 数値は記述しないでください。

1 つのメタデータブロックで複数の Minecraft リリースを網羅しようとせず、対象とするパッチバージョンに合わせて pack.mcmeta を正確に設定してください。

---

ディレクトリ構成

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 スキルでは、コマンドのみの作業を詳しく扱います。

---

マクロ（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 を実行します（または、MOD が割り込む場合は /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 を更新します
ファンクションが tick 時に実行されない	エンジンの tick タグがない、または名前空間が誤っている	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