提取原版资源包

原版资源包是最好的老师。基本上，你只要看到原版怎么命名、怎么引用，后面的 JSON 就不会跟盘古开天一样的需要你耗费时间反推。同时，我们还要善用mc wiki和mc百科，这样我们会解决很多不必要到处问的问题。记住，独立思考的过程永远是充满乐趣的，做资源包就是这么一个过程。

普通贴图和模型

找到对应版本的游戏 jar，用压缩软件打开。大部分贴图、模型、方块状态都能在 assets/minecraft 下找到。

隐藏音效与补充资源

音频并不总是在 jar 中直接全数展示。可以使用音效提取工具补齐 sounds、sounds.json、也可以自行用修改后的编译文件修改语言资源。音效提取工具我其实有，但是用起来还是有点问题。等到研究完毕后我会第一时间发布。

再次强调：真正做自己的资源包时，不需要把所有文件夹都复制进去，除非你有特殊爱好。以下是原版资源包的大致结构

atlases/ 1

图集配置目录。控制哪些贴图会被打进不同的 atlas；普通材质替换一般只需照原版结构保留。

blockstates/ 1

方块状态目录。每个方块 JSON 根据朝向、含水、连接状态、红石强度等状态选择要渲染的模型。

equipment/ 1

装备定义目录。新版中盔甲、鞍具、翅膀等装备渲染会参考这里的配置。

font/ 2

字体配置目录。放字体 provider JSON；可引用 TTF 或 textures/font 中的 bitmap 字体贴图。

items/ 1

物品模型映射目录。1.21.5+ 的重点目录，用来决定物品在不同组件、命名、展示上下文下使用哪个模型。

lang/ 1

语言目录。放 zh_cn.json、en_us.json 等语言键值；可用于改物品名、UI 文案、容器标题和自定义语言。

models/ 3

模型目录。储存方块、物品和父模型 JSON，通常由 blockstates 或 items 指向。

particles/ 1

粒子描述目录。控制粒子使用的贴图列表和资源定位。

post_effect/ 1

后处理效果目录。用于部分屏幕效果或实体视角效果；普通材质包可先只作为参考。

resourcepacks/ 1

原版内置资源包目录。第三方资源包通常不需要向这里新增内容。

shaders/ 4

原版着色器目录。包含 core、include、post 等渲染文件；和 Iris/光影包不是同一套体系，入门阶段建议少改。

sounds/ 338

音频目录。放 .ogg 音效文件；真正的事件名、音量、随机池通常还要配合 sounds.json。

texts/ 1

长文本目录。包括终末之诗、致谢名单、闪烁黄字等文本资源。

textures/ 154

贴图目录。资源包最常修改的区域，包含方块、物品、实体、GUI、字体、粒子、盔甲纹饰等 PNG。

train_hat_info/ 1

我也不知道这是啥玩意。头部数据？真没看懂。

waypoint_style/ 1

可用于自定义路径点样式。

完整逐文件夹请查看参考栏目的“资源目录索引”。

资源包读取靠的是路径和命名空间。minecraft:item/… 这类写法最终都会映射到 assets/minecraft/... 下的具体文件；如果只改钻石剑贴图这种简单的行为，只需要改png文件就行，不需要也没必要复制完整原版 tree。

pack.mcmeta-让游戏识别你的资源包

一个最小可识别资源包，需要根目录存在 pack.mcmeta 和 assets 文件夹。图标是一个可选项，使用同级的 pack.png。如果没有图标，游戏会显示默认的资源包图标。

pack.mcmeta · 1.21.4 示例

{
  "pack": {
    "pack_format": 46,
    "description": "请输入文本",
    "supported_formats": [1, 99]
  },
  "language": {
    "zh_koneko_belown": {
      "name": "自定义中文",
      "region": "KonekoBelown",
      "bidirectional": false
    }
  }
}

字段	作用
`pack_format`	资源包推荐版本。文档示例中 1.21.4 使用 46。
`description`	资源包描述。可以使用 `\n` 换行，也可以使用 `\u00a7` 表示 Minecraft 颜色代码符号。
`supported_formats`	兼容版本范围。示例 `[1, 99]` 是为了避免游戏显示红色不兼容提示。——然而这个不兼容解决方案还没等到需要让99写成100的时候就被新写法的不向下兼容给肘死了

pack.mcmeta · 1.21.11 示例

{
  "pack": {
    "description": "请输入文本",
    "min_format": 74,
    "max_format": 99
  },
  "language": {
    "zh_koneko_belown": {
      "name": "自定义中文",
      "region": "KonekoBelown",
      "bidirectional": false
    }
  }
}

新版结构用 min_format 和 max_format 取代旧式 pack_format / supported_formats 的写法。维护 1.21.11 资源包时，建议把旧版和新版分开，不要强行混用。

mojang我操他妈了个逼的私募万一也是个畜生来的，写文件规则不向下兼容旧版本，新版资源包无法被旧版本正常识别，要想被旧版本不冲突识别那在新版本就会显示成损坏资源包，要他妈逼的做一个全版本通用的资源包就得他妈的写两套mcmeta，他妈的傻吊

注意：.mcmeta采用的是json语法，所有标点符号均为英文符号。资源包无法识别时，优先检查 pack.mcmeta 是否是合法 JSON。

自定义字体

字体不仅能换字形，还能把小图标、小抄、UI 提示塞进文本系统里（感谢 @药水棒冰的梧桐加减法资源包提供了此灵感）。核心文件在 assets/minecraft/font 与 assets/minecraft/textures/font。
此处教程参阅了Minecraft Wiki的相关说明，Minecraft Wiki真的是贼好用一wiki，你遇到原版相关的问题尽管查阅就是了。

我先把我最经常用的两种字体类型发出来，基本上我材质包里面大多数功能都是靠的这俩。

TTF 字体

