SoapsUniverse
SoapsCommon
SoapsCommon

Getting Started

HomeIntroductionGetting Started

Configuration

ConfigurationDefault Config Files

Features

GUI ArchitectureGUI SystemGUI AnimationsIntegrations

Other

FAQChangelog

GUI Architecture

Last updated Sep 20, 2026

GUI Architecture

This page explains how SoapsCommon menus fit together. Use it when you want the big picture. For YAML keys, see GUI System. For animated effects, see GUI Animations.

Who owns what

Piece Where it lives Who edits it
Shared GUI engine SoapsCommon JAR Nobody on the server (library code)
Menu YAML files Each plugin's data folder You
Global filler, border, click sound gui/_settings.yml in that plugin You
Built-in staff panels Java in the suite plugin Cosmetic overrides only (when supported)
Click actions action: fields in menu YAML You (plus extra actions the plugin registers)

SoapsCommon does not store menus under plugins/SoapsCommon/. Edit the plugin that opens the menu (for example plugins/SoapsAdmin/gui/).

How a menu opens

  1. A player runs a command, clicks an item, or another menu uses [open_menu].
  2. The suite plugin asks its SoapsCommon GuiManager for that menu id.
  3. SoapsCommon builds the inventory from YAML (title, size, items, sounds).
  4. Clicks are routed through one shared listener in SoapsCommon.
  5. The action: string on the clicked item runs (close, open another menu, command, and so on).

You never register a separate GUI listener for SoapsCommon menus. The library handles click, drag, and close events for every suite plugin that uses it.

Suite plugins load menus in a few ways. The names below match how SoapsCommon classifies them:

Type What you can change Typical use
Custom Full layout, items, and actions in a YAML file under gui/ Player hubs, shops, daily rewards, custom screens
Skin override Cosmetics only (materials, names, lore) via system-gui.yml Soften the look of a built-in panel without rewriting its logic
Merged Effective result after defaults + skin override Java-backed admin/staff panels that still honor YAML cosmetics

If a menu is fully custom, almost everything is in that one YAML file. If it is a built-in panel, changing slots or actions in YAML may be ignored; prefer the plugin's own wiki for those screens.

Settings cascade

Values resolve from general to specific:

  1. SoapsCommon built-in defaults (see Default Config Files)
  2. Plugin gui/_settings.yml (filler, border, click sound)
  3. The individual menu YAML (title, size, per-menu filler/border, items)
  4. Runtime context from the owning plugin ({player}, balances, target names, and so on)

A per-menu filler or border overrides _settings.yml for that menu only.

Folder models

Multi-file gui/ folder (SoapsAdmin is the main example):

plugins/SoapsAdmin/gui/
  _settings.yml
  system-gui.yml      Optional cosmetic overrides for built-in panels
  player-hub.yml
  shop-hub.yml
  ...

Single file (some smaller plugins):

plugins/SomePlugin/gui.yml

The YAML schema is the same either way. SoapsCommon loads it; the plugin decides which model to use.

Master switch

Each consumer plugin can turn menus off without removing SoapsCommon:

gui:
  enabled: false

That key lives in the consumer config.yml. See Configuration.

Animations

Menus with an animations: block use SoapsCommon's animation runtime. Effects run on the same screen as the static items. Details and keys: GUI Animations.

Practical checklist

When a menu misbehaves:

  1. Confirm SoapsCommon and the suite plugin are matching 1.4.x builds
  2. Confirm gui.enabled: true in the consumer plugin
  3. Check YAML syntax in the menu file and _settings.yml
  4. Decide whether the screen is custom (edit YAML) or built-in (check that plugin's wiki)
  5. Turn on settings.debug: true in the consumer plugin while testing