wait

Wait commands

Server-side condition waiting (AUTHAPI-25). job wait waits until a runtime/editor member condition holds — evaluated on the Editor's per-frame loop — and can act in the same frame the condition first becomes true (e.g. screenshot the moment a match-end screen appears). It replaces the dominant agent anti-pattern of client-side polling loops: read a value via script eval, sleep in the client, repeat. That loop is token-expensive and slow, and its client round-trips can miss short-lived states entirely (a 2-second screen is easy to miss at ~1–2 s per poll). A server-side condition is a cheap per-frame delegate that can act atomically the frame it fires.

Sync vs async: pick the right mode first

/api/exec executes one command at a time — a synchronous job wait holds that queue for its entire duration. The Editor itself never freezes (each poll is marshaled onto the main thread between sleeps), but every other command queues behind the wait until it resolves. That includes any command whose effect your condition is waiting for: if the condition needs a mutation you haven't issued yet, the mutation can never run, and the wait self-deadlocks until its timeout.

Use a synchronous wait only when BOTH hold:

• the wait is short — comfortably under your client's HTTP timeout (typically < 30 s), and
• the condition does not depend on any command you still need to issue (it will be satisfied by something already in motion: play-mode gameplay, a running bake, a timer, ...).

For everything else, pass async=true: you get a waitId back immediately, other commands keep executing, and you poll job wait_status (and cancel with job wait_cancel). This is the default choice for long waits and for any "issue command, then wait for its effect" flow.

A synchronous wait submitted as a detached job (POST /api/exec with "job": true) remains cancelable: POST /api/job/cancel interrupts the sleep loop and resolves the wait as canceled.