这玩意我觉得都不用介绍了其实。字体文件放在 assets/minecraft/font/font.ttf，写一下字体 JSON 就能直接用。

bitmap 字体

这玩意能把某个字符渲染成图片。图片放在 assets/minecraft/textures/font，通过 chars 绑定字符。

TTF 字体 provider

{
  "providers": [
    {
      "type": "ttf",
      "file": "minecraft:font.ttf",
      "shift": [0, 0],
      "oversample": 5,
      "size": 8,
      "skip": ""
    }
  ]
}

bitmap 字体 provider

{
  "providers": [
    {
      "type": "bitmap",
      "file": "minecraft:font/lizi.png",
      "chars": ["例"],
      "height": 256,
      "ascent": 20
    }
  ]
}

这玩意在下文有详细说明，不只是可以替换这些常用文字，否则也太糟了。unicode有个私人编码区，就是专门给这种特殊字符预留的。

常用参数怎么理解

oversample 控制字体清晰度，越高越清晰，但调的太高的话性能负担也很高。size 控制渲染大小，你想要多大字就自己调着写。shift 是水平和垂直偏移（单个bitmap的偏移需要用space字段设置，下文有提及）bitmap 的 height 控制图片渲染高度，最大不能超过256.ascent 控制基线位置，且不能大于 height。

以下是根据wiki内容整理的完整讲解

详解前言

自定义字体在原版地图制作、数据包界面、资源包 UI、小图标、小抄、动作栏、标题图像里面都有用。它的核心逻辑其实很简单：单纯就是让“某个字符”在 Minecraft 里显示成“某张图”或者“某个别的字符”。

比如你把 \ue001 这个字符绑定到一张金币 PNG，那么以后在语言文件、title、tellraw、物品名里输出 \ue001，游戏看到的就不是普通文字，而是金币图标。这就是自定义字体最常用、也最实用的地方。

总的来讲：文字系统，也就是lang文件这些，负责输出字符；而字体系统，也就是assets/minecraft/font/下的各类json，负责决定字符长什么样。我们做 bitmap 为首的杂七杂八的字体，本质上就是把某个字符的字形换成像素图。

基础概念：字符、码位和字形

字符 Character

字符是文字系统里的基本单位。汉字、英文字母、数字、符号，甚至某些 emoji，都是字符。

字符代码 Character Code

计算机需要用数字表示字符。比如在某个极简系统里，可以规定 a 是 1、b 是 2、c 是 3。这个编号就是字符代码。

字形 Glyph

字符只是抽象编号，真正画到屏幕上的图形才是字形。字体文件或 bitmap provider 决定了这个字符最后长什么样。

所以，A 这个字符可以用正常英文字体显示成 A，也可以在你的资源包里被强行显示成一个按钮、一枚金币、一条魔法值。这就像给一个字符换皮。只不过换太常见的字符会把语言文件一起污染，你也不想看到你的游戏里大伙的聊天框、头顶的名字都是金币钻石满天飞吧？所以不要乱来。

Unicode 和码位

Unicode 是一种常见的字符编码标准。它给大量语言文字、符号、emoji 分配了统一编号。这个编号一般用十六进制表示，写文章时常加 U+ 前缀，比如 A 的码位是 U+0041。

概念	范围或例子	说明
基本多文种平面 BMP	`U+0000`–`U+FFFF`	最常见的一批字符都在这里。Minecraft 资源包里常用的 `\ue000` 也在这里。
辅助平面	`U+10000` 以上	包含大量 emoji、扩展汉字、古文字等。写法通常比 BMP 麻烦一些。
码位 Code Point	`U+E001`、`U+1F9D9`	一个字符在 Unicode 里的编号。

我们也许看到过 UCS-2、UCS-4 这类说法。简单理解就行：UCS-2 大致对应 0000 到 FFFF 的 2 字节范围，UCS-4 则能表示更大的范围。后来实际使用中更多会讲 UTF-8、UTF-16 这些编码形式。

UTF-8、UTF-16 和 Minecraft 里要怎么写

Unicode 是“字符编号标准”，UTF-8、UTF-16 是“把这些编号存进计算机”的方式。资源包文件一般建议保存为 UTF-8,这样中文、英文、私用区字符都能比较正常地写进 JSON 或 mcfunction。

写法环境	例子	说明
JSON / lang / font	`"\ue001"`	最常用。BMP 范围内的私用区字符可以直接用 4 位 `\u` 转义。
JSON 中的辅助平面字符	`"\ud83e\uddd9"`	JSON 本身只认 4 位 `\uXXXX` 转义。辅助平面通常要写成 UTF-16 代理对。
SNBT 1.21.5+	`\x41`、`\u0100`、`\U0001f9d9`	SNBT 字符串里可以用 2 位、4 位或 8 位形式。位数不能乱省。

别把位数写错：\u0100 是合法的 4 位写法，写成 \u100 就不对。机器不是人，它不会主动帮你猜。

私人使用区 PUA：最适合塞自定义图标的区域

Unicode 里有一个协议叫私人使用区（Private Use Area，PUA）。这些码位不会被 Unicode 官方分配给固定字符，意思就是：这地方你自己用吧我们不管你。对于资源包来说，这玩意非常适合拿来放图标、UI 小抄、数值条状态、菜单符号。

区域	范围	可用编码数量	资源包建议
BMP 私人使用区	`U+E000`–`U+F8FF`	6,400 个	最推荐。可以直接写成 `\ue000`、`\ue001` 这种形式，够用且好管理。
补充私人使用区 A	`U+F0000`–`U+FFFFD`	65,534 个	数量很大，但写法、编辑器显示、代理对处理都更麻烦。
补充私人使用区 B	`U+100000`–`U+10FFFD`	65,534 个	适合超大型项目做严格分区，普通资源包基本用不上。
合计	三个私人使用区	137,468 个	一般项目只用 BMP 私人使用区就已经非常够了。

