Event Engine

The Event Engine is the owner-facing product inside SoapsCommon: server automation and multi-step events without a custom plugin.
Build with /soaps: pick When, Only if, Do, and Steps. Definitions save under plugins/SoapsCommon/.

You still need this jar for every other Soaps plugin. Library features (menus, text, chat input) work whether the engine is on or off.

---

Canonical shape

Every definition uses the same three segments (root and each step):

When  →  Only if  →  Do

id: example
description: "Short blurb shown in the event list lore."
name: "Example"
enabled: false
type: automation   # Kind: automation | event (list filters use this)
# event meta (events always; automations only when non-default):
# cooldown: 1h
# max_running: 1
when:
  type: player_join   # staff-start uses type: manual (Start / Shift-left)
only_if:
  - players_online: ">= 4"   # also: "<= 10" or "4 <= x <= 10"
  # - players: [Alice, Bob]  # named players must be online
do:
  # - participants: { mode: starter }   # lock audience to starter (joiners via add_participant)
  # - participants: { players: [Alice, Bob] }
  - message: "<green>Hi!"

Kind (type:) vs staff-start (when.type: manual) are different. Filters Automations / Events follow Kind. Enable + Start is required when When is manual. See FAQ.

Default audience is open (anyone can progress goals; online players are seeded as participants). Use Only-if for start gates (counts / names). Use Do participants to lock the audience to starter or named players.

Header order is fixed: id → description → name → enabled → type → cooldown → max_running → when → only_if → do / steps. GUI saves use the same order. Description appears automatically in list and detail item lore.

Multi-step events add steps with per-step only_if, do, goal, and next.

---

Plain language

Word	Meaning
When	What starts the rule or event
Only if	Requirements that must pass
Do	What happens
Step	One stage of a longer event
Goal	Progress target (kill, collect, reach…)
Next	When to leave a step
Event	Saved definition you edit
Running	Live instance on the server

Quick automations stop at When → Only if → Do.
Full events add Steps, Goals, and Next.

---

Two creation modes

Quick event (default)

When → Only if → Do → Save / Test

Examples: welcome kit, undead bounty, weekend promo (see Examples).

Event with steps

When → Only if → Steps (only_if, lasts, do, goal, next) → Save / Test

Examples: undead siege, ore challenge, XP boost night, community mine.

Same engine. Different depth. GUI covers blank create, pickers, and run control; YAML covers rare fields.

---

How it fits the suite

SoapsCommon owns the engine runtime and staff GUIs.
Installed Soaps plugins add native When / Only if / Do types into the same pickers (Floor clears, Arena match end, Quest claim, portals, traits, stamina, Admin money / warp, and more). Soft plugins (MythicMobs, Vault, WorldGuard) do the same.

Full table: Integrations.

Do not use the engine to rewrite Quest, Arena, or Floor. Hook them with those native types (or console_command when you need a one-off).

---

Defaults that matter

• Players stay where they are unless a Do teleports them
• Resume after restart reloads the current definition YAML for that id (not a frozen snapshot file)
• Dangerous Dos (console, big spawns) go through the command sandbox and admin perms (no GUI confirm checkbox)
• World / location prompts accept here for the world or block you stand on; omit world filters for any world
• Everything the engine spawns should be tagged and cleaned up
• Missing soft plugins (MythicMobs, Vault…) show clear “unavailable” on validate / start

---

Module toggle

Global settings include engine.enabled in engine.yml.
If disabled, Common behaves as the shared library only (menus, text, services).

---

See also

Page	Content
Event GUI	In-game editors and list UX
Composition Cookbook	Item procs, cancel, audiences, call_event
When / Only if / Do	Catalogs
Examples	Seeded automations and events
FAQ	Enable vs Start vs Kind