Skip to main content

Understand a GUI menu

The GUI extension does not require every slot to be placed in code. Describe a layout tree, then the engine creates a player session and renders the visible part of the menu.

The complete flow​

  1. An open_gui entry is triggered by a quest, NPC, command, or another extension.
  2. layoutPool contains named layouts.
  3. mainLayoutId selects the root layout.
  4. The engine creates a session for the player.
  5. Clicks, page changes, and scrolling update that session.

Vocabulary​

TermPractical meaning
open_guiAction that opens the menu and carries its main options.
MenuVisible window, title, container, and player session.
LayoutComposition rule that produces positions and components.
ComponentItem, button, frame, or child layout placed in the menu.
layoutPoolList of layouts referenced by identifier.
mainLayoutIdIdentifier of the starting layout.
ViewportArea actually visible to the player.
Virtual areaComplete logical area of a scrollable layout.
GuiItemVisual item with appearance, permissions, and interactions.
SessionPlayer state: active view, history, page, and scroll position.

Create a first menu​

In the web interface:

  1. Create an open_gui entry named my_first_menu.
  2. Choose guiType: CHEST, a suitable size, and a title.
  3. Add a simple layout with the identifier main.
  4. Select main in mainLayoutId.
  5. Add a GuiItem at x: 4, y: 1.
  6. Set its item, displayName, and lore.
  7. Add a LEFT interaction.
  8. Enable closeMenu if the button must close the menu after its action.
In practice

Start with one simple layout. Add composite, frame, scrollable, or paginated after the simple menu works.

Repeat a slot​

count, direction, gap, and repeatY repeat a component. For example, one item can create a row of nine panes with count: 9 and a horizontal direction. These fields do not change the Minecraft item stack size.

If direction is not set, count, gap, and repeatY do not create a useful repetition. Negative or unsupported coordinates are rejected by the parser.

Control visibility and clicks​

  • viewPermission hides the slot when the player lacks the permission.
  • clickPermission leaves the slot visible but prevents activation.
  • criteria can add a functional condition.
  • allowPickup controls whether the player can take the item.

This distinction lets you show a locked button without making it usable.

Open, go back, and close​

  • Another entry can trigger OpenGuiAction.
  • executeReturn adds the internal gui:back action.
  • closeMenu adds the internal gui:close action.
  • A command or extension can also trigger navigation when it registers the corresponding handler.

Next step​