When (Triggers)
Last updated Oct 9, 2026
When (Triggers)
When defines what starts a Quick event or a multi-step event.
Pick a type in the GUI, then fill its settings. Short IDs only (no soaps: prefix in the UI).
How When works
- Something happens on the server (join, kill, schedule tick…).
- The engine finds matching When subscriptions (indexed by type and filters).
- Filters run first (world, mob, permission, cooldown).
- Only if runs next.
- Do / first Step runs if everything passed.
Hot Whens (interact, command) must use filters. Do not fire every rule on every click.
Built-in When catalog
| ID | Display name | What fires it | Common settings |
|---|---|---|---|
player_join |
Player join | Player joins the server | first join only (optional) |
player_quit |
Player quit | Player leaves | |
player_death |
Player death | Player dies | world, cause filters |
player_kill |
Player kill | Player kills entity or player | mob / player, world |
player_interact |
Player interact | Click block or air | material, hand, world |
player_command |
Player command | Player runs a command | command match, exact / starts with |
player_chat |
Player chat | Player sends chat | contains keyword |
player_respawn |
Player respawn | Player respawns | world |
block_break |
Block break | Player breaks a block | block / material, world |
block_place |
Block place | Player places a block | block / material, world |
player_level_up |
Player level up | Player gains a level | min level |
server_start |
Server start | Server finished loading | delay (optional) |
players_online_change |
Players online change | Online count changes | |
schedule |
Schedule | Clock time / cron-like | at (e.g. friday 20:00) |
interval |
Interval | Every N time | every (e.g. 2h) |
manual |
Manual | Staff start from GUI or command | |
player_damage |
Player deals damage | Player damages an entity | optional victim / victim_uuid |
player_hurt |
Player takes damage | Player is hurt by an entity | world |
player_jump |
Player jump | Paper jump event | world |
toggle_sneak |
Toggle sneak | Player starts sneaking | world |
craft_item |
Craft item | Non-creative craft result | item / material |
fish_catch |
Fish catch | Fishing rod catches fish | world |
glide_start |
Start gliding | Elytra glide begins | world |
player_move |
Player move | Block-move (throttled ~750ms) | world; prefer filters / cooldowns |
enter_region |
Enter region | Enter watched WG region | region |
leave_region |
Leave region | Leave watched WG region | region |
region_threshold |
Region headcount | Players in region crosses N | region, amount |
world_change |
World change | Player switched worlds | from / to |
player_teleport |
Teleport | Player teleports | optional cause |
item_consume |
Item consume | Eat / drink | ItemMatcher |
item_drop / item_pickup |
Drop / pickup | Item drop or pickup | ItemMatcher |
equip_armor / unequip_armor |
Armor change | Equip or unequip | ItemMatcher |
bed_enter / bed_leave |
Bed | Enter / leave bed | |
portal_use |
Portal | Nether / end portal | |
entity_spawn |
Entity spawn | Entity spawns | type + reason |
entity_interact |
Entity interact | Right-click entity | type filter |
entity_explode |
Entity explode | Creeper / other explode | type filter |
entity_death |
Entity death | Non-player entity dies | type filter |
weather_change |
Weather | Weather changes | |
world_day / world_night |
Day / night | World day-night transition | world |
projectile_hit |
Projectile hit | Arrow / projectile lands | target + item |
Region Whens only fire for region ids referenced by enabled events / running occupy goals (not every WG region).
ItemMatcher on Whens (item: or flat material / tag / name_* / custom_model_data / enchant / durability): shared with Only-if and Dos. Shift-click in the picker while holding the item to capture fields.
Filters (early reject)
Attach filters on the When so irrelevant traffic never reaches Only if.
| Filter | Example |
|---|---|
| World | world_nether (omit for any world; type here in the editor for your current world) |
| Permission | event.hunter |
| Mob / entity type | zombie |
| Material | oak_button |
| Cooldown / debounce | 250ms on noisy Whens |
GUI walkthrough
- Open the event → When
- Pick a type from the list (searchable)
- Fill settings with pickers (world, mob, duration…)
- Add filters if needed
- Preview line updates at the top of the editor
Addon and suite Whens
Extra Whens appear only when the matching plugin is installed. Examples:
| Source | When ids (examples) |
|---|---|
| SoapsFloor | floor_cleared, floor_started, floor_victory, floor_failed |
| SoapsArena | arena_match_end |
| SoapsQuest | quest_claimable, quest_redeemed |
| SoapsAdmin | money_changed |
| SoapsTeleporter | portal_teleport, portal_stabilize, portal_collapse |
| SoapsTraits | trait_changed |
| SoapsHungerStamina | stamina_empty |
Full list: Integrations.
If the plugin is missing, that When is not in the picker. A saved event that still references it fails validation until you change it.
Safety
- Prefer schedule / interval / join / kill over move-every-tick style Whens
- Set a world filter on interact and kill when the event is world-local; leave it blank for all worlds
- Manual When (
when.type: manual) is safest for testing; that is staff-start, not Kind