SoapsUniverse

Composition Cookbook

Last updated Oct 9, 2026

Composition Cookbook

Recipes that stay in When → Only if → Do using composition (items, cancel, audiences, chaining). Not a fourth DSL.

Seeded showcases that use these ideas: blaze_blade, help_desk, arena_call, hot_potato, freeze_frenzy. Full list: Examples.

1) Named-sword hit proc

Rename a diamond sword so the name contains Blaze (anvil), or give a tagged sword with give_named.

id: blaze_blade
type: automation
enabled: true
when:
  type: player_damage
  item:
    material: DIAMOND_SWORD
    name_contains: Blaze
only_if:
  - chance: 25
do:
  - damage: { amount: 2, target: victim }
  - particle: { particle: FLAME, count: 18 }
  - action_bar: "<gold>Blaze Blade scorches!"

In the picker: hold the sword → Shift-click an item-aware When/Only-if to fill matcher fields (material, tag, name).

2) Spawn cancel break (rules engine)

id: spawn_protect_break
type: automation
enabled: true
when:
  type: block_break
only_if:
  - region: spawn
    fail_message: "<red>No breaking in spawn."
    fail_cancel: true
do:
  - cancel_event: {}

cancel_event needs a cancellable Bukkit When (break/place/interact/command…). Fail feedback uses fail_message / fail_cancel / fail_do on Only-if leaves. Set region to your real WorldGuard region id.

3) Arena auto-start (region_threshold)

id: arena_auto_start
type: automation
enabled: true
when:
  type: region_threshold
  region: arena
  amount: ">= 4"
only_if:
  - players_in_region: { region: arena, amount: ">= 4" }
do:
  - call_event: { event: arena_match, vars: { round: 1 } }
  - broadcast: "<green>Arena match starting!"

Use your WorldGuard region ids. Create arena_match as a separate event.

4) Around-players shockwave

do:
  - around_players:
      radius: 8
      include_self: false
      do:
        - damage: { amount: 2 }
        - particle: { particle: EXPLOSION, count: 4 }
  - to_victim:
      do:
        - effect: { effect: slowness, duration: 2s, amplifier: 1 }

Optional meta on any Do: chance, cooldown, delay (ticks), require (soft placeholder gate).

5) VIP gate + PlaceholderAPI

only_if:
  - permission: event.vip
    fail_message: "<red>VIP only"
    fail_do:
      - sound: { sound: BLOCK_NOTE_BLOCK_BASS }
  - placeholder_match: { left: "%vault_eco_balance%", op: ">=", right: "1000" }

See also