Layouts, frames and slots

A layout is a named block of the menu. You create it in the layoutPool of an Open GUI entry and give it an id. Other layouts reach it through that id.

Choose a layout

Layout	Use it for	Fields
simple	Static menus, borders and fixed buttons.	items
flex	Items placed automatically in rows.	items, justifyContent, alignItems, wrap, virtualHeight
paginated	A list split into pages.	itemsPerPage, slots, items, navigationButtons
scrollable	Content larger than the window.	innerId, virtualWidth, virtualHeight, buttons
frame	Independent rectangles.	frames
composite	Layers drawn on top of each other.	children
book	A written book.	pages
merchant	Villager trades.	trades
storage	Persistent item slots.	entry, groupKey, slots
leaderboard	A fact ranking.	leaderboard, x, y, width, height, previousButton, nextButton

simple

Every item has an x (column, 0 to 8) and a y (row, 0 at the top). It is the layout to start with.

dropOnClose hands back what is left in the slots of the layout when the menu closes (also when another menu replaces it): loot the player did not take, or an item they put there. Only items with allowPickup are handed back, once; decoration never is. closeDelivery chooses how: GIVE_OR_DROP (default) puts the items in the inventory and drops the surplus at the player's feet, DROP drops everything. It is off by default, and the editor warns when it is on but no item allows pickup.

flex

flex ignores the x and y of its items and flows them from left to right, row after row, over the width of the menu. justifyContent decides how a row is spread (START, CENTER, END, SPACE_BETWEEN), alignItems where the block sits vertically inside virtualHeight, and wrap whether a full row continues on the next line. Without wrap, items past the last column are dropped and logged.

paginated

Items are cut into pages of itemsPerPage and poured into the physical slots (slot index is y * 9 + x). When slots is empty they fill the inventory from the top left. Add buttons in navigationButtons, one per role:

• NEXT and PREVIOUS appear only when there is a page to go to.
• BACK is always shown and returns to the previous menu.
• INDICATOR is not clickable and appears only with two pages or more. Its name and lore accept {page}, {total_pages}, {next_page}, {prev_page} and {page_indicator}.

Reserve the cells of the buttons: pages fill the slots listed in slots and do not avoid your buttons.

scrollable

A scrollable layout shows a window on the layout named in innerId. virtualWidth and virtualHeight give the size of the full area. Add buttons with a direction (UP, DOWN, LEFT, RIGHT) and a step, in slots per click. Each button is shown only when there is something to scroll to in its direction.

With showDefaultButtons on (the default), an arrow is added for every direction that has no buttons entry. defaultStep (at least 1) is the number of slots these arrows scroll per click; your own buttons keep their step. Off means no default arrow.

Default arrows follow the same rule as your own: they show only while the content can scroll in their direction. Unless you configure them, they are a plain arrow item named ▲, ▼, ◀ or ▶, in the right column (column 8) for up and down and on the bottom row for left and right. They never cover anything: if the cell already holds a content item, a button or a decoration, the arrow is simply not shown, with no message in the console. Change an arrow's item, name or place in the scrollArrows list of GUI Settings.

Menus written before default arrows

showDefaultButtons is on by default, so an existing scrollable layout gains arrows. Set it to false, or place the arrows elsewhere, to keep the menu exactly as it was.

The mouse wheel also scrolls the focused scrollable layout vertically while a menu is open. Give every scrollable and paginated layout a unique id, since the position is tracked per id.

frame

A frame layout lists rectangles: id, x, y, width, height and the layoutId of the layout that fills it. The content of the frame is positioned relative to its top left corner. A frame without a resolvable layoutId is skipped. Use @view as layoutId to let the active view fill it.

A typical dashboard: a fixed tab column, a scrollable content frame and a footer frame.

composite

composite draws its children (layout ids) in order, later children on top. Put the background first, the content in the middle and the buttons last. A child that does not exist is skipped, and a loop between layouts yields an empty layout.

Connect layouts

A layout is used when it is referenced: by mainLayoutId, a composite child, a scrollable innerId or a frame layoutId. A layout nobody references is simply not drawn.

Items and slots

See the Menus section of the GUI page for the fields of an item.