Skip to content

Custom Items

natan307 edited this page Nov 16, 2026 · 1 revision

Custom Items

Items are defined in plugins/PackLoader/items/*.yml (every .yml / .yaml file in the folder is loaded). Apply changes with /packloader reload.

Requires Minecraft 1.21.4+ for generated models (item definition files in assets/<ns>/items/). See Compatibility.

Example

items:
  ruby_flat:                       # 2D item from a texture
    display_name: "&cRuby"
    material: PAPER
    lore:
      - "&7A shiny ruby"
    texture: "packloader:item/ruby"

  ruby_crystal:                    # 3D item from a model
    display_name: "&cRuby Crystal"
    material: PAPER
    model: "packloader:item/ruby_crystal"
    glint: true

Give it with /packloader give <player> ruby_crystal [amount].

Keys

Key Description
(section name) Item id. Only a-z 0-9 _.
display_name Name. Supports & codes and &#RRGGBB. Italic is removed.
material Base vanilla material. Default PAPER.
lore List of lines (same colour support).
texture namespace:path of a PNG, without .png. Generates a flat model.
parent With texture: generated (default) or handheld, or any model id.
model namespace:path of a model JSON (for example exported from Blockbench).
item_model Use an item definition that already exists in your pack. PackLoader does not generate one.
custom_model_data Optional integer, also set on the item.
glint true/false - enchantment glow.
unbreakable true/false.
hide_flags true/false - hide tooltips for attributes, enchants etc.
block Makes the item placeable, see Custom Blocks.

If a value has no namespace (item/ruby), the resource-pack.namespace from the config is used.

Where files go

For texture: "packloader:item/ruby" put this in a pack:

assets/packloader/textures/item/ruby.png

For model: "packloader:item/ruby_crystal":

assets/packloader/models/item/ruby_crystal.json
assets/packloader/textures/item/ruby.png        <- whatever the model references

What PackLoader generates

For an item ruby_crystal with namespace packloader:

  • assets/packloader/items/ruby_crystal.json - item definition pointing to your model
  • (texture items only) assets/packloader/models/packloader_generated/<id>.json

The item gets the minecraft:item_model component packloader:ruby_crystal, so it does not depend on custom_model_data and does not clash with other packs.

3D models (Blockbench)

  1. Create the model in Blockbench using the Java Block/Item format.
  2. Export the model JSON and the textures.
  3. Put them in a pack: models in assets/<ns>/models/..., textures in assets/<ns>/textures/.... Texture references inside the model must match ("0": "packloader:item/ruby").
  4. Reference the model with model: as shown above.

Adjust the display section of the model to control how it looks in the GUI, hand and on the ground.

Checking your setup

After a build PackLoader checks that the referenced texture / model / item definition exists in the merged pack and prints a warning such as:

Item 'ruby_crystal': model not found in any pack: assets/packloader/models/item/ruby_crystal.json

A purple-black item in game almost always means a wrong path, or a texture referenced by the model that is missing.

Notes

  • Every item carries a hidden packloader:item_id tag so PackLoader can recognise it (used by blocks).
  • Invalid ids, unknown materials and duplicate ids are reported in the console. A duplicate id overrides the earlier one.

Clone this wiki locally