举个实际分区方案：\ue000–\ue0ff 放基础 UI 图标，\ue100–\ue1ff 放菜单图标，\ue200–\ue2ff 放数值条状态，\ue300 以后再留给别的系统。这样后面维护的时候不会变成赛博坟场。当然，你大可以乱分，到时候把font的zip和lang文件这些乱七八糟的丢给ai让它给你一键划分。这些都无所谓，看你自己喜好了

语言文件中使用私用区图标

{
  "item.minecraft.diamond": "钻石 \ue001",
  "container.example.magic": "\uf814§f\ue200"
}

结论：如果你要把像素图替换到某个文字或字符上，非必要条件下别碰常见汉字、英文字母和标点。用私人使用区，干净，稳定，不容易把正常文本一起炸了。

字形提供器 provider

字形提供器是自定义字体的核心。它负责告诉游戏：遇到某个字符时，到底应该渲染成什么图形。Minecraft 的字体 JSON 里，providers 就是一组按顺序读取的提供器。

provider 类型	作用	常见用途
`ttf`	加载 TrueType 字体。	改变文字显示风格，例如让中文或英文换字体。
`bitmap`	把字符映射到 PNG 位图。	图标、按钮、小抄、数值条、屏幕图像。
`space`	定义某些字符的水平占位宽度。	做负空格、左右偏移、把图像挪到 UI 外侧。
`reference`	引用其他字体定义。	拆分大型字体文件，避免一个默认的字体 JSON 长到打开看了一眼就想关闭编辑器。

你可以直接改 assets/minecraft/font/default.json，这样默认字体系统会直接吃到新增字符。如果你想保持独立，也可以做自己的命名空间字体，例如 assets/mcw/font/title.json，然后在文本组件里写 "font":"mcw:title"。

bitmap：把像素图绑定到字符

bitmap 是最常用的图标方案。它会把一张 PNG 按 chars 矩阵切分，然后把每个格子绑定到对应字符。比如只有一个字符时，整张图就是这个字符的字形。

单个私用区字符绑定到一张图

{
  "providers": [
    {
      "type": "bitmap",
      "file": "minecraft:font/icon_coin.png",
      "chars": ["\ue001"],
      "height": 16,
      "ascent": 12
    }
  ]
}

多个字符按矩阵切分同一张图

{
  "providers": [
    {
      "type": "bitmap",
      "file": "mcw:font/icons.png",
      "chars": [
        "\ue001\ue002",
        "\ue003\ue004"
      ],
      "height": 16,
      "ascent": 14
    }
  ]
}

上面这个例子会把 textures/font/icons.png 按 2×2 切开，四个格子分别给 \ue001、\ue002、\ue003、\ue004。这就是为什么 chars 每一行的长度必须一致。长度不一致，游戏就不知道怎么切，最后只能给你表演一个加载失败。至于你要切几行几列，这都无所谓，你就是切成臊子也不管我事。

切图注意：图片尺寸除以矩阵数量时会向下取整。比如 64×64 的图硬切成 3 行，每行高度会变成 21，最后就会丢像素。所以做图集时最好让图片尺寸能被行列数整除。

height 和 ascent：控制大小与上下位置

height 控制字形渲染高度，ascent 控制字形顶端到基线的距离。简单说：height 管大小，ascent 管上下位置。ascent 不能大于 height。

参数组合	效果
`height: 16, ascent: 16`	图像基本压在线上方，常用于小图标。
`height: 16, ascent: 8`	图像更靠中间，适合和普通文字混排。
`height: 64, ascent: 32`	适合 title 或屏幕图像，图很明显，但也会占很大的文本空间。
`height: 128, ascent: 64`	适合大 UI 图像，不适合放在普通物品名里。

如果图标在物品名里太高、太低、压住文字、或者离谱地飞到一边，优先调 height 和 ascent。如果是左右位置不对，再考虑 space 提供器做偏移。

space：左右偏移和负空格

space provider 不负责显示图片，它只负责定义某个字符占多少水平宽度。这个宽度可以是正数，也可以是负数。负数就是资源包里常说的“负空格”。

定义负空格

{
  "providers": [
    {
      "type": "space",
      "advances": {
        "\uf814": -14,
        "\uf801": -16,
        "\uf820": 32
      }
    }
  ]
}

比如你先输出 \uf814，再输出 \ue001，后面的图标就会被向左拉。容器标题、动作栏、title 屏幕图像都能靠这个做位置微调。

语言文件里组合负空格与图标

{
  "container.mcw.title_test": "\uf814§f\ue001"
}

这里加 §f 是为了防止一些ui标题默认颜色是灰色，把图标染灰。这个坑很常见。

应用：数值条

数值条的做法是提前绘制所有状态，并把每个状态绑定到不同字符。比如魔法值有 0–100 共 101 个状态，就生成 101 个图像状态，然后把它们塞进一张图集，再用 chars 矩阵绑定到 \ue200 入门的一批私用区字符。

先画满状态

先画出完整的血条、魔法条、水分条、体力条。这个是母版。

程序批量生成空状态

从右到左盖黑色矩形，或者逐渐裁切，生成 0%、1%、2%……100% 的状态。

生成字符矩阵

每生成一张状态图，就分配一个 Unicode 私用区字符。空白格用占位字符补齐，保证每一行长度一致。

数据包负责选择字符

根据记分板数值计算当前百分比，再输出对应字符。资源包负责显示，数据包负责选择。两边别混在一起想，不然脑子会开始冒烟。

如果你在程序编写上感到困难，不妨使用AI，这玩意编写出来就是服务于人的。

数值条字体映射示例

