minecraft-resource-pack

Minecraft 资源包技能

什么是资源包？

资源包是一个文件夹（或 .zip），用于覆盖或添加 Minecraft 的视觉和音频资源：纹理、模型、声音、语言文件和字体。对于这些原版资源，无需 Java 或模组加载器。

适用范围

• Use when：交付内容是资源包格式的视觉／音频资源（纹理、模型、声音、字体）。
• Do not use when：任务需要更改游戏玩法逻辑或运行时行为（使用 minecraft-datapack、minecraft-plugin-dev 或 minecraft-modding）。
• Do not use when：任务涉及服务器基础设施／运行时管理（使用 minecraft-server-admin）。

---

资源包元数据

Minecraft 版本	首选 pack 元数据
1.21 / 1.21.1	pack_format: 34
1.21.2 / 1.21.3	pack_format: 42
1.21.4	pack_format: 46
1.21.5	pack_format: 55
1.21.6	pack_format: 63
1.21.7 / 1.21.8	pack_format: 64
1.21.9 / 1.21.10	min_format: [69, 0]、max_format: [69, 0]
1.21.11	min_format: [75, 0]、max_format: [75, 0]
26.1	min_format: [84, 0]、max_format: [84, 0]
26.2	min_format: [88, 0]、max_format: [88, 0]

仅对低于 65 的资源格式（截至 1.21.8）使用旧版 pack_format。 资源格式 65 及更高版本要求同时设置 min_format 和 max_format；要精确指定补丁版本，请使用 [major, minor]，包括 .0，例如 [84, 0]。 整数或 [major] 形式的 min_format 表示 [major, 0]；整数或 [major] 形式的 max_format 允许该主版本系列的所有次版本。不要编写十进制 JSON 数字。仅使用旧格式的资源包可单独使用整数 pack_format。如果范围内的 min_format 包含旧版格式，则需要整数 pack_format 和 supported_formats；仅包含现代格式的范围不要包含 supported_formats。

---

目录结构

my-pack/
├── pack.mcmeta
├── pack.png                   ← 64×64 icon (optional)
└── assets/
    └── minecraft/             ← override vanilla (or <namespace>/ for new packs)
        ├── models/
        │   ├── block/
        │   │   └── stone.json
        │   └── item/
        │       └── diamond_sword.json
        ├── items/              ← 1.21.4+ item model definitions
        │   └── diamond_sword.json
        ├── blockstates/
        │   └── stone.json
        ├── textures/
        │   ├── block/
        │   │   └── stone.png
        │   ├── item/
        │   │   └── diamond_sword.png
        │   ├── gui/
        │   │   └── sprites/
        │   │       └── my_sprite.png
        │   └── entity/
        │       └── zombie/
        │           └── zombie.png
        ├── sounds/
        │   └── custom/
        │       └── my_sound.ogg
        ├── sounds.json
        ├── font/
        │   └── default.json
        └── lang/
            └── en_us.json

OptiFine CIT 和 Iris 着色器包等客户端模组专用文件使用各自的格式。添加这些文件前，请阅读条件资源。

---

pack.mcmeta

1.21.8 及更早版本

{
  "pack": {
    "pack_format": 64,
    "description": "My Custom Resource Pack v1.0"
  }
}

1.21.9 / 1.21.10

{
  "pack": {
    "min_format": [69, 0],
    "max_format": [69, 0],
    "description": "My Custom Resource Pack v1.0"
  }
}

1.21.11

{
  "pack": {
    "min_format": [75, 0],
    "max_format": [75, 0],
    "description": "My Custom Resource Pack v1.0"
  }
}

26.2

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

---

方块模型

assets/minecraft/models/block/my_cube.json

完整方块——六个面均使用相同纹理：

{
  "parent": "minecraft:block/cube_all",
  "textures": {
    "all": "minecraft:block/stone"
  }
}

柱状方块（例如原木）：

{
  "parent": "minecraft:block/cube_column",
  "textures": {
    "end": "mypack:block/my_pillar_top",
    "side": "mypack:block/my_pillar_side"
  }
}

不同侧面：

