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`. Events that fire off the main thread (e.g. async chat) are supported, but their callbacks are run on the main thread the following tick, so they cannot cancel or modify the triggering event.

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