SoapsUniverse

Steps and Events

Last updated Oct 9, 2026

Steps and Events

Multi-step events are state machines made of Steps and Next rules.
Quick events have no steps (only When → Only if → Do).

Event vs running

Event Running
What Saved definition you edit Live instance
Edit while live? Saves a new version for future runs Continues on its snapshot
ID undead_siege undead_siege#42 (example)

Step fields

Field Meaning
Id Internal key (invasion)
Name Display name
Lasts Optional duration (60s, 10m, or bare ticks e.g. 3000 = 150s)
Only if Optional step gates. Must pass to run this step’s Do / goal
Do Actions on enter (after Only if)
Goal Optional progress target
Next Leave rules (priority order, first match)

Step Only if failure skips Do and goal for that entry; after_time next rules can still fire. Root Only if still gates the whole event start.

Step fields are edited in the Steps GUI. List order is left to right. Shift-left moves a step earlier, shift-right moves it later, and Drop deletes it. The green book (or Shift-click on a step title) marks which step starts the event. Next rules still control the live path between steps.

Emergency stop always clears stash, locks, tagged entities, pulses, and boss bars. The optional step named cleanup (or wrap) is skipped on a normal stop. Use Shift-stop (list / Running / More) or /soaps events stop <id> --cleanup to run that step’s Dos first.

Next rules

Kind Meaning
after_time Step timer expired → go to step
goal_done Goal completed → go to step
goal_fail Goal failed (for example hangman out of guesses) → go to step
then Immediate → go to step (after Dos, or when there is no timer/goal wait)
variable Variable compare → go to step

Priority: lower number first (or list order). First match wins. No ambiguous double jumps.

Participation / audience

Approach Role
Default (no Do) Open audience. Anyone may progress goals; online players seeded
Only-if players_online Start gate: >= 4, <= 10, 4 <= x <= 10
Only-if players Start gate: named players must be online (any: true = at least one)
Do participants Lock audience: mode: starter / online, or players: [A, B]
Do add_participant Opt-in join (join_prompt / /soaps join)

Opt-in join: use the join_prompt Do for a clickable chat link. Optional teleport, or a WorldGuard region gate when no teleport is set. Mute does not hide join prompts.

Default feel: play in place. Teleport only if a Do teleports.

Scheduling and pools

  • Schedule / interval When: clock-driven starts
  • Event pool: pick among listed events (weight / chance / list) via pools.yml or the Pools GUI. Optional pool When auto-starts the same way as an event. Defaults: weekend, showcase (disabled until you enable events + pool)
  • Admin start via /soaps pools start <id> (honors the pool’s pick mode)
  • Pool file layout: Configuration

Cooldown and limits

Setting Purpose
Cooldown Wait before the same event can start again
Max running Cap simultaneous instances of this definition
Global budgets Cap actions/spawns across the engine

Cleanup

Track what the engine created:

  • Tagged entities from spawn
  • Temporary tasks / boss bars
  • Temporary effects the engine applied (when supported)

On end, cancel, fail, disable, or restart recovery:

cleanup tag → cancel tasks → clear bars → end

Never delete entities you did not tag.
World block changes (if added later) need restore limits and claim checks.

Boss bars and live control

  • Attach boss_bar Dos to timed steps or goal progress ({goal.progress} and related tokens)
  • Staff Running now: click = extend +1 minute; right-click = stop without cleanup; Shift-right = stop and run cleanup Dos
  • CLI: /soaps events extend <runningId> <duration> for a custom extend (needs soaps.engine.events.start)
  • Players: /soaps me browser and /soaps mute for broadcasts / boss bars

Validation before start

Examples of blocked starts:

  • Goal references a missing MythicMob type and Mythic is not installed
  • Next points to a missing step id
  • Spawn without a tag when cleanup is required
  • Expression parse error

Errors name the step and the fix.

See also