{
  "parent": "minecraft:block/cube",
  "textures": {
    "up":    "mypack:block/my_block_top",
    "down":  "mypack:block/my_block_bottom",
    "north": "mypack:block/my_block_side",
    "south": "mypack:block/my_block_side",
    "east":  "mypack:block/my_block_side",
    "west":  "mypack:block/my_block_side",
    "particle": "mypack:block/my_block_side"
  }
}

交叉模型（花、植物）：

{
  "parent": "minecraft:block/cross",
  "textures": {
    "cross": "mypack:block/my_flower"
  }
}

自定义几何体（elements）

{
  "credit": "Custom model",
  "ambientocclusion": true,
  "textures": {
    "0": "mypack:block/panel",
    "particle": "mypack:block/panel"
  },
  "elements": [
    {
      "from": [0, 0, 7],
      "to": [16, 16, 9],
      "faces": {
        "north": { "texture": "#0", "uv": [0, 0, 16, 16] },
        "south": { "texture": "#0", "uv": [0, 0, 16, 16] }
      }
    }
  ],
  "display": {
    "thirdperson_righthand": {
      "rotation": [75, 45, 0],
      "translation": [0, 2.5, 0],
      "scale": [0.375, 0.375, 0.375]
    }
  }
}

from 和 to 的单位是方块的 1/16（0–16）。uv 的格式为 [x1, y1, x2, y2]，单位范围为 0–16。

---

物品模型

对于 1.21.4 及更高版本，请在 assets/<namespace>/items/ 中使用物品定义。对于 1.21.3 及更早版本，请使用旧版模型的 overrides 数组。有关基于字符串的当前 custom_model_data 选择器和旧版数字谓词，请阅读条件资源；它们的值不能互换。

---

方块状态定义

简单方块（无变体）

{
  "variants": {
    "": { "model": "mypack:block/my_block" }
  }
}

朝向方块（4 种旋转）

{
  "variants": {
    "facing=north": { "model": "mypack:block/my_block" },
    "facing=south": { "model": "mypack:block/my_block",  "y": 180 },
    "facing=east":  { "model": "mypack:block/my_block",  "y": 90  },
    "facing=west":  { "model": "mypack:block/my_block",  "y": 270 }
  }
}

随机纹理（multipart）

{
  "variants": {
    "": [
      { "model": "minecraft:block/grass_block",  "weight": 3 },
      { "model": "minecraft:block/grass_block_2" }
    ]
  }
}

Multipart（台阶、栅栏、墙）

{
  "multipart": [
    { "apply": { "model": "mypack:block/my_slab_bottom" }, "when": { "type": "bottom" } },
    { "apply": { "model": "mypack:block/my_slab_top"    }, "when": { "type": "top"    } },
    { "apply": { "model": "mypack:block/my_block"        }, "when": { "type": "double" } }
  ]
}

---

纹理

• 格式：PNG，RGBA（32 位）
• 标准方块／物品尺寸：16×16 px
• 纹理可以更大（32×32、64×64）——Minecraft 会缩放纹理，但请使用 2 的幂次方尺寸
• 动画要求高度 = N × 宽度（例如，4 帧时为 16×64）
• 将方块纹理放在 assets/<namespace>/textures/block/
• 将物品纹理放在 assets/<namespace>/textures/item/
• 在 JSON 中引用所有纹理时，不带 .png 扩展名

动画纹理 MCMETA

assets/minecraft/textures/block/fire_0.png.mcmeta：

{
  "animation": {
    "frametime": 2,
    "frames": [0, 1, 2, 3, 4, 5, 6, 7]
  }
}

如果省略 frames，则所有帧会按顺序播放。frametime 的单位是游戏刻（默认值为 1）。

GUI sprites (1.20.2+)

将精灵图放在 assets/minecraft/textures/gui/sprites/<category>/<name>.png。 在代码/JSON 中使用 <category>/<name> 引用。

26.1 方块模型纹理条目

对于 26.1，方块模型的 textures 条目可以仍然是精灵图字符串，也可以使用 对象。对象必须包含字符串类型的 sprite；如果设置了 force_translucent，则 必须为布尔值。

