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:

.. code-block:: python

    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:

.. code-block:: python

    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:

- :doc:`../_generated/Varwin_WaitForSeconds` — suspends execution for a specified number of seconds.
- :doc:`../_generated/Varwin_WaitForEndOfFrame` — suspends execution until the end of the current frame.
- :doc:`../_generated/Varwin_WaitWhile` — suspends execution while the specified condition (callable) returns ``True``.

Example with ``WaitWhile``:

.. code-block:: python

    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.