{
  "providers": [
    {
      "type": "bitmap",
      "file": "mcw:font/magic_bar.png",
      "chars": [
        "\ue200\ue201\ue202\ue203\ue204",
        "\ue205\ue206\ue207\ue208\ue209"
      ],
      "height": 16,
      "ascent": 14
    }
  ]
}

实际项目里不要手写 101 个字符，除非你有那种属性的爱好。我更建议用ai或者自己写点脚本，生成图集和字符矩阵。

应用：屏幕图像

如果要直接在屏幕上显示图形，常见做法是用 /title 输出自定义字体。比如手持某个带自定义数据的物品时，触发函数，然后输出一个大位图。

tick 中检测玩家手持物

execute if items entity @s weapon.mainhand *[custom_data~{selected_trigger:1b}] run function test:player_selected_paper

输出屏幕图像

execute unless items entity @s weapon.mainhand paper run return fail

title @s times 0 3 0

title @s title [{"text":"\uf801\ue001","font":"mcw:title","shadow_color":[0,0,0,0]}]

这里 \uf801 是负空格，负责把图像向左挪；\ue001 是真正的位图字符；font 指向你的自定义字体文件。大图一般要反复调 height、ascent 和负空格，不可能一次就刚好对齐，别和它赌气。

维护建议

建议	原因
私用区分段管理	后面图标一多，不分段会很难查。
保留字符表	建议单独维护一个表，记录 `\ue001` 对应什么图标、哪张 PNG、什么用途。
不要覆盖常用字符	把“例”“子”“A”这类字符映射成图标只是测试方便，正式包里容易出事故。
大图和小图分字体文件	物品名图标、容器 UI、title 大图最好拆开，后面调参不容易互相污染。

语言文件

语言文件位于 assets/minecraft/lang，常用简体中文文件为 zh_cn.json。它可以改物品名、方块名、界面文字，以及你在游戏里看到的任何能根据语言切换而变化的文本，也能配合 bitmap 字体显示图片。

zh_cn.json · 修改物品名

{
  "item.minecraft.diamond_sword": "钻石剑",
  "item.minecraft.netherite_sword": "下界合金剑"
}

配合 bitmap 字体插入图标

{
  "item.minecraft.diamond_sword": "钻石剑      例",
  "item.minecraft.netherite_sword": "下界合金剑      子"
}

只要 例、子 已经在 bitmap 字体中绑定到图片，语言文件里的对应字符就会渲染成图。容器 UI 小抄、物品名称旁边的小图标，都可以用这个思路实现。

拓展：声明一门自定义语言

{
  "pack": {
    "pack_format": 46,
    "description": "请输入文本",
    "supported_formats": [1, 99]
  },
  "language": {
    "zh_custom_pack": {
      "name": "自定义中文",
      "region": "KonekoBelown",
      "bidirectional": false
    }
  }
}

我并不建议新增语言。自定义语言文件最好覆盖原版语言的所有键，否则缺失内容可能回退到英文。Mod 语言也需要另行处理。

红显制作

以 @XeKr 为代表的创作者制作的红显资源包，是生电，储电，以至于几乎所有的红石玩家都所钟爱的内容。资源包创作者以其惊人的智慧和想象力，让玩家见识到了，mc并不是一定要靠f3才能获得那高深莫测的数据。以红石粉为例，power 有 0–15，四个方向有 none、side、up 等状态。

看状态

在游戏里用 F3 对准红石粉，可以看到 north、east、south、west、power 等值。

写条件

在 blockstates/redstone_wire.json 中用 when 判断状态，用 apply 应用模型。

叠数字

额外按 power 匹配 dust_0 到 dust_15 模型，就能显示信号强度。

按 power 叠加模型的基本思路

{
  "apply": {
    "model": "minecraft:block/dust_0"
  },
  "when": {
    "power": "0"
  }
},
{
  "apply": {
    "model": "minecraft:block/dust_1"
  },
  "when": {
    "power": "1"
  }
}

这个示例的效果是将不管是爬墙，单点，还是链接，只要信号为指定数目，就渲染指定的信号强度的固定模型。然而，我们需要的肯定不止于此，因此，我们需要继续对每个状态的红石粉进行语句判断索引模型。这个就交给你们自己搞了因为我懒得粘贴。

负尺寸模型与自发光模型

负尺寸模型常用于描边：正尺寸外壳渲染正常面，负尺寸外壳显示反向面。自发光则可用模型元素的 light_emission 控制视觉亮度。

在 Blockbench 处理模型

用描边插件(如Outline Creator)或复制外壳方式生成 outline 元素。

更改描边元素的负尺寸大小

负尺寸的不同大小会改变可见面的大小，形成描边相对地变宽变细的视觉效果。

按元素添加 light_emission

在模型 JSON 的目标元素中加入 light_emission，例如描边 15、本体 10。

模型元素中加入 light_emission

{
  "from": [1, 1, 4],
  "to": [5, 1, 4],
  "rotation": {
    "angle": 19,
    "axis": "x",
    "origin": [19, 8, 10]
  },
  "shade": false,
  "light_emission": 15
}

边界：light_emission 主要影响模型自身的视觉亮度，不等于真正给周围环境打光，也不一定会被手持光源类 Mod 当作光源识别。

物品模型映射（CIT）·1

第一部分先讲实战判断树。以前很多人会把这类东西统称为 CIT。现在原版 Java 版已经把一部分事情收进了 assets/<命名空间>/items/ 里的物品模型映射，这让我们得以在原版实现很多以前只有mod才能做到的事情。

来源说明：本段关于物品模型映射的基础概念，参照了Minecraft Wiki。

文件位置

物品模型映射文件放在 assets/<命名空间>/items/。例如你要改原版弩，就会覆盖 assets/minecraft/items/crossbow.json。文件本身是一个很脆弱的 JSON，一个地方的语法有问题就会把整个json肘死，让你的所有形态下的该物品都是神秘的紫黑块。

