SoapsUniverse
SoapsCommon
SoapsCommon

Getting Started

HomeIntroductionGetting Started

Pages

GUI architecture across the Soaps suite (ECO-003)

Configuration

ConfigurationDefault Config Files

Guides

GUI SystemGUI AnimationsIntegrations

Support

FAQ

Getting Started

Last updated Jul 6, 2026

Getting Started

Install

  1. Download SoapsCommon.jar from SoapsUniverse.com or the plugin page for the suite plugin you are installing.
  2. Place the JAR in your server's plugins/ folder.
  3. Restart the server (a full restart is safer than /reload for library plugins).

If your other Soaps plugins use shaded builds, you may not need a separate SoapsCommon JAR. Check the download page for each plugin.

Verify it loaded

On startup you should see the SoapsCommon banner in the console. Suite plugins that depend on it will print their own startup line after SoapsCommon is ready.

If a dependent plugin disables itself, look for a boxed error in the console. The usual cause is a missing or outdated SoapsCommon JAR.

First-run files

SoapsCommon does not create a plugins/SoapsCommon/config.yml. It only ships plugin.yml inside the JAR.

GUI settings for suite plugins live in each plugin's own folder, for example:

plugins/SoapsAdmin/gui/_settings.yml
plugins/SoapsQuest/gui.yml

See GUI System for how those files connect to SoapsCommon.

Troubleshooting

"Missing library" or plugin won't enable

  • Confirm SoapsCommon.jar is in plugins/.
  • Match versions: if SoapsAdmin 1.4.2 asks for SoapsCommon 1.4.x, do not run an older 1.2.x build.
  • Restart the server after adding the JAR.
  • Check gui.enabled: true in the consumer plugin's config.yml (not SoapsCommon).
  • Confirm the consumer plugin's GUI YAML has no syntax errors.
  • Enable settings.debug: true in the consumer plugin to get finer log output.

Placeholders show as raw text in menus

  • Install PlaceholderAPI if the menu text uses %placeholder% syntax.
  • {placeholder} braces in GUI YAML are filled by the plugin that owns the menu, not PlaceholderAPI.

Next steps

  • Configuration for shared config keys
  • GUI System if you customize menus for SoapsAdmin or other plugins with a gui/ folder
Discord