Getting Started

1. Install Dependencies

1. Install Paper 1.21+ (26.1+ recommended) and run on Java 21+ (25+ recommended on latest Paper).
2. Place SoapsCommon in plugins/. SoapsAdmin will not enable without it.
3. Place SoapsAdmin in plugins/.
4. Optional: Vault for third-party economy hooks (built-in economy works without it).
5. Optional: PlaceholderAPI for %soapsadmin_*% placeholders.
6. Optional: MythicMobs (+ MythicCrucible for custom recipe items).
7. Optional: Citizens — NPCs can be treated as custom mobs for drop rules.

2. First Start

Start the server once. SoapsAdmin creates its data folder:

plugins/SoapsAdmin/
  config.yml          # storage, help, integrations
  staff.yml           # staff mode, vanish, snapshots
  teleport.yml        # homes, warps, TPA, death respawn
  server.yml          # backups, worlds, broadcasts, tickets
  player.yml          # AFK, friends, nicknames, QoL
  modules.yml
  economy.yml
  chat.yml
  moderation.yml
  messages.yml
  customcommands.yml
  recipes.yml
  kits.yml
  prices.yml
  gui/
  data/
    server/spawners.yml
    social/mail/{uuid}.yml
    storage/vaults/
    settings/prefs.yml
    ...

Check the console for the SoapsCommon startup banner, module count, storage type, and (if present) Mythic bridge status.

3. Verify the Plugin

Check	Command
Version	/sa version → should report 1.7.0
Module list	/sa modules list
Admin dashboard	/sa admin (soapsadmin.admin)
Player dashboard	/sa dashboard
Help	/sa help
Soft deps	/sa info

4. Initial Configuration

Priority	File	Action
High	config.yml	Set storage.type (mysql for networks)
High	economy.yml	Currencies, mob drops, Mythic tables
Medium	modules.yml	Disable unused modules
Medium	staff.yml	Staff mode hotbar tools
Medium	teleport.yml	Warmups, homes, death respawn
Medium	moderation.yml	Warn escalation and QP templates
Medium	recipes.yml	Custom / Crucible recipes
Medium	rules.yml	Server rules
Medium	customcommands.yml	Typed aliases / overrides (type: required)
Low	gui/system-gui.yml	Reskin panels (copied on first run)

Reload after edits:

/sa reload
/sa reload config
/sa reload staff
/sa reload teleport
/sa reload server
/sa reload player
/sa reload messages
/sa reload gui
/sa reload shop
/sa reload all

5. Permission Setup

Role	Permission nodes
Owner	soapsadmin.*
Admin	soapsadmin.admin, soapsadmin.reload, world/economy/recipe nodes
Moderator	kick, mute, warn, freeze, vanish, reports, playerinfo, invsee
Helper	soapsadmin.staffchat, soapsadmin.reports, soapsadmin.ticket.assign
Builder	soapsadmin.spawner, soapsadmin.itemeditor, soapsadmin.recipe.manage, soapsadmin.fakeplayer
Player	Defaults from plugin.yml (dashboard, home, warp, balance, msg, kits)

See Permissions.

6. Optional: Top-Level Commands

# customcommands.yml
settings:
  register-all-commands: true

Reload with /sa reload. SoapsAdmin takes priority over vanilla commands where names overlap.

7. Optional: Mythic / Crucible Stack

1. Install MythicMobs (and MythicCrucible if you use Crucible items).
2. Restart so soft-deps load.
3. Spawner type picker → MythicMobs tab.
4. Recipe wizard → type crucible:ItemId or use Held Item.
5. Configure economy.yml → mob-drops.mobs.mythicmobs.

Details: Integrations, Spawners, Recipes, Economy and Shop.

8. Optional: Reskin Built-in GUIs

Edit plugins/SoapsAdmin/gui/system-gui.yml (present after first boot), then /sa reload gui.

Troubleshooting First Boot

Problem	Fix
Plugin disabled on start	Install SoapsCommon first
No economy in other plugins	Enable vault-integration in economy.yml
GUIs do not open	Check config.yml gui.enabled and gui/_settings.yml
Commands say unknown	Module may be disabled in modules.yml
Mythic tab empty	MythicMobs not loaded, or no mobs registered
Crucible recipe fails	MythicMobs/Crucible not loaded, or wrong item id