资源包与自定义模型

所属：服主指南　·　相关：物品定义 · 碎片与模板

QI 物品可以声明自定义模型数据（CustomModelData）或 1.20.5+ 的模型资源路径，配合你的资源包显示自定义外观。

---

1. 声明方式

物品定义里用 resource_pack 段：

demo_sword:
  type: sword
  material: diamond_sword
  resource_pack:
    custom_model_data: 12345           # 数字 CMD（1–99999）
    model: "custom/legendary_sword"    # 1.20.5+ 模型资源路径

键	含义
custom_model_data	自定义模型数据整数。优先级高于 options.custom_model_data
model	1.20.5+ 模型资源位置（namespace:path 格式）

也可以只用 options.custom_model_data（见 物品定义 → options），但若 resource_pack.custom_model_data 也设了，以后者为准。

---

2. 校验约束（重要）

QI 对 resource_pack 有严格的隔离策略（ResourcePackValidator / ResourcePackIsolationPolicy）。保存 / 重载时若违反会报错。

允许

• custom_model_data：整数 ≥ 0
• model：namespace:path 格式，不含空格

禁止（会报 [RP_POLICY] 错误）

禁止内容	原因
引用变量：{}、%var%、${}	模型不能绑定到 ICVM / 变量
层 / 动作 token：layer、action、trigger、handler 等	模型不能依赖层 / 动作
条件渲染：if、when、unless、switch、random、weight	模型不能含条件分支

设计意图：资源包外观必须是静态、确定的，不能随物品状态 / 变量动态变化。这样物品外观与游戏逻辑解耦，避免难以调试的渲染问题。

报错示例：

resource_pack.custom_model_data 不能为负数 (-5)
resource_pack.model 需 namespace:path 格式，got 'invalid'
[RP_POLICY] ResourcePack cannot reference ICVM variables — resource_pack.model: '{var}'
resource_pack 含禁止字段 [conditions, layer] — 仅允许 custom_model_data / model

---

3. 模型目录（编辑器用）

integrations/resource_models.yml 是给编辑器（模型选择器）用的静态模型目录，按分类列出可选模型，无运行时过滤、无层 / 星级绑定：

categories:
  weapons:
    - qi:katana/01
    - qi:katana/02
  armor:
    - qi:helm/01
  misc:
    - qi:gem/01

GUI 里选模型时（资源包编辑器）从这里取候选。

---

4. 两条「自定义外观」路线

QI 给物品换皮有两条互斥的路线，按你的资源包方案二选一：

路线	怎么写	适合
A. 自带资源包 + CMD/模型	resource_pack.custom_model_data 或 resource_pack.model，配合你自己的资源包	你自己做模型、走原版材质 + CMD
B. 借外部插件成品当底模	material: ce:xxx / nexo:xxx / ia:xxx 等	已经用 CraftEngine / ItemsAdder / Nexo 管模型，直接复用

走路线 B 时，外部物品自带模型 / CMD / 组件，所以不需要再设 resource_pack.custom_model_data——重复设反而可能覆盖外部模型。

路线 B：外部物品源引用

material 写成带 : 或 - 的引用即可：

my_skin_sword:
  type: weapon
  material: craftengine:dragon_blade   # 或 ce-dragon_blade
  display_name: "<gold>龙焰之刃</gold>"
  # 不写 resource_pack —— 外观由 CraftEngine 物品自带
  providers:
    ap: { value: '{"attack_damage":30}' }   # QI 只管属性/动作/Lore

支持的前缀（ce / ia / nexo / mi / ni / mm …）与完整语法、排错见 物品定义 → 5.1 外部物品源引用。

💡 路线 B 的分工：外部插件出外观，QI 出属性 / 动作 / 套装 / 绑定 / 宝石孔。等于给别家的皮套上 QI 的一整套 RPG 逻辑。

---

下一步

• 物品定义：options 视觉字段
• 编辑器 GUI → 其他编辑器：资源包 / 模型选择器