Resource Packs and Custom Models

Belongs to: Server Admin Guide　·　Related: Item Definition · Fragments and Templates

QI items can declare custom model data (CustomModelData) or a 1.20.5+ model resource path, displaying a custom appearance together with your resource pack.

---

1. How to Declare

Use the resource_pack section in the item definition:

demo_sword:
  type: sword
  material: diamond_sword
  resource_pack:
    custom_model_data: 12345           # Numeric CMD (1–99999)
    model: "custom/legendary_sword"    # 1.20.5+ model resource path

Key	Meaning
custom_model_data	Custom model data integer. Higher priority than options.custom_model_data
model	1.20.5+ model resource location (namespace:path format)

You can also just use options.custom_model_data (see Item Definition → options), but if resource_pack.custom_model_data is also set, the latter takes precedence.

---

2. Validation Constraints (Important)

QI applies a strict isolation policy to resource_pack (ResourcePackValidator / ResourcePackIsolationPolicy). Violations raise an error on save / reload.

Allowed

• custom_model_data: integer ≥ 0
• model: namespace:path format, no spaces

Forbidden (raises a [RP_POLICY] error)

Forbidden Content	Reason
Variable references: {}, %var%, ${}	A model cannot be bound to ICVM / variables
Layer / action tokens: layer, action, trigger, handler, etc.	A model cannot depend on layers / actions
Conditional rendering: if, when, unless, switch, random, weight	A model cannot contain conditional branches

Design intent: A resource pack appearance must be static and deterministic; it cannot change dynamically based on item state / variables. This decouples item appearance from game logic and avoids hard-to-debug rendering issues.

Error examples:

resource_pack.custom_model_data cannot be negative (-5)
resource_pack.model requires namespace:path format, got 'invalid'
[RP_POLICY] ResourcePack cannot reference ICVM variables — resource_pack.model: '{var}'
resource_pack contains forbidden fields [conditions, layer] — only custom_model_data / model are allowed

---

3. Model Catalog (for the Editor)

integrations/resource_models.yml is a static model catalog used by the editor (model picker). It lists selectable models by category, with no runtime filtering and no layer / star-rating binding:

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

When you pick a model in the GUI (Resource Pack Editor), candidates are pulled from here.

---

4. Two "Custom Appearance" Routes

QI offers two mutually exclusive routes for reskinning an item; pick one based on your resource pack setup:

Route	How to Write	Best For
A. Own resource pack + CMD/model	resource_pack.custom_model_data or resource_pack.model, together with your own resource pack	You make your own models, using vanilla materials + CMD
B. Use an external plugin's product as the base material	material: ce:xxx / nexo:xxx / ia:xxx, etc.	You already manage models with CraftEngine / ItemsAdder / Nexo and want to reuse them directly

When using route B, the external item comes with its own model / CMD / components, so you do not need to set resource_pack.custom_model_data again — setting it redundantly may actually override the external model.

Route B: External Item Source References

Write material as a reference containing : or -:

my_skin_sword:
  type: weapon
  material: craftengine:dragon_blade   # or ce-dragon_blade
  display_name: "<gold>Dragonflame Blade</gold>"
  # No resource_pack —— appearance comes from the CraftEngine item itself
  providers:
    ap: { value: '{"attack_damage":30}' }   # QI only handles attributes/actions/Lore

For the supported prefixes (ce / ia / nexo / mi / ni / mm …), full syntax, and troubleshooting, see Item Definition → 5.1 External Item Source References.

💡 The division of labor in route B: the external plugin provides the appearance, QI provides attributes / actions / sets / bindings / gem sockets. This wraps another plugin's skin with QI's full suite of RPG logic.

---

Next Steps

• Item Definition: options visual fields
• Editor GUI → Other Editors: resource pack / model picker