Custom chest menus

How custom chest GUIs are imported, captured, tuned and described by hand so Bedrock players see their background art, and the limits.

On this page

Custom menus give Java players a styled chest screen with their own background art. NusaPack draws that art on the Bedrock chest screen too. This page shows how to import menus, capture one that is built in code, adjust its position and describe it by hand.

How custom menus work

A custom menu is a normal chest whose title contains a large background image: a font glyph, plus negative-space shifts that move it into place. NusaPack finds that background glyph, measures where it sits and draws it behind the Bedrock chest screen.

Slots, items and clicks stay on the server. Your menu plugins keep working unchanged, and NusaPack does not run any menu actions.

What Bedrock players see

  • The Java art becomes the whole background, without the grey Bedrock dialog frame or title.
  • Chest, inventory and hotbar slots sit exactly where Java puts them.
  • When the art already draws slot frames, Bedrock draws only the items. When it does not (for example, a header-only image), Bedrock draws its own slot frames and a plain panel behind the art, like Java's own chest texture.
  • A close button in the menu corner, because touch players have no Esc key. You can switch it off per menu.
  • 1 to 3 rows use the Bedrock small chest; 4 to 6 rows use the large chest.

Only Bedrock players get the converted title; Java players see the original.

Import menus automatically

/npb gui scan                      read the menu files of every supported menu plugin
/npb gui scan deluxemenus,zmenu    only some plugins (comma list)
/npb convert                       then convert

Auto import reads the menu files of these plugins. Nothing has to be opened in game:

Menu pluginFolder that is read
DeluxeMenusplugins/DeluxeMenus/gui_menus/ (chest menus only)
AuraSkillsplugins/AuraSkills/menus/
zMenuplugins/zMenu/inventories/
CommandPanelsplugins/CommandPanels/panels/
ChestCommandsplugins/ChestCommands/menu/
TrMenuplugins/TrMenu/menus/

Titles are understood when they use ItemsAdder %img_name%, :name: and :offset_N:, Nexo or Oraxen <glyph:name>, <shift:N> and %nexo_shift_N%, and colour codes. The background position comes from the shifts and spaces in front of the glyph, and the row count from the menu file. Menu files are only read, never changed or run.

The result shows what changed, for example Added 3 | Updated 0 | Unchanged 2 | Skipped 0. Menus are stored in plugins/NusaPackBridge/gui-bindings.json, up to 64 menus. With gui_auto_import on (the default), this import also runs before every /npb convert, so new menus are picked up by themselves.

Capture a menu in game

For a menu built in code, or one that still looks wrong after the import, measure it live:

  1. Open the menu in game as a player.
  2. While it is open, run /npb gui capture, or /npb gui capture <id> to choose its ID.
  3. Run /npb convert.

A capture records the title exactly as the server built it, with the real row count. A later auto import never undoes a capture.

Adjust a menu

/npb gui list shows every converted menu with its ID, size, rows and offset. The /npb panel has the same list under Menus. Then adjust one menu:

/npb gui tune <id> offset_y -30      move the background up or down
/npb gui tune <id> offset_x -8       move it left or right
/npb gui tune <id> rows 6            1 to 6
/npb gui tune <id> enabled off       leave this menu as a plain chest
/npb gui tune <id> close_button off  no close button in the corner
/npb gui tune <id> slots auto        auto, art or native
FieldValuesEffect
offset_xpixelsMoves the background left or right, in pixels at Java GUI scale
offset_ypixelsMoves the background up or down
rows1 to 61 to 3 rows use the small chest, 4 to 6 the large chest
slotsauto, art, nativeauto decides from the art; art means the art draws the slot frames; native draws Bedrock slot frames
enabledon, offoff leaves this menu as a plain chest
close_buttonon, offThe close button in the menu corner (on by default)

Edited menus are marked "edited": true in gui-bindings.json, and imports leave them alone. /npb gui list and plugins/NusaPackBridge/gui-layouts.json show what was decided for the slots (chestSlotsFromArt, inventorySlotsFromArt).

Describe a menu by hand

Menus whose background is a large glyph are also recognised without any import, using the usual -8 px shift. For full control, describe a menu yourself in plugins/NusaPackBridge/gui-bindings.json:

{
  "schema": 1,
  "layouts": [
    {
      "id": "skills_menu",
      "match": "glyph",
      "texture": "textures/myplugin/skills_menu",
      "rows": 6,
      "width": 256, "height": 256,
      "offsetX": -8, "offsetY": -35,
      "anchor": "top_left"
    }
  ]
}
  • anchor is top_left (offsets from the Java title position) or center.
  • Instead of title, an entry can give the full javaTitle (with <shift:N> for shifts) and leave title empty. NusaPack then finds the background glyph and measures its position.
  • Menu IDs use lowercase letters, digits and underscores.
  • /npb gui remove <id> removes a hand-made entry. Menus that were detected automatically cannot be removed this way, because they follow the source pack; use /npb gui tune <id> enabled off instead.

When changes show up

Menu changes apply after /npb convert. A change that only touches menus is a pack-only change, so Bedrock players see it after rejoining. If the last line of /npb convert asks for a restart, restart once.

Known limits

  • Only chest menus (1 to 6 rows) are converted. Other containers, such as hoppers, furnaces or anvils, keep their normal Bedrock screen.
  • The pocket (touch) UI layout still shows the vanilla chest.
  • Animated menu backgrounds show only their first frame.
  • Very large background art, and a glyph character used by several fonts, may not convert fully; the conversion reports this, and the menu stays a normal chest.
  • Titles made of several layered background glyphs keep their original title.
  • Visible title text placed after the background glyph is hidden on Bedrock.
  • Large glyphs used for HUD elements, not menus, are not converted as menus.

Next steps

Nusa product documentation · NusaPackPaper 1.21.x · Java 21

Loading the index…