Syntax

listen for <.+>

Description

Declarative event listener. Two forms are available: ` - listen for event [where cond]:` registers immediately. ` - set %~object% to listener for event [where cond]:` defines the listener for later activation via `register`. Optional entries: ` - countdown: timespan` sets an auto-timeout duration. Required when `on timeout:` is used. ` - triggers: number` caps how many times the listener fires before `on completion:` runs. ` - cooldown: timespan` debounces the listener: after an accepted trigger, further events within this window are ignored, so they don't run `on trigger:` and don't count toward `triggers:`. Per-listener, so scope it to a player (via `owner:`/`where`) for a per-player cooldown. ` - owner: offlineplayer/entity/chunk/world` scopes the listener to that owner and auto-unregisters when the owner goes away: a player disconnecting, an entity being removed from the world (death/despawn), or a chunk/world unloading. Any owner can be bulk-cleaned with `unregister all listeners owned by %object%`. Optional sections: ` - where:` adds extra filter conditions that must all pass. Combines with any inline `where` clause. ` - every timespan:` runs its body on a repeating timer while the listener is active (and is paused along with the listener). Useful for live displays, e.g. an action-bar countdown. ` - on trigger:` runs each time the event fires after filters pass. Inside it, `cancel listener` stops early without firing completion or timeout, and `skip trigger` ignores the current event without consuming a `triggers:` slot. ` - on completion:` runs once `triggers:` is reached. ` - on timeout:` runs when `countdown:` elapses. ` - on end:` runs whenever the listener stops, however it stops: after completion, after timeout, and on `cancel listener`/`unregister`/owner-disconnect cleanup. Use it for teardown; `end reason` tells you why it stopped. ` - on pause:` runs each time the listener is paused (via `pause %listener%`), after the countdown freezes. ` - on resume:` runs each time the listener is resumed (via `resume %listener%`), after the countdown restarts. ` - on register:` runs once the listener becomes active (immediately for `listen for ...:`, or when `register %listener%` activates a declared one), symmetric with `on end:` for setup/teardown. Expressions valid inside any callback: ` - remaining triggers` reports the fires left before completion. ` - remaining countdown` reports the time left before timeout. ` - end reason` (inside `on end:`) is `completion`, `timeout`, `cancelled`, or `unregistered`.

Examples

listen for block break where event-block is stone:
	where:
		event-player is sneaking
	countdown: 30 seconds
	triggers: 10
	cooldown: 1 second
	on trigger:
		if event-world is not "world":
			skip trigger
		send "keep going... (%remaining triggers% left)" to event-player
	every 5 seconds:
		send action bar "%remaining countdown% left" to event-player
	on completion:
		send "you did it!" to event-player
	on timeout:
		send "too slow! (%remaining triggers% left to break)" to event-player
	on pause:
		send "challenge paused (%remaining countdown% left)" to event-player
	on resume:
		send "challenge resumed!" to event-player
	on end:
		send "challenge over (%end reason%)" to event-player