是的这次确实不是沟槽的optifine干的了。

它和模型文件的关系

items/ 里面的这些jjbb的文件负责根据物品的状态来判断要用哪个模型，models/ 里面这些勾勾八八的文件负责来判断这些模型要长什么样。前者就是一个目录，后者则是目录里面指代的具体内容。

类型	它在干嘛	常见用途
`model`	直接指定一个模型。	普通物品、判断树的叶子节点。
`condition`	判断一个真假条件，真走 `on_true`，假走 `on_false`。	是否正在使用、是否有某个组件、是否按着某个键。
`select`	读取一个枚举值，然后按 `cases` 选择模型。	渲染位置、弩装填类型、组件字符串。
`range_dispatch`	读取一个数值，按阈值选择模型。	弩拉弓进度、耐久损坏进度、物品数量、使用进度。
`composite / special`	一个负责组合多个模型，一个负责调用硬编码特殊渲染。	收纳袋、旗帜、箱子、头颅、盾牌、书这类不是普通平面物品的东西。

弩为什么适合拿来当例子

弩这玩意能搞很多花样。烟花装填了的，箭矢装填了的，没有装填的，装填123阶段的，附魔的，没附魔的，命名的，物品栏里面的，手里面的，展示框里面，展示架，还有别的乱七八糟的。你要是想，你甚至可以搞出几百种搭配。因此它特别适合用来理解物品模型映射。

我们就用我的材质包里面的弩为例子来简单说明。

弩的判断树

展示位置 display_context
├─ gui / ground / fixed / on_shelf
│  └─ 展示用模型 minecraft:item/crossbow/...
└─ fallback
   └─ 手持用模型 minecraft:item/crossbow_in_hand/...

每条分支内部再判断：
是否有 custom_name
├─ true  → cn_crossbow 系列
└─ false → 普通 crossbow 系列

随后判断 charge_type
├─ arrow  → 已装箭模型
├─ rocket → 已装烟花模型
└─ fallback
   └─ using_item
      ├─ false → 普通待机模型
      └─ true  → crossbow/pull
         ├─ < 0.58 → pulling_0
         ├─ ≥ 0.58 → pulling_1
         └─ ≥ 1.0  → pulling_2

第一层：先看展示位置

弩先用 minecraft:display_context 判断当前渲染场景。gui、ground、fixed、on_shelf 走展示用模型；其它情况走手持模型。
我不知道你们怎么想，但是我确实觉得背包里面一堆是模型，一堆是高分辨率，一堆是原版的16x确实不美观。我觉得背包里面的状态是符合16x风格的小图标才是比较好的做法。
总之，这样分开展示，美观也美观了，手里拿着也可以做得更精细。

第二层：再看有没有命名

每个展示分支里继续用 minecraft:has_component 检查 minecraft:custom_name。有铁砧命名就走 cn_crossbow 系列（我为什么会用这个够八model名字）；没有名字就走普通 crossbow 系列。

第三层：再看弩里装了什么

minecraft:charge_type 会读弩的装填状态。装箭是 arrow，装烟花是 rocket，没装或者无法匹配就走 fallback。这一栏没啥说的，确实只有这么点

第四层：没装填时，才看是否正在拉弩

fallback 里用 minecraft:using_item 判断玩家是不是正在使用这把弩。如果没有使用，就显示待机模型；如果正在使用，就交给 minecraft:crossbow/pull 按进度切换 pulling_0、pulling_1、pulling_2。

拉弩进度：range_dispatch 的核心段

{
  "type": "minecraft:range_dispatch",
  "property": "minecraft:crossbow/pull",
  "entries": [
    { "threshold": 0.58, "model": { "type": "minecraft:model", "model": "minecraft:item/crossbow/crossbow_pulling_1" } },
    { "threshold": 1.0,  "model": { "type": "minecraft:model", "model": "minecraft:item/crossbow/crossbow_pulling_2" } }
  ],
  "fallback": {
    "type": "minecraft:model",
    "model": "minecraft:item/crossbow/crossbow_pulling_0"
  }
}

其实这个地方你自己搞判断逻辑也行。我的逻辑是按照我舒服的思路来的，你要是觉得让有命名和没命名的作为俩大类也行，只要你写着舒服就好。

最小骨架

如果你只是想把“物品栏展示”和“手持展示”拆开，可以先从这个最小骨架开始。别一上来就把弩这种套娃塞满，不然f3+t之后看到手里的东西变成紫黑块还是挺难受的。

按 display_context 拆分模型

{
  "model": {
    "type": "minecraft:select",
    "property": "minecraft:display_context",
    "cases": [
      {
        "when": ["gui", "ground", "fixed", "on_shelf"],
        "model": "（这里走物品栏 / 掉落物 / 展示框 / 架子模型）"
      }
    ],
    "fallback": "（这里走手持模型）"
  }
}

完整弩示例

我把这次用到的完整 crossbow.json 放到下面了。要是想看的话可以看看，不想看的话拉jb倒你个懒b

完整 crossbow.json

crossbow.json

