Fragments and Templates

Belongs to: Server Owner Guide　·　Related: Variables · Layers and Assembly

A Fragment is a reusable item YAML snippet: it extracts fields shared by multiple items (material, lore, variables, attributes, options) so they can be maintained in one place and referenced from many. Config files: plugins/QinhItems/fragments/*.yml.

---

1. What Is a Fragment

Think of it as a "mixin / template inheritance" from programming. A Fragment (QinhItemFragment) can contain: material / displayName / itemName / lore / variables / providers / options. Items reference them via a fragments: list, and they are merged in at compile time.

---

2. Defining a Fragment

# fragments/weapon_base.yml
id: weapon_base                  # Fragment ID (or use the file name)

# Under structured layout, fragment lore is merged into the item's description section; leave empty to avoid duplication
lore: []

variables:
  base_tier: "1"

All fragment fields are optional; only write the parts you want to share.

---

3. Referencing It in an Item

# items/sword.yml
sword_iron:
  type: sword
  material: iron_sword
  fragments:
    - weapon_base               # Pulls in the base_tier variable, etc.
  display_name: "<white>Iron Sword</white>"

---

4. Merge Rules (Template Compilation)

TemplateCompiler compiles YAML into a QinhItemDefinition. Merge priority (later overrides earlier):

1. Fragments (in the order of the fragments: list)
2. The override section (override.material / override.variables / …)
3. Root-level fields (highest priority)

Lore has two merge modes (override.lore_mode):

• append (default): fragment lore + override lore are stacked
• replace: override lore replaces fragment lore

dragon_blade:
  fragments:
    - weapon_base
  override:
    lore_mode: append
    variables:
      base_tier: "5"            # Overrides the fragment's base_tier
  variables:
    extra: "x"                  # Root level, highest priority

---

5. Compilation Output: Capability Flattening

At compile time, CapabilityCompiler flattens the item definition into a "capability manifest" for editors / tools to read (e.g. which features each of skill / attribute / render / set has). This is an internal artifact; server owners generally don't need to worry about it.

---

6. Resource Pack Declaration

Fragments / items can declare custom models; see Resource Packs for details. The resource_pack section is ultimately compiled into a ResourcePackDeclaration.

---

7. Registry (Developers)

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

Fragments are reloaded from the fragments/ directory on /qi reload.

---

8. Library Manifest

A "library" is content-pack metadata (LibraryManifest) that bundles a group of types / capabilities, used for content distribution and editor grouping. Structure:

weapon_library:
  display_name: "Weapon Pack"
  version: "v1.0"
  description: "Core weapons (sword, bow, hammer)"
  category: "weapons"
  types: [sword, bow, hammer]
  capabilities: [SKILL, ATTRIBUTE, RENDER]
  dependencies: [base_items_library]
  author: "QinhItems Team"

When not explicitly configured, it is auto-generated from QinhItemTypeRegistry by library-category. For developer details see Layers and Assembly.

---

Next Steps

• Variables: declare reusable variables inside fragments
• Resource Packs: custom models
• Layers and Assembly: inside templates / assembly