Decorative Items

Decorative Items

Decorative items are small pack-scoped assets used mainly for GUI visuals.

They are not skin definitions. They are custom item models that SkinEngine can reference by token.

File locations

Definitions live in:

/plugins/SkinEngine/packs/<pack_id>/configs/decorative_items.yml

Assets live in:

/plugins/SkinEngine/packs/<pack_id>/resourcepack/decorative_items/

What decorative items are for

Use decorative items when you want:

  • custom button icons in guis.yml
  • decorative GUI fillers
  • lightweight helper models such as back, next, info, cancel
  • a pack icon model in pack.yml

They are the right tool when you need an item-model value, not when you need text-like image inserts in titles or messages.

Example

info:
  material: PAPER
  type: generate
  resource: "info.png"

next:
  material: PAPER
  type: generate
  resource: "next.png"

How SkinEngine identifies them

The id inside decorative_items.yml is local to the pack.

SkinEngine turns it into a global key using:

<pack_id>_<item_id>

So this:

info:
  material: PAPER
  type: generate
  resource: "info.png"

inside pack folder frostfall/ becomes:

frostfall_info

Supported fields

Entry id

The id must use only letters, numbers, and _.

material

The Bukkit material used for the decorative item.

This is the real item base that receives the model. Use a material that makes sense for the place where the decorative item will be shown.

type

Supported values:

  • generate
  • model

Use generate when the resource is a PNG.

Use model when the resource is a JSON model file.

That means:

  • generate is the usual choice for quick GUI visuals
  • model is the choice when you already have a custom JSON model and want to wire it in directly

resource

Relative path inside resourcepack/decorative_items/.

Rules:

  • must stay inside the decorative item folder
  • generate expects a .png
  • model expects a .json
  • the file must exist

Examples:

back:
  material: PAPER
  type: generate
  resource: "buttons/back.png"

frame:
  material: PAPER
  type: model
  resource: "gui/frame.json"

Tokens

Decorative items are usually used through:

{$decorative:pack_id_item_id}

Example:

item-model: "{$decorative:frostfall_info}"

This is especially useful in:

Actual places where decorative tokens are accepted:

  • pack.yml icon item-model
  • guis.yml item item-model

They are not a general-purpose text token like {$image:...}.

What the plugin validates

When SkinEngine loads decorative_items.yml, it validates:

  • the item id only uses letters, numbers, and _
  • material is a real Bukkit material
  • type is either generate or model
  • resource stays inside resourcepack/decorative_items/
  • the referenced file exists

If two decorative items end up with the same global key, the later one is skipped.

Good patterns

Keep decorative items boring and predictable:

  • use short ids such as info, next, back, empty
  • group files into subfolders only when the pack is large
  • reserve decorative items for GUI-facing models and pack icons
  • use Images and Font Assets for title strips, inline logos, and text overlays