Custom GUI background in DeluxeMenus with ItemsAdder

How a texture GUI works

A chest menu shows its title in the top left corner. The title is text, and text can contain characters from the server resource pack. ItemsAdder can turn any PNG into such a character, called a font image. Put a big font image into the title and the client draws it over the chest screen.

Two more pieces make it line up. A negative offset moves the cursor to the left before the image, so the picture starts at the left edge of the chest instead of after the title indent. The y_position of the font image moves it up or down until it covers the whole menu.

The slots stay normal slots. Where your picture shows a button, the menu has an empty, clickable slot with material: air and its own click actions.

What you need

• DeluxeMenus and PlaceholderAPI on a Spigot or Paper server.
• ItemsAdder, which builds the resource pack and provides the %img_…% placeholders.
• A working resource pack delivery, so players actually download the pack (ItemsAdder offers self-hosting and other hosting options).
• A background PNG. Minecraft does not allow font glyphs bigger than 256×256 pixels, so the picture has to fit into that.

Step 1: Make the background picture

Design the menu in the GUI Maker: pick rows, a theme or preset, and draw big buttons over several slots. Choose ItemsAdder as export, enter your namespace (for example mymenus) and the menu name (for example shop).

The exported PNG is 256 pixels wide. Its height depends on the rows, from 164 pixels for one row to 254 pixels for six. The extra space around the chest lets frames and decorations stick out of the normal menu outline.

Step 2: Register the font image in ItemsAdder

Copy the PNG into your namespace and add a font_images entry. This is what the GUI Maker exports for a six-row menu:

info:
  namespace: mymenus
font_images:
  gui_shop:
    path: gui/shop
    show_in_gui: false
    suggest_in_command: false
    scale_ratio: 254
    y_position: 45

The picture itself goes to plugins/ItemsAdder/contents/mymenus/resourcepack/assets/mymenus/textures/gui/shop.png.

• scale_ratio is the height the image is drawn at. Use the real pixel height of the PNG so nothing gets stretched.
• y_position moves the image vertically. ItemsAdder requires it to be lower than or equal to scale_ratio, because the game does not allow more.
• show_in_gui: false keeps the background out of the ItemsAdder emoji list.

Step 3: Put the image into the DeluxeMenus menu title

DeluxeMenus parses PlaceholderAPI placeholders in menu_title. ItemsAdder provides %img_<name>% for the image and %img_offset_<pixels>% for empty space, which can be negative.

menu_title: '&f%img_offset_-48%%img_gui_shop%%img_offset_-201%&8Shop'
open_command: 'shop'
register_command: true
size: 54
items:
  button_1_buy:
    material: air
    slots: [10, 11, 19, 20]
    priority: 1
    click_commands:
      - '[openguimenu] shop_buy'

1. &f at the start keeps the picture in its real colours. Without it the image is tinted with the title colour.
2. %img_offset_-48% moves the cursor 48 pixels to the left before the picture. The GUI Maker uses this value for its canvas: 8 pixels for the indent of the chest title plus the 40 pixel margin it adds on each side.
3. %img_gui_shop% is the background itself.
4. The second offset moves the cursor back, so &8Shop is written on top of the picture where a title belongs. Its value depends on the width of your picture; the GUI Maker calculates it for you.

If you bake the title into the picture in the GUI Maker, the title ends after the background placeholder and there is no second offset.

Step 4: Register the menu and rebuild the pack

DeluxeMenus loads only menus listed in its config.yml:

gui_menus:
  shop:
    file: shop.yml

1. Run /iazip so ItemsAdder rebuilds the resource pack with the new image.
2. Run /dm reload. Open the menu once with /dm open shop to check it.
3. register_command: true registers /shop as a real command, but only when the server starts. Restart the server once after adding a new menu.
4. Rejoin, accept the resource pack and open the menu.

Common errors and fixes