{
  "textures": {
    "all": {
      "sprite": "mypack:block/frosted_panel",
      "force_translucent": true
    }
  }
}

两种形式都能在不带 .png 的情况下标识精灵图。仅当几何体必须在半透明渲染阶段绘制，而精灵图像素本身不具备半透明效果时，才使用 force_translucent。

---

声音

事件的命名空间来自包含 sounds.json 的命名空间；声音条目的 name 用于标识声音文件的命名空间。声音文件为 Vorbis .ogg 格式，位于 assets/<namespace>/sounds/ 下。阅读 条件资源，了解正确的事件示例、别名、声音来源选择和替换行为。

---

语言文件

assets/minecraft/lang/en_us.json：

{
  "block.mypack.my_block": "My Custom Block",
  "item.mypack.my_item": "Magic Wand",
  "entity.mypack.my_mob": "Forest Guardian",
  "death.attack.mypack.laser": "%1$s was zapped by %2$s"
}

• 为模组/数据包命名空间使用准确的翻译键格式
• 文件名为区域设置代码（例如，fr_fr.json、de_de.json）
• 始终提供 en_us.json 作为主要回退

---

字体

阅读条件资源，了解位图提供器布局和专用区图标指南。

---

OptiFine 和着色器

OptiFine CIT 和 Iris 着色器包使用客户端模组专属格式。添加任一内容前，请阅读条件资源； 它们不是可移植的原版资源包功能。

---

安装

# Singleplayer: place in
~/.minecraft/resourcepacks/my-pack/
# or
~/.minecraft/resourcepacks/my-pack.zip

# Server-side (forces on clients):
# Set in server.properties:
resource-pack=https://example.com/my-pack.zip
resource-pack-sha1=<sha1 hash>
resource-pack-prompt={"text":"Required pack","color":"gold"}

---

常见问题

问题	原因	修复方法
模型未显示	JSON 路径错误或语法错误	检查 assets/<namespace>/models/ 路径；验证 JSON
黑色/粉色棋盘格	纹理路径错误或文件缺失	检查 textures/ 路径；JSON 中不包含文件扩展名
方块状态未生效	状态属性名称错误	使用 F3 检查方块状态；使用 /data get block <x> <y> <z> 获取方块实体 NBT
动画未生效	MCMETA 位置错误	必须与纹理位于同一文件夹，命名为 texture.png.mcmeta
自定义声音未播放	未在 sounds.json 中注册	在 sounds.json 中注册声音事件，并确保命名空间匹配
数据包未加载	pack_format 或 min_format / max_format 值错误	根据准确的 1.21.x 补丁版本更新 pack.mcmeta

验证器脚本

发布资源包更新前，请使用随附的验证器脚本：

未打包的其他命名空间模型、纹理、声音或字体引用会产生警告，需要在依赖项存在时进行运行时验证。当前命名空间中的缺失文件会导致验证失败；严格模式下，未解决的警告也会导致验证失败。

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

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

检查内容：

• 验证 pack.mcmeta 和 assets/**/*.json 的 JSON 格式
• 检查旧版与现代版 pack.mcmeta 字段格式，包括整数、[major] 和 [major, minor] 版本
• 检查模型/方块状态/字体/声音引用是否能解析到实际文件
• 检查当前 custom_model_data 选择案例是否使用字符串；26.1 纹理对象是否使用字符串类型的 sprite 和可选的布尔类型 force_translucent
• 检查同一命名空间的 type: "event" 声音别名是否指向该 sounds.json 中的事件
• 检查每个 *.png.mcmeta 是否都有对应的 *.png

验证器无法解析由其他命名空间拥有的声音事件，也无法证明某条命令或模组代码会以预期的声音来源调用事件。 这些情况会产生警告，需要在准确的客户端环境中进行运行时检查。

---

参考资料

• Mojang：Java Edition 1.21.4
• Mojang：Java Edition 1.21.9
• Mojang：Java Edition 26.1
• NeoForge 1.21.8：声音
• Misode 的模型查看器：https://misode.github.io/
• OptiFine CIT 指南：https://optifine.readthedocs.io/cit.html