Wait

The Wait class is a static global class which allows you to schedule code (functions) to be executed later on.

Important

Please note that Wait does not pause Lua script execution, because that would freeze Tabletop Simulator! The next line of code after a Wait function call will always be executed immediately.

Function Summary

Function Name	Description	Return
condition( toRunFunc, conditionFunc, timeout, timeoutFunc)	Schedules a function to be executed after the specified condition has been met.
frames( toRunFunc, numberFrames)	Schedules a function to be executed after the specified number of frames have elapsed.
stop( id)	Cancels a Wait-scheduled function.
stopAll()	Cancels all Wait-scheduled functions.
time( toRunFunc, seconds, repetitions)	Schedules a function to be executed after the specified amount of time (in seconds) has elapsed.

---

Function Details

condition(...)

Schedules a function to be executed after the specified condition has been met.

The return value is a unique ID that may be used to stop the scheduled function before it runs.

condition(toRunFunc, conditionFunc, timeout, timeoutFunc)

• toRunFunc: The function to be executed after the specified condition is met.
• conditionFunc: The function that will be executed repeatedly, until it returns true (or the timeout is reached).
• timeout: The amount of time (in seconds) that may elapse before the scheduled function is cancelled.
  • Optional, defaults to never timing out.
• timeoutFunc: The function that will be executed if the timeout is reached.
  • Optional

conditionFunc will be executed (possibly several times) until it returns true, at which point the scheduled function (toRunFunc) will be executed, and conditionFunc will no longer be executed again.

Optionally, a timeout and timeoutFunc may be specified. If conditionFunc does not return true before the specified timeout (seconds) has elapsed, then the scheduled function is cancelled i.e. will not be called. If a timeoutFunc is provided, then it will be called when the timeout is reached.

Example

Roll a die, and wait until it comes to rest.

die.randomize() -- Roll a die
Wait.condition(
    function() -- Executed after our condition is met
        if die.isDestroyed() then
            print("Die was destroyed before it came to rest.")
        else
            print(die.getRotationValue() .. " was rolled.")
        end
    end,
    function() -- Condition function
        return die.isDestroyed() or die.resting
    end
)

Example

Launch an object into the air with a random impulse and wait until it comes to rest. However, if it's taking too long (more than two seconds), give up waiting.

local upwardImpulse = math.random(5, 25)
object.addForce({0, upwardImpulse, 0})
Wait.condition(
    function()
        if object.isDestroyed() then
            print("Object was destroyed before it came to rest.")
        else
            print("The object came to rest in under two seconds.")
        end
    end,
    function()
        return object.isDestroyed() or object.resting
    end,
    2, -- second timeout
    function() -- Executed if our timeout is reached
        print("Took too long to come to rest.")
    end
)

---

frames(...)

Schedules a function to be executed after the specified number of frames have elapsed.

The return value is a unique ID that may be used to stop the scheduled function before it runs.

frames(toRunFunc, frameCount)

• toRunFunc: The function to be executed after the specified number of frames have elapsed.
• numberFrames: The number of frames that must elapse before toRunFunc is executed.
  • Optional, defaults to `1`.

Example

Prints "Hello!" after 60 frames have elapsed.

Wait.frames(
    function()
        print("Hello!")
    end,
    60
)

It's a matter of personal preference, but it's quite common to see the above compacted into one line, like:

Wait.frames(function() print("Hello!") end, 60)

Advanced Example

Prints "1", "2", "3", "4", "5", waiting 60 frames before each printed number.

Note that the scheduled function, upon execution, will reschedule itself unless count has reached 5.

local count = 1
local function printAndReschedule()
    print(count)

    if count < 5 then
        count = count + 1
        Wait.frames(printAndReschedule, 60)
    end
end

Wait.frames(printAndReschedule, 60)

---

stop(...)

Cancels a Wait-scheduled function.

stop(id)

• id: A wait ID (returned from Wait scheduling functions).

Example

Schedules two functions: one that says "Hello!", and one that says "Goodbye!". However, the latter is stopped before it has a chance to execute i.e. We'll see "Hello!" printed, but we won't see "Goodbye!"

Wait.time(function() print("Hello!") end, 1)
local goodbyeId = Wait.time(function() print("Goodbye!") end, 2)
Wait.stop(goodbyeId)

---

stopAll(...)

Cancels all Wait-scheduled functions.

Warning

You should be extremely careful using this function. Generally you should cancel individual scheduled functions with stop instead.

Example

Schedules two functions: one that says "Hello!", and one that says "Goodbye!". However, both are stopped before either has the chance to execute.

Wait.time(function() print("Hello!") end, 1)
Wait.time(function() print("Goodbye!") end, 2)
Wait.stopAll()

---

time(...)

Schedules a function to be executed after the specified amount of time (in seconds) has elapsed.

The return value is a unique ID that may be used to stop the scheduled function before it runs.

time(toRunFunc, seconds, repetitions)

• toRunFunc: The function to be executed after the specified amount of time has elapsed.
• seconds: The amount of time that must elapse before toRunFunc is executed.
• repetitions: Number of times toRunFunc will be (re)scheduled. -1 is infinite repetitions.
  • Optional, defaults to `1`.

repetitions is optional and defaults to 1. When repetitions is a positive number, toRunFunc will execute for the specified number of repetitions, with the specified time delay before and between each execution. When repetitions is -1, toRunFunc will be re-scheduled indefinitely (i.e. infinite repetitions).

Example

Prints "Hello!" after 1 second has elapsed.

Wait.time(
    function()
        print("Hello!")
    end,
    1
)

It's a matter of personal preference, but it's quite common to see the above compacted into one line, like:

Wait.time(function() print("Hello!") end, 1)

Example

Prints "1", "2", "3", "4", "5", waiting 1 second before each printed number.

local count = 1
Wait.time(
    function()
        print(count)
        count = count + 1
    end,
    1, -- second delay
    5 -- repetitions
)

---