碎片（Fragment）与模板

所属：服主指南　·　相关：变量 · 层与装配

碎片是可复用的物品 YAML 片段：把多件物品共享的字段（材质、Lore、变量、属性、选项）抽出来一处维护、多处引用。配置文件：plugins/QinhItems/fragments/*.yml。

---

1. 碎片是什么

类比编程里的「mixin / 模板继承」。一个碎片（QinhItemFragment）可包含：material / displayName / itemName / lore / variables / providers / options。物品用 fragments: 列表引用，编译时合并进来。

---

2. 定义碎片

# fragments/weapon_base.yml
id: weapon_base                  # 碎片 ID（或用文件名）

# 结构化排版下碎片 lore 会并入物品描述段，留空避免重复
lore: []

variables:
  base_tier: "1"

碎片字段都可选，只写要共享的部分。

---

3. 在物品里引用

# items/sword.yml
sword_iron:
  type: sword
  material: iron_sword
  fragments:
    - weapon_base               # 引入 base_tier 变量等
  display_name: "<white>铁剑</white>"

---

4. 合并规则（模板编译）

TemplateCompiler 把 YAML 编译成 QinhItemDefinition，合并优先级（后者覆盖前者）：

1. 碎片（按 fragments: 列表顺序）
2. override 段（override.material / override.variables / …）
3. 根级字段（最高优先级）

Lore 有两种合并模式（override.lore_mode）：

• append（默认）：碎片 Lore + 覆盖 Lore 叠加
• replace：用覆盖 Lore 替换碎片 Lore

dragon_blade:
  fragments:
    - weapon_base
  override:
    lore_mode: append
    variables:
      base_tier: "5"            # 覆盖碎片的 base_tier
  variables:
    extra: "x"                  # 根级，最高优先级

---

5. 编译产物：能力扁平化

编译时 CapabilityCompiler 会把物品定义扁平化成「能力清单」，供编辑器 / 工具读取（如 skill / attribute / render / set 各自有哪些特性）。这是内部产物，服主一般无需关心。

---

6. 资源包声明

碎片 / 物品可声明自定义模型，详见 资源包。resource_pack 段最终编译成 ResourcePackDeclaration。

---

7. 注册表（开发者）

FragmentRegistry.get(id): QinhItemFragment?
FragmentRegistry.allIds(): List<String>
FragmentRegistry.reload(folder)

碎片在 /qi reload 时从 fragments/ 目录重新加载。

---

8. 库清单（Library Manifest）

「库」是把一组类型 / 能力打包的内容包元数据（LibraryManifest），用于内容分发与编辑器分组。结构：

weapon_library:
  display_name: "武器包"
  version: "v1.0"
  description: "核心武器（剑、弓、锤）"
  category: "weapons"
  types: [sword, bow, hammer]
  capabilities: [SKILL, ATTRIBUTE, RENDER]
  dependencies: [base_items_library]
  author: "QinhItems Team"

未显式配置时会从 QinhItemTypeRegistry 按 library-category 自动生成。开发者细节见 层与装配。

---

下一步

• 变量：碎片里声明可复用变量
• 资源包：自定义模型
• 层与装配：模板 / 装配内部