GUI architecture across the Soaps suite (ECO-003)

SoapsCommon ships the shared GUI engine (com.soaps.common.api.gui.GuiManager, GuiBus, YAML menus). Plugins integrate in one of three patterns:

Pattern A — SoapsCommon facade (preferred)

Plugin-local GuiManager wraps com.soaps.common.api.gui.GuiManager and registers YAML screens.

Plugin	Local class	Notes
SoapsAdmin	CommonGuiBridge	Full YAML + Java router
SoapsFloor	com.soapsfloor.gui.GuiManager	commonGui() delegate
SoapsTeleporter	com.soaps.teleporters.gui.GuiManager	Portal YAML screens
SoapsQuest	com.soaps.quest.gui.GuiManager	Uses Common GuiManager directly

Lifecycle: call commonGui.shutdown() (or bridge shutdown()) from onDisable. GuiBus auto-detaches on PluginDisableEvent if omitted.

Pattern B — Legacy custom inventory (intentional)

Plugin	Class	Reason
SoapsTraits	soapstraints.gui.GuiManager + SoapsGuiHolder	Trait editor UX predates Common YAML
SoapsHungerStamina	soapshungerstamina.gui.GuiManager	Config editor with custom slot logic
SoapsArena	com.soapsarena.gui.GuiManager	Arena-specific session state

Migration to Pattern A is deferred until editors stabilize (see consolidation backlog).

Pattern C — Mini plugins

Most mini plugins use lightweight custom GUIs or no GUI. They still benefit from SoapsText / SoapsCommon.require().

Reload safety

• YAML reload must call GuiManager.closeAllActive() before reloading menu definitions (SoapsAdmin CommonGuiBridge.reload() does this).
• Animated GUIs must use per-animation task handles (GuiAnimationRuntime), not cancelTasks(plugin).