{
  "model": {
    "type": "minecraft:select",
    "cases": [
      {
        "when": [
          "gui",
          "ground",
          "fixed",
          "on_shelf"
        ],
        "model": {
          "type": "minecraft:condition",
          "property": "minecraft:has_component",
          "component": "minecraft:custom_name",
          "on_true": {
            "type": "minecraft:select",
            "cases": [
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow/cn_crossbow_arrow"
                },
                "when": "arrow"
              },
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow/cn_crossbow_firework"
                },
                "when": "rocket"
              }
            ],
            "fallback": {
              "type": "minecraft:condition",
              "on_false": {
                "type": "minecraft:model",
                "model": "minecraft:item/crossbow/cn_crossbow"
              },
              "on_true": {
                "type": "minecraft:range_dispatch",
                "entries": [
                  {
                    "model": {
                      "type": "minecraft:model",
                      "model": "minecraft:item/crossbow/cn_crossbow_pulling_1"
                    },
                    "threshold": 0.58
                  },
                  {
                    "model": {
                      "type": "minecraft:model",
                      "model": "minecraft:item/crossbow/cn_crossbow_pulling_2"
                    },
                    "threshold": 1.0
                  }
                ],
                "fallback": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow/cn_crossbow_pulling_0"
                },
                "property": "minecraft:crossbow/pull"
              },
              "property": "minecraft:using_item"
            },
            "property": "minecraft:charge_type"
          },
          "on_false": {
            "type": "minecraft:select",
            "cases": [
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow/crossbow_arrow"
                },
                "when": "arrow"
              },
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow/crossbow_firework"
                },
                "when": "rocket"
              }
            ],
            "fallback": {
              "type": "minecraft:condition",
              "on_false": {
                "type": "minecraft:model",
                "model": "minecraft:item/crossbow/crossbow"
              },
              "on_true": {
                "type": "minecraft:range_dispatch",
                "entries": [
                  {
                    "model": {
                      "type": "minecraft:model",
                      "model": "minecraft:item/crossbow/crossbow_pulling_1"
                    },
                    "threshold": 0.58
                  },
                  {
                    "model": {
                      "type": "minecraft:model",
                      "model": "minecraft:item/crossbow/crossbow_pulling_2"
                    },
                    "threshold": 1.0
                  }
                ],
                "fallback": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow/crossbow_pulling_0"
                },
                "property": "minecraft:crossbow/pull"
              },
              "property": "minecraft:using_item"
            },
            "property": "minecraft:charge_type"
          }
        }
      }
    ],
    "fallback": {
      "type": "minecraft:condition",
      "property": "minecraft:has_component",
      "component": "minecraft:custom_name",
      "on_true": {
        "type": "minecraft:select",
        "cases": [
          {
            "model": {
              "type": "minecraft:model",
              "model": "minecraft:item/crossbow_in_hand/cn_crossbow_arrow"
            },
            "when": "arrow"
          },
          {
            "model": {
              "type": "minecraft:model",
              "model": "minecraft:item/crossbow_in_hand/cn_crossbow_firework"
            },
            "when": "rocket"
          }
        ],
        "fallback": {
          "type": "minecraft:condition",
          "on_false": {
            "type": "minecraft:model",
            "model": "minecraft:item/crossbow_in_hand/cn_crossbow"
          },
          "on_true": {
            "type": "minecraft:range_dispatch",
            "entries": [
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow_in_hand/cn_crossbow_pulling_1"
                },
                "threshold": 0.58
              },
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow_in_hand/cn_crossbow_pulling_2"
                },
                "threshold": 1.0
              }
            ],
            "fallback": {
              "type": "minecraft:model",
              "model": "minecraft:item/crossbow_in_hand/cn_crossbow_pulling_0"
            },
            "property": "minecraft:crossbow/pull"
          },
          "property": "minecraft:using_item"
        },
        "property": "minecraft:charge_type"
      },
      "on_false": {
        "type": "minecraft:select",
        "cases": [
          {
            "model": {
              "type": "minecraft:model",
              "model": "minecraft:item/crossbow_in_hand/crossbow_arrow"
            },
            "when": "arrow"
          },
          {
            "model": {
              "type": "minecraft:model",
              "model": "minecraft:item/crossbow_in_hand/crossbow_firework"
            },
            "when": "rocket"
          }
        ],
        "fallback": {
          "type": "minecraft:condition",
          "on_false": {
            "type": "minecraft:model",
            "model": "minecraft:item/crossbow_in_hand/crossbow"
          },
          "on_true": {
            "type": "minecraft:range_dispatch",
            "entries": [
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow_in_hand/crossbow_pulling_1"
                },
                "threshold": 0.58
              },
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/crossbow_in_hand/crossbow_pulling_2"
                },
                "threshold": 1.0
              }
            ],
            "fallback": {
              "type": "minecraft:model",
              "model": "minecraft:item/crossbow_in_hand/crossbow_pulling_0"
            },
            "property": "minecraft:crossbow/pull"
          },
          "property": "minecraft:using_item"
        },
        "property": "minecraft:charge_type"
      }
    },
    "property": "minecraft:display_context"
  }
}

