Skip to main content

🖌️ Appearance

Overview​

Item appearance is controlled by the pack section in each item config and by the appearance systems enabled in settings.yml. Oraxen generates the required resource pack files (models, textures, and item definitions) based on those settings.

info

On 1.21.4+, Oraxen can combine multiple appearance systems - The modern minecraft:item_model component and CustomModelData dispatchers. On older versions, it always falls back to legacy predicate overrides with integer CustomModelData.

Configuration​

Appearance is configured per item in .yml files inside plugins/Oraxen/items, while the model/texture assets live in plugins/Oraxen/pack.

  • 📁 plugins
    • 📁 Oraxen
      • 📁 items
        • 📄 weapons.yml
        • 📄 foods.yml
      • 📁 pack
        • 📁 models
          • 📄 ice_sword.json
        • 📁 textures
          • 📄 ice_sword.png
my_item:
  material: IRON_SWORD
  pack:
    model: weapons/swords/ice_sword

Appearance Modes​

The appearance systems are configured in plugins/Oraxen/settings.yml under Pack.generation.appearance. This controls what resource pack files are generated by Oraxen.

Pack:
  generation:
    appearance:
      item_properties: true
      model_data_ids: false
      model_data_float: false
      generate_predicates: false
🧩 item_properties

Uses the minecraft:item_model component (1.21.4+) with keys like oraxen:<item_id>. Oraxen generates item definition files at assets/oraxen/items/<item_id>.json that point to your model.

🏷️ model_data_ids

Uses custom_model_data.strings[0] = "oraxen:<item_id>" and generates assets/minecraft/items/<material>.json with minecraft:select dispatchers.

🔢 model_data_float

Uses custom_model_data.floats[0] = <custom_model_data> and generates assets/minecraft/items/<material>.json with minecraft:range_dispatch. Oraxen also sets integer CustomModelData on the item for compatibility.

🧱 generate_predicates

Generates legacy predicate overrides in assets/minecraft/models/item/*.json. Not required on 1.21.4+, but useful when external tools still read legacy predicate models.

info

On 1.21.4+, you can enable both model_data_ids and model_data_float to generate both dispatch modes in vanilla item definitions for compatibility. Oraxen will still set both string and float data on items.

Pack Properties​

🖼️ model

Path to an existing model JSON (relative to pack/models/, without .json).

my_item:
  pack:
    model: weapons/swords/ice_sword
🧾 gui_model

Model used in inventory/GUI contexts. When set, model is used for held/equipped contexts.

my_item:
  pack:
    model: weapons/swords/ice_sword_3d
    gui_model: weapons/swords/ice_sword_icon

Minecraft version
1.21.4+

⚙️ generate_model

Automatically generates a model JSON from textures. Effectively defaults to false, so enable it explicitly when generating from textures.

my_item:
  pack:
    generate_model: true
    parent_model: item/generated
    textures:
      - weapons/swords/ice_sword
🎨 textures

Texture layers for generated models (relative to pack/textures/, without .png). Accepts either an array (layer0, layer1, ...) or a named map.

my_item:
  pack:
    textures:
      - weapons/swords/ice_sword
my_item:
  pack:
    textures:
      layer0: weapons/swords/ice_sword
      particle: weapons/swords/ice_sword
📦 parent_model

Parent model used when generate_model is enabled.

my_item:
  pack:
    parent_model: item/handheld

Default
item/generated

🧭 generated_model_path

Custom output path for generated model files. Supports namespaced paths like oraxen:weapons. The models/ prefix is inserted automatically, so do not include it.

my_item:
  pack:
    generated_model_path: oraxen:weapons
🔢 custom_model_data

Sets a specific CustomModelData value (auto-generated if not set). Used by legacy predicates and model_data_float dispatching.

my_item:
  pack:
    custom_model_data: 120001
🧩 models

Additional model definitions registered as oraxen:<item_id>/<key>. Useful for mechanics that swap models.

my_item:
  pack:
    models:
      active: weapons/swords/ice_sword_active
      cracked: weapons/swords/ice_sword_cracked
🛡️ blocking_model / blocking_texture

Shield blocking model or texture. If you provide a texture, Oraxen generates a model automatically.

my_shield:
  pack:
    blocking_texture: weapons/shields/ice_shield_blocking
🏹 pulling_models / pulling_textures

Bow pulling stage models or textures. Provide multiple entries (from early to late pull stages).

my_bow:
  pack:
    pulling_models:
      - weapons/bows/ice_bow_pull_0
      - weapons/bows/ice_bow_pull_1
      - weapons/bows/ice_bow_pull_2
⚡ charged_model / charged_texture

Crossbow charged model or texture.

my_crossbow:
  pack:
    charged_model: weapons/crossbows/ice_crossbow_charged
🎆 firework_model / firework_texture

Crossbow-with-firework model or texture.

my_crossbow:
  pack:
    firework_texture: weapons/crossbows/ice_crossbow_firework
🎣 cast_model / cast_texture

Fishing rod cast model or texture.

my_rod:
  pack:
    cast_model: tools/rods/ice_rod_cast
🩹 damaged_models / damaged_textures

Durability-based model or texture stages, from least to most damaged.

my_item:
  pack:
    damaged_textures:
      - tools/picks/ice_pick_1
      - tools/picks/ice_pick_2
      - tools/picks/ice_pick_3
🚫 exclude_from_predicates

Exclude this item from CustomModelData predicate generation. Works on all versions. On 1.21.4+ it also excludes the item from custom_model_data component data and vanilla item definitions.

my_item:
  pack:
    exclude_from_predicates: true
🚫 exclude_from_item_model

Exclude this item from the minecraft:item_model component.

my_item:
  pack:
    exclude_from_item_model: true

Minecraft version
1.21.4+

📏 oversized_in_gui

Allows oversized rendering in GUI contexts for item definitions.

my_item:
  pack:
    oversized_in_gui: true

Minecraft version
1.21.4+

🤚 hand_animation_on_swap

Controls whether the hand animation plays when swapping to this item.

my_item:
  pack:
    hand_animation_on_swap: false

Default
true

Minecraft version
1.21.4+

📐 swap_animation_scale

Scales the item swap animation.

my_item:
  pack:
    swap_animation_scale: 0.75

Default
1.0

Minecraft version
1.21.4+

Example​

ice_sword:
  material: IRON_SWORD
  itemname: "<gradient:#80d9ff:#1c7fd1>Ice Sword"
  pack:
    model: weapons/swords/ice_sword
    gui_model: weapons/swords/ice_sword_icon
    generate_model: false
    custom_model_data: 120001
    models:
      active: weapons/swords/ice_sword_active
    damaged_textures:
      - weapons/swords/ice_sword_cracked_1
      - weapons/swords/ice_sword_cracked_2

Notes​

  • Pack model paths are relative to plugins/Oraxen/pack/models and omit the .json extension.
  • Pack texture paths are relative to plugins/Oraxen/pack/textures and omit the .png extension.
  • custom_model_data is optional; Oraxen will auto-generate it unless automatic model data is disabled.
  • This page focuses on appearance; properties and components are documented separately.