waitUntil

Description

Suspends execution of scheduled script until the given condition satisfied.

• This command will loop and call the code inside {} mostly every frame, depends on complexity of the condition and the overall engine load, until the code returns true
• If the very first execution of the code returns true the command will exit immediately, therefore it will not produce any "Suspending not allowed in this context" error when used inside non-scheduled script. For all other uses it must be executed in environment that allows suspension (canSuspend), such as spawned or execVMed code
• Avoid doing waitUntil { time > 20 }; and use sleep 20; instead!
• If you can, add a sleep to the condition to save some cpu cycles waitUntil { sleep 1; !alive player };

Note

Arma 3: Since Arma 3 v1.94, a condition returning anything other than true or false will result in an appropriate type error.

Syntax

Syntax 1

waitUntil condition

Parameters:

• condition: Code - the expression that must return a Boolean, true to finish waiting or false to continue waiting

Returns: Anything - the value the condition evaluates to when the wait is over (normally true)

Syntax 2

since arma3 2.22

waitUntil [condition, timeout, interval]

Parameters:

• condition: Code - the expression that must return a Boolean, true to finish waiting or false to continue waiting
• timeout: Number - a timeout in seconds of game time (sleep vs uiSleep). The timeout is only checked after the condition was checked. Any negative value disables the timeout
• interval: Number - (Optional, default 0) the time interval in seconds of game time between condition checks, this is equivalent to using a "sleep" after the condition.

Returns: Anything - the value the condition evaluates to when the wait is over (normally true), or Nothing if the timeout ended the wait

Syntax 3

since arma3 2.22

waitUntil scriptHandle

Parameters:

• scriptHandle: Script Handle - a script handle or promise to wait on

Returns: Anything - The result of the script or Promise

Syntax 4

since arma3 2.22

waitUntil [scriptHandle, timeout]

Parameters:

• scriptHandle: Script Handle - a script handle or promise to wait on
• timeout: Number - a timeout in seconds of game time (sleep vs uiSleep)

Returns: Anything - the result of the script or Promise. Or Nothing if timed out.

Examples

Example 1

waitUntil { not alive player };

Example 2

_i = 0; waitUntil { _i = _i + 1; _i >= 100 };

Example 3

waitUntil can lead to performance loss if used improperly:

waitUntil { not alive player };            // bad
waitUntil { sleep 1; not alive player };    // good - checks every 1 second
player addEventHandler ["Killed", {  }];    // best - don't forget about Event Handlers

Example 4

An on-the-fly custom event handler:

_myEH = ["ZoomIn"] spawn {
    while { true } do
    {
        waitUntil { inputAction (_this select 0) == 1 };
        diag_log format ["%1 @ %2", _this select 0, diag_tickTime];
    };
};

Although it may be better to use onEachFrame (stacked) mission Event Handler, depending on the application.

Example 5

Use getVariable with default value to prevent unexcepted script errors:

waitUntil { bank getVariable ["money", 0] > 0 };
waitUntil { missionNamespace getVariable ["isready", false] };

Example 6

Always return Boolean:

waitUntil { sleep 1; if (not alive player) exitWith {}; _time = _time + 1 };                // bad
waitUntil { sleep 1; if (not alive player) exitWith { true }; _time = _time + 1; false };    // good
waitUntil { sleep 1; not alive player };                                                    // perfect

Problems

For some unknown reason if you have waitUntil loop active and game is saved/loaded, some variables in the expression may appear undefined for a short time. As a workaround, assign expression to a variable and make sure it is defined before waitUntil checks it:

waitUntil { private _expression = someBooleanVar && (someNumberVar > 10); !isNil "_expression" && { _expression } };

See also

sleep · uiSleep · canSuspend · spawn · execVM · while · Control Structures

waitUntil {
    // exit loop if the unit gets deleted
    if (isNull _unit) exitWith { true }; // has to return true to continue

    !alive _unit;
};

disableUserInput true;
player moveInDriver _vehicle; // this command is asynchronous and can fail sometimes
_time = time;
waitUntil {vehicle player == _vehicle || time - _time > 3};
disableUserInput false;