GUI Configuration

This page explains the runtime GUI layout file: guis.yml.

Important distinction:

  • guis.yml controls layout symbols, materials, item-models, and open-actions
  • translations/<language>/guis.yml controls GUI titles and built-in item text

What guis.yml controls

Use guis.yml for:

  • layout grids
  • row counts
  • custom GUI items
  • required GUI item symbols
  • custom materials
  • decorative item-model references
  • open sounds

Built-in views

SkinEngine currently has four built-in views:

  • start
  • packs
  • skins
  • confirm

items.custom-items

Custom items are optional helper items you place into layouts yourself.

Supported fields:

  • symbol
  • material
  • item-model
  • hide-tooltip
  • item-flags

items.required-items

Required items are the built-in controls SkinEngine expects.

Current required types are:

  • close
  • next
  • back
  • preview
  • confirm
  • confirm_clear
  • insert
  • clear
  • skin_slot
  • filter

Each required item needs a layout symbol. Text for built-in required items is not taken from guis.yml; it comes from translations/<language>/guis.yml.

Decorative item models

item-model can use:

  • a normal namespaced key such as skinengine:some/path
  • a decorative token such as {$decorative:skinengine_info}

Decorative tokens are resolved from pack decorative_items.yml files.

Layout rules

Each layout row must contain exactly 9 characters.

rows must match the real number of rows in layout.

Required symbols by view:

  • start: insert, clear, close
  • packs: skin_slot, back, next, close
  • skins: skin_slot, preview, filter, back, next, close
  • confirm: preview, confirm, close

confirm_clear does not need a dedicated slot in the layout. SkinEngine swaps it into the normal confirm position during clear mode.

Skin filter

The filter control is used in the skins view. Each click cycles through:

  • all skins
  • unlocked skins
  • locked skins

A skin is unlocked when the player has its permission, or when that skin does not require one. The selected filter only changes what is shown in the current skin list.

The filter item's model and position are configured in the root guis.yml. Its name, option labels, lore, and selected or unselected entry style are configured in translations/<language>/guis.yml.

open-actions

open-actions currently supports sound directives:

open-actions:
  - "{$sound:ui.button.click:1:1}"

Text and titles

Built-in GUI text is now translated through:

/plugins/SkinEngine/translations/<language>/guis.yml

That file contains:

  • titles
  • skin state names and lore
  • pack entry lore
  • built-in button names and lore

So if you want to change titles or built-in button text, edit translations/<language>/guis.yml, not guis.yml.