Interactions and navigation

An interaction connects a GUI component to a behavior. It can execute a TypeWriter action, command, trigger, input dialog, or menu session change.

Add an interaction

In a GuiItem, add an interaction to interactionList or interactions, then choose:

Field	Role
type	Click or input type.
commands	Commands executed by the interaction.
triggers	TypeWriter triggers to execute.
closeMenu	Adds gui:close after the action.
executeReturn	Adds gui:back to return to the previous menu.

Common interaction types

LEFT, RIGHT, SHIFT_LEFT, SHIFT_RIGHT, MIDDLE, DOUBLE_CLICK, NUMBER_KEY_1..9, DROP, DROP_ALL, and SWAP_OFFHAND are the values verified in code. Exact behavior depends on the container and item pickup rules.

Execution chain

Close or go back

• To close after an interaction, enable closeMenu.
• To return to the previous menu, enable executeReturn.
• These options add gui:close and gui:back; you do not need to write these strings in a separate command.

User input

The input field of a GuiItem can display a dialog. Configure enabled, title, placeholder, targetVar, onInputCommands, and onInputTriggers. The entered text is passed to targetVar before the configured execution.

Security

Validate on the server any value that influences a command, amount, identifier, or permission. Input displayed in a menu is not business validation.

Permissions

• viewPermission decides whether the slot is visible.
• clickPermission decides whether the player can activate it.
• criteria complements these permissions with a context condition.

For a locked button, use clickPermission if you want to show the item and its lore. For a completely hidden button, use viewPermission.

Both fields are opt-in, and an empty value gates nothing. Leave them blank when the slot is for everyone: since v0.14 a blank permission is treated as absent. Before that release it was passed to Bukkit, which resolves an unregistered node as operator-only — the slot then disappeared for every ordinary player while staff kept seeing it. The same rule applies to a view's viewPermission, which hides a whole tab.

Extension-provided buttons

An extension can register button types. Shops registers ShopButtonType and uses the shop_button: prefix. GUI displays the component; the extension handler executes the business action.

Cooldowns and updates

An item can have cooldownTicks and triggers. For changing data, use autoRefreshTicks on the open_gui entry when supported by the extension version. Avoid very short refresh intervals for a static menu.

Common error

If a click displays the item but does nothing, check in this order: clickPermission, criteria, type, the presence of commands/triggers, then the extension handler that provides the buttonType.