版本提醒：物品模型映射是 Java 版资源包机制，不是基岩版做法。你如果跟着旧教程找 models/item/*.json 里的 overrides，会发现压根没用。有些ai会给你这个写法，真的有点那啥

物品模型映射（CIT）·2

第二部分是关于附魔书、附魔武器和特殊命名材质的内容。正如第一部分所说，1.21.5 之后，物品模型映射能力增强。许多过去依赖 OptiFine CIT 的效果，开始能用原版 items 映射和 component 判断实现。

物品模型映射

入口在 assets/命名空间/items/。它决定一个物品在什么条件下使用哪个模型。

模型与贴图

实际模型放在 assets/命名空间/models/，贴图放在 assets/命名空间/textures/。

普通物品映射

{
  "model": {
    "type": "minecraft:model",
    "model": "minecraft:item/netherite_sword"
  }
}

附魔书：按 stored_enchantments 选择模型

{
  "model": {
    "type": "minecraft:select",
    "property": "minecraft:component",
    "component": "minecraft:stored_enchantments",
    "cases": [
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/enchanted_book/bane_of_arthropods_1"
        },
        "when": [
          { "minecraft:bane_of_arthropods": 1 },
          { "minecraft:bane_of_arthropods": 2 },
          { "minecraft:bane_of_arthropods": 3 },
          { "minecraft:bane_of_arthropods": 4 }
        ]
      },
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/enchanted_book/limit/bane_of_arthropods_5"
        },
        "when": [
          { "minecraft:bane_of_arthropods": 5 }
        ]
      }
    ],
    "fallback": {
      "type": "minecraft:model",
      "model": "minecraft:item/enchanted_book/enchanted_zip"
    }
  }
}

特殊命名：按 custom_name 选择模型

{
  "type": "minecraft:select",
  "property": "component",
  "component": "custom_name",
  "cases": [
    {
      "model": {
        "type": "minecraft:model",
        "model": "minecraft:item/netherite_spear_koneko"
      },
      "when": "矛爷冲击！"
    },
    {
      "model": {
        "type": "minecraft:model",
        "model": "minecraft:item/netherite_spear_undyne"
      },
      "when": ["正义之矛", "Spear of Justice"]
    }
  ],
  "fallback": {
    "type": "minecraft:model",
    "model": "minecraft:item/netherite_spear"
  }
}

实现思路：附魔书用 minecraft:stored_enchantments，普通附魔物品多用 minecraft:enchantments,特殊命名则检查 custom_name。复杂物品需要你跟套石山一样多层条件嵌套。这种亲自拉史的方式很折磨，真的很折磨。这就是为什么我很敬佩那些给武器写上全部附魔显示的创作者。

物品模型映射（CIT）·3

第三部分是把 Minecraft Wiki 里关于物品模型映射的细节重新整理成资源包作者更容易查的版本。
该段内容参照了 Minecraft Wiki：物品模型映射。

它到底是什么

物品模型映射是 Java 版资源包里的客户端渲染机制。它不会改变物品本身，也不会给物品添加功能，它只是在客户端渲染这个物品堆叠时，根据物品状态、组件、上下文、数值进度等条件选择一个模型。

文件放在 assets/<命名空间>/items/。比如原版弩对应 assets/minecraft/items/crossbow.json。这个文件选择的是“用哪个模型”，而真正模型长什么样，还要去 assets/<命名空间>/models/ 里找。

位置	作用
`assets/minecraft/items/crossbow.json`	判断弩现在该显示哪个模型。
`assets/minecraft/models/item/crossbow/xxx.json`	具体模型文件，决定形状、贴图、display 变换。
`assets/minecraft/textures/item/...`	模型引用的贴图。

不要混淆：items/ 不是旧版 models/item 的替代品。它是一个选择器，选中了哪个模型之后，游戏还是要去 models/ 读取具体模型。

根文件格式

一个物品模型映射 JSON 的根元素通常长这样：

最小物品模型映射

{
  "model": {
    "type": "minecraft:model",
    "model": "minecraft:item/diamond_sword"
  }
}

字段	作用
`model`	核心字段。里面写一个物品模型映射节点，可以是 `model`、`condition`、`select`、`range_dispatch` 等。
`hand_animation_on_swap`	切换到该物品时是否播放手部切换动画，默认 `true`。
`oversized_in_gui`	是否允许 GUI 内模型超出槽位，默认 `false`。
`swap_animation_scale`	切换动画速度倍率。模型很大的时候可以调，但一般不用一上来就碰。

常用类型总览

类型	一句话理解	适合干什么
`minecraft:model`	直接渲染某个模型。	普通物品，或判断树最后的叶子。
`minecraft:condition`	判断真假，真走 `on_true`，假走 `on_false`。	是否有组件、是否正在使用、是否按下键位。
`minecraft:select`	读取一个枚举值，然后按 `cases` 匹配。	展示位置、弩装填类型、字符串 custom_model_data。
`minecraft:range_dispatch`	读取一个数值，按阈值选择模型。	拉弩进度、耐久进度、数量、使用时间。
`minecraft:composite`	把多个模型按顺序叠起来渲染。	收纳袋、分层图标、组合显示。
`minecraft:special`	调用游戏内置的特殊渲染器。	旗帜、箱子、头颅、盾牌、书、钟等。
`minecraft:empty`	什么都不渲染。	需要隐藏某个状态时使用。

model：最普通的叶子节点

model 是最简单的节点。它只负责告诉游戏：用这个模型渲染。

model 节点

{
  "type": "minecraft:model",
  "model": "minecraft:item/netherite_sword"
}

这里的 minecraft:item/netherite_sword 会指向 assets/minecraft/models/item/netherite_sword.json。别把它写成贴图路径，也别把 models 这层硬塞进命名空间 ID 里。

condition：真假判断

condition 的思路很直白：条件为真就走 on_true，条件为假就走 on_false。比如判断物品有没有自定义名称：

has_component 判断 custom_name

{
  "type": "minecraft:condition",
  "property": "minecraft:has_component",
  "component": "minecraft:custom_name",
  "on_true": {
    "type": "minecraft:model",
    "model": "minecraft:item/custom_named_sword"
  },
  "on_false": {
    "type": "minecraft:model",
    "model": "minecraft:item/normal_sword"
  }
}

常用 property	作用
`minecraft:has_component`	检查物品有没有某个组件，例如 `minecraft:custom_name`。
`minecraft:using_item`	检查物品是否正在被使用，例如正在拉弩、吃食物。
`minecraft:custom_model_data`	读取 `custom_model_data.flags` 里的布尔值。
`minecraft:keybind_down`	检查某个键位是否被按下。
`minecraft:component`	检查某个组件是否满足指定谓词。写法更细，但也更容易写错。

select：枚举分支

select 适合处理“结果只会是几个固定值”的情况。弩的 charge_type 就是典型例子：arrow、rocket、none。

按 charge_type 匹配弩装填物

{
  "type": "minecraft:select",
  "property": "minecraft:charge_type",
  "cases": [
    {
      "when": "arrow",
      "model": {
        "type": "minecraft:model",
        "model": "minecraft:item/crossbow_arrow"
      }
    },
    {
      "when": "rocket",
      "model": {
        "type": "minecraft:model",
        "model": "minecraft:item/crossbow_firework"
      }
    }
  ],
  "fallback": {
    "type": "minecraft:model",
    "model": "minecraft:item/crossbow"
  }
}

常用 property	枚举来源
`minecraft:display_context`	当前渲染位置，例如 `gui`、`ground`、`fixed`、`firstperson_righthand` 等。
`minecraft:charge_type`	弩内装填物：`arrow`、`rocket`、`none`。
`minecraft:custom_model_data`	读取 `custom_model_data.strings` 指定下标的字符串。
`minecraft:component`	读取某个可持久化组件的值并完全匹配。
`minecraft:context_dimension`	当前维度 ID。
`minecraft:main_hand`	玩家主手是 `left` 还是 `right`。

注意：select 的 when 不能重复。重复的枚举值会直接报错。复杂文件里这个错误很难肉眼找，最好少复制粘贴之后忘记改。

range_dispatch：按数值分段

range_dispatch 用来处理连续数值。游戏会把 entries 按 threshold 从小到大排序，然后选择第一个达到阈值的模型。如果数值低于所有阈值，就走 fallback。

弩拉伸进度

{
  "type": "minecraft:range_dispatch",
  "property": "minecraft:crossbow/pull",
  "entries": [
    {
      "threshold": 0.58,
      "model": {
        "type": "minecraft:model",
        "model": "minecraft:item/crossbow_pulling_1"
      }
    },
    {
      "threshold": 1.0,
      "model": {
        "type": "minecraft:model",
        "model": "minecraft:item/crossbow_pulling_2"
      }
    }
  ],
  "fallback": {
    "type": "minecraft:model",
    "model": "minecraft:item/crossbow_pulling_0"
  }
}

常用 property	数值来源
`minecraft:crossbow/pull`	弩拉伸进度，通常在 0–1 之间。
`minecraft:damage`	耐久损坏进度，可用 `normalize` 控制是否归一化。
`minecraft:count`	物品数量，可用 `normalize` 控制读取比例还是数量。
`minecraft:use_duration`	物品使用时间或剩余使用时间。
`minecraft:cooldown`	物品冷却进度。
`minecraft:custom_model_data`	读取 `custom_model_data.floats` 指定下标的浮点数。

custom_model_data 的新版结构

新版 custom_model_data 不再只是一个老式整数思路。它可以在不同字段里塞不同类型的数据。资源包做判断时，也要看你调用的是哪类属性。

用在哪里	读取字段	适合用途
`condition + custom_model_data`	`flags`	真假开关，例如是否显示某个外观。
`range_dispatch + custom_model_data`	`floats`	数值分段，例如 0.0、0.5、1.0。
`select + custom_model_data`	`strings`	字符串分支，例如 `koneko`、`gold`、`broken`。
`model tints + custom_model_data`	`colors`	控制着色颜色。

所以你要先想清楚自己是在做布尔判断、数值区间、字符串分支，还是染色。不要看到 custom_model_data 就把所有写法混到一起。

special：特殊渲染

special 用来渲染那些不是普通平面或普通方块模型的物品。比如旗帜、箱子、头颅、盾牌、书、钟、末地传送门方块效果等。

特殊模型的大致结构

{
  "type": "minecraft:special",
  "base": "minecraft:item/template_banner",
  "model": {
    "type": "minecraft:banner",
    "color": "white"
  }
}

base 负责提供基础变换、粒子纹理等信息，model 里面再写具体特殊渲染器的配置。这个东西能做的很多，但也最容易被版本更新打断。普通资源包入门阶段，不建议拿它当主战场。

写复杂判断树的顺序

先分显示场景

物品栏、地上、展示框、手持往往需要不同模型。优先用 display_context 拆开，不然后面会混得很难看。

再分物品身份

是否命名、是否有自定义数据、是否有附魔，这些决定“它是哪一种物品”。

最后分动态状态

是否正在使用、装填了什么、拉弩进度、耐久进度，这些是“它现在是什么状态”。

每一层都留 fallback

不要相信自己永远能匹配所有情况。没有 fallback，写错时直接紫黑块，排查体验很差。

我的建议：不要上来就写五层套娃。相信我，你通常情况下不会一次成功的。

此页内容

页面信息

标题-

分类-

路径-

上一页无下一页无

从原版客户端提取参考文件

只塞你要改的文件

创建可被游戏识别的资源包骨架

小步子探索

普通贴图和模型

隐藏音效与补充资源

TTF 字体

bitmap 字体

详解前言

基础概念：字符、码位和字形

字符 Character

字符代码 Character Code

字形 Glyph

Unicode 和码位

UTF-8、UTF-16 和 Minecraft 里要怎么写

私人使用区 PUA：最适合塞自定义图标的区域

字形提供器 provider

bitmap：把像素图绑定到字符

height 和 ascent：控制大小与上下位置

space：左右偏移和负空格

应用：数值条

先画满状态

程序批量生成空状态

生成字符矩阵

数据包负责选择字符

应用：屏幕图像

维护建议

找到原版音效位置

控制音频时长

按用途选择声道

看状态

写条件

叠数字

在 Blockbench 处理模型

更改描边元素的负尺寸大小

按元素添加 light_emission

文件位置

它和模型文件的关系

弩为什么适合拿来当例子

第一层：先看展示位置

第二层：再看有没有命名

第三层：再看弩里装了什么

第四层：没装填时，才看是否正在拉弩

最小骨架

完整弩示例

物品模型映射

模型与贴图

它到底是什么

根文件格式

常用类型总览

model：最普通的叶子节点

condition：真假判断

select：枚举分支

range_dispatch：按数值分段

custom_model_data 的新版结构

special：特殊渲染

写复杂判断树的顺序

先分显示场景

再分物品身份

最后分动态状态

每一层都留 fallback

逐文件夹说明