GUI System
Last updated Jul 6, 2026
GUI System
SoapsCommon powers the inventory menus used across the Soaps suite. Most server owners interact with this through YAML files in each plugin's data folder, not through SoapsCommon itself.
Folder layout
Plugins that use the full GUI folder model (SoapsAdmin is the main example) store files like this:
plugins/SoapsAdmin/gui/
_settings.yml Global filler, border, click sounds
system-gui.yml Optional cosmetic overrides
player-hub.yml One file per menu
shop-hub.yml
...
Other plugins may use a single gui.yml in their plugin folder instead. The schema is the same.
Global settings (_settings.yml)
| Key | Default | Description |
|---|---|---|
filler-material |
GRAY_STAINED_GLASS_PANE |
Empty slot background |
filler-name |
" " |
Display name on filler items |
border-material |
BLACK_STAINED_GLASS_PANE |
Border row material |
click-sound |
UI_BUTTON_CLICK |
Sound on item click |
click-sound-volume |
0.5 |
Click sound volume |
click-sound-pitch |
1.0 |
Click sound pitch |
Set click-sound to NONE to disable click sounds.
Menu options
Each menu YAML file supports:
| Key | Default | Description |
|---|---|---|
title |
menu id | Inventory title (MiniMessage supported) |
size |
3 |
Rows (1-6, each row is 9 slots) |
filler |
none | Override filler material for this menu only |
border |
none | Border material for this menu |
open-permission |
none | Permission required to open |
open-command |
none | Command string (registered by the owning plugin) |
open-sound |
none | Sound when menu opens |
open-sound-volume |
0.5 |
Open sound volume |
open-sound-pitch |
1.0 |
Open sound pitch |
close-action |
none | Action run when menu closes |
conditional-fillers |
{} |
Map of permission node to filler material |
refresh |
0 |
Auto-refresh interval in seconds (0 = off) |
Item options
Each item under items: in a menu file:
| Key | Default | Description |
|---|---|---|
slot |
0 |
Slot number or range like 10-16 |
material |
STONE |
Bukkit material name |
name |
"" |
Display name |
lore |
[] |
Lore lines |
material-active |
none | Material when item is in active state |
name-active |
none | Name when active |
lore-active |
none | Lore when active |
name-alt |
none | Alternate name |
permission |
none | Hide item if player lacks permission |
action |
none | Click action (see below) |
requires-online |
false |
Target player must be online |
right-action |
none | Right-click action |
middle-action |
none | Middle-click action |
shift-left-action |
none | Shift + left click |
shift-right-action |
none | Shift + right click |
drop-action |
none | Drop key / swap offhand |
number-action |
none | Hotbar number key |
skull-owner |
none | Player name for player heads |
custom-model-data |
0 |
Resource pack model data |
amount |
1 |
Stack size |
glow |
false |
Enchantment glint |
flags |
none | Item flag list |
view-condition |
none | Parsed for custom screens (plugin-specific) |
Click actions
Actions use bracket syntax in the action field:
action: "[open_menu] player-hub"
action: "[command] spawn"
action: "[console] say Hello {player}"
action: "[message] <green>Clicked!"
Built-in actions
| Action | Syntax | What it does |
|---|---|---|
| close | [close] |
Close the inventory |
| refresh | [refresh] |
Rebuild the current menu |
| open_menu | [open_menu] <menuId> |
Open another registered menu |
| command | [command] <cmd> |
Run as the player (no slash) |
| console | [console] <cmd> |
Run as console |
| message | [message] <text> |
Send a message to the player |
| broadcast | [broadcast] <text> |
Broadcast to the server |
| actionbar | [actionbar] <text> |
Show action bar text |
| sound | [sound] <SOUND> [vol] [pitch] |
Play a sound |
| none | [none] |
Do nothing |
| animation_trigger | [animation_trigger] <id> |
Start an animation (animated menus) |
| animation_stop | [animation_stop] <id> |
Stop an animation |
Chain multiple actions with ;;:
action: "[message] <yellow>Opening shop... ;; [open_menu] shop-hub"
Placeholders in actions
| Placeholder | Replaced with |
|---|---|
{player} |
Clicking player's name |
{target} |
Target player name (if set) |
{target_uuid} |
Target UUID |
{key} |
Any value the owning plugin adds to the menu context |
Suite plugins may register extra actions (for example shop buy/sell). Those are documented in each plugin's wiki.
Placeholders in item text
Use {key} in item names, lore, and titles for values the owning plugin supplies (balance, stats, room name, and so on).
Use %placeholder% syntax only if PlaceholderAPI is installed and the owning plugin parses PAPI in that text field.
Disabling GUIs
Set gui.enabled: false in the consumer plugin's config.yml. See Configuration.
For animated menus, see GUI Animations.