Customization

GUI layout files

Every menu is described by one YAML file inside the McmmoGuiV2/gui/ folder. The file defines the shape of the menu (rows, buttons, materials, slots, sounds), while the language file provides the text. We call these files GUI templates.

Layout file anatomy

Gui:
  Rows: 6                      # Menu height, 1 to 6. Total slots = Rows x 9
  Sound:                       # Played when the menu opens
    Value: ui.button.click
    Pitch: 2
  FeatureButtons:              # Buttons the plugin drives (skills, party, ranking, ...)
    Swords:
      Material: IRON_SWORD
      Slots: [10]
      Flags: ["*"]
  DecorationButtons:           # Static buttons, fillers, links, your own buttons
    Corner:
      Slots: [46, 52]
      Material: BLACK_STAINED_GLASS_PANE
      HideTooltip: true

Feature buttons are the ones the plugin looks up by name and fills with live data (a skill, a leaderboard entry, the party panel). Decoration buttons are not wired to any plugin logic, which makes them the safe place for your own additions.

Slots are 0-indexed, starting from the top-left corner. A slot number greater than or equal to Rows x 9 is silently ignored, so raise Rows before using a slot in a new row.

Button properties

An unknown material falls back to BARRIER, which is the quickest way to spot a typo in-game. For head-<username>, a name the server has never seen falls back to the skin defined by Settings.OfflinePlayerSkinValue in settings.yml.

Layout-specific keys

A few keys are only read by one layout.

Adding a new button

The example below adds a shop button to the skill overview menu.

  DecorationButtons:
    # ... the shipped buttons stay untouched
    Shop:
      Slots: [45]
      Material: EMERALD
      Glow: true
      Flags: ["*"]
      Name: "<green>Server Shop"
      Lore:
        - "<gray>Sell what you farmed with"
        - "<gray>your mcMMO skills."
        - ""
        - "<dark_gray>Click to open the shop"
      Sound:
        Value: ui.button.click
        Pitch: 2.0
      Commands:
        - "[close]"
        - "[player] shop"

Name and lore

A button's text can come from two places.

    Shop:
      Slots: [45]
      Material: EMERALD
      Name: "<green>Server Shop"
      Lore:
        - "<gray>Sell what you farmed with"
        - "<gray>your mcMMO skills."

Which one wins

For each button the plugin resolves the text in this order.

1. Name and Lore from the GUI template are read first.
2. If the player's language file has a section for that button, its Name and Lore replace them.
3. The GUI then fills in the per-button tokens (%name%, %level%, %stats%, %description%, %abilities%, ...).
4. Finally the plugin's own placeholders, then PlaceholderAPI, then MiniMessage are applied.

A button with no language entry, which is the case for every button you add yourself, keeps the text from the template. That is why a custom button needs nothing more than the Name and Lore lines shown above.

Styling name and lore

All text goes through MiniMessage, so colors, gradients, hover and click events work everywhere. Item text is rendered without the vanilla italics.

The tags a server allows are controlled by Settings.AllowMiniMessageTags in settings.yml. The default is ALL. If you replace it with an explicit list, keep at least CLICK and DECORATION, the shipped layouts need them.

Built-in placeholders

These are resolved by McmmoGui itself, before PlaceholderAPI runs, and work in names, lore, materials, titles and click actions.

Any other placeholder is handed to PlaceholderAPI, so every expansion installed on your server works here too. See Placeholders for the ones McmmoGui provides.

Click actions

The Commands list holds what happens when the button is clicked. Each entry may start with a tag.

Good to know:

• A leading / in a command is stripped for you, both syntaxes work.
• Entries run in the order they are listed, after the button's own Sound.
• Placeholders are resolved at click time, so %player% is the player who clicked.
• An unknown tag is skipped and a warning naming the button is printed in the console.
• Clickable: false blocks every action on the button, useful for pure display items.

The shipped Docs button is a complete example of the three most used tags.

    Docs:
      Slots: [51]
      Material: BOOK
      Commands:
        - '[close]'
        - '[sound] ui.button.click 1 2'
        - "[message] <green>→ <white>Visit our docs: <u><green><click:open_url:'https://mcmmo.hyronic.dev/'>https://mcmmo.hyronic.dev/</click>"

Hiding a button

Applying your changes

Run /mgui reload to reload every GUI template, language file and setting without restarting. The only change that still needs a full server restart is renaming a command or its aliases in settings.yml.