Asynchronous programming

To implement scenarios with asynchronous behavior — such as sequential animations, delays, condition waiting, or non-blocking logic execution — the Varwin platform provides built-in support for coroutines based on the async/await syntax.

Unlike the standard asyncio library, Varwin’s asynchronous model is integrated directly with the engine’s game loop and guarantees that all user code executes in the main thread, where all scene objects and their methods are accessible.

The Varwin.Async Class

The main entry point for working with coroutines is the Varwin.Async class. It provides methods for registering and starting asynchronous functions within the scene’s lifecycle context.

Key Methods:

  • Varwin.Async.Run(coro) — immediately starts the passed coroutine.

  • Varwin.Async.AddStart(coro_func) — registers an asynchronous function (not the call result!) to be launched once when the scene starts.

  • Varwin.Async.AddUpdate(coro_func) — registers an asynchronous function to be called in a loop (similar to Update in Unity, but with await support).

Usage Example:

async def Chain2():
    # Scale the object over 1 second
    await cube10.ScaleBehaviour.ScaleOverTime(Varwin.Vector3(7, 1, 1), 1)
    # Wait for 2 seconds
    await Varwin.WaitForSeconds(2)
    # Return to the original scale
    await cube10.ScaleBehaviour.ScaleOverTime(Varwin.Vector3(1, 1, 1), 1)

# Start the coroutine
Varwin.Async.Run(Chain2())

Important: When using AddStart and AddUpdate, pass the function itself, not its call:

Varwin.Async.AddStart(Chain2)  # ✅ Correct
# Varwin.Async.AddStart(Chain2())  # ❌ Error: function is already called

Built-in Awaitable Objects

For organizing delays and synchronization with the game loop, Varwin provides special awaitable objects. They suspend coroutine execution until a specific event occurs.

Available Types:

  • WaitForSeconds — suspends execution for a specified number of seconds.

  • WaitForEndOfFrame — suspends execution until the end of the current frame.

  • WaitWhile — suspends execution while the specified condition (callable) returns True.

Example with WaitWhile:

async def WaitCubeMoving():
    await Varwin.WaitWhile(lambda: cube.MotionBehaviour.Position.X < 5.0)
    Varwin.Debug.Log("Cube reached X=5 position!")

Warning

Do not use the standard asyncio library for interacting with scene objects. All engine components (including transformations, behaviors, events) are available only in the main thread, while asyncio may execute code in background threads or event loops not connected to the game loop. This will lead to errors or undefined behavior.

Recommendations

  • Use coroutines for sequential scenarios: animation → delay → sound → trigger activation.

  • Avoid blocking calls (e.g., time.sleep()) — they will halt the entire engine.

  • Always prefer await Varwin.WaitForSeconds(...) over synchronous delays.

  • For parallel execution of multiple tasks, launch several coroutines via Varwin.Async.Run().

Coroutines in Varwin are a safe and convenient way to write readable, sequential logic without explicit state or timer management.