Usage examples
---------------------

Below are typical scenarios for using the Varwin Python API in real projects.  
The examples cover object management, asynchronous scenarios, user interaction, and integration with external systems.

Training Scenario Automation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creating a sequential training process with visual feedback:

.. code-block:: python

    async def TrainingSequence():
        # Display instruction
        instruction.Activate()
        await Varwin.WaitForSeconds(3)
        instruction.Deactivate()

        # Activate equipment
        machine.Activate()
        await Varwin.WaitForSeconds(1)

        # Wait for correct user action
        await Varwin.WaitWhile(lambda: not valve.IsOpen)
        success_sound.Play()
        await Varwin.WaitForSeconds(2)

        # Complete stage
        stage_complete.Activate()

    Varwin.Async.AddStart(TrainingSequence)

Yandex GPT Integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using the Yandex GPT cloud language model to generate context-dependent responses or hints in simulations:

.. code-block:: python
    
    import json

    async def GetHintFromGPT(context: str):
        # Token and folder from Yandex Cloud settings
        iam_token = "YOUR_IAM_TOKEN"
        folder_id = "YOUR_FOLDER_ID"

        payload = {
            "modelUri": f"gpt://{folder_id}/yandexgpt/latest",
            "completionOptions": {
                "stream": False,
                "temperature": 0.6,
                "maxTokens": "50"
            },
            "messages": [
                {"role": "system", "text": "You are a safety training assistant in a VR simulator."},
                {"role": "user", "text": f"The user cannot open the emergency valve. Context: {context}"}
            ]
        }

        response = await Varwin.Requests.Post(
            "https://llm.api.cloud.yandex.net/foundationModels/v1/completion",
            json=payload,
            headers={
                "Authorization": f"Bearer {iam_token}",
                "Content-Type": "application/json"
            }
        )

        if response.status_code == 200:
            data = json.loads(response.text)
            hint_text = data["result"]["alternatives"][0]["message"]["text"]
            hint_ui.SetText(hint_text)
            hint_ui.Show()
        else:
            Varwin.Debug.LogError(f"GPT error: {response.status_code}")

    # Called when the "Hint" button is pressed
    Varwin.Async.Run(GetHintFromGPT("Valve is stuck, requires counter-clockwise lever rotation."))

Scene Event Handling
~~~~~~~~~~~~~~~~~~~~~~~~

Processing user interactions with objects in real-time:

.. code-block:: python

    def OnAlarmButtonPressed(sender):
        alarm.Play()
        door.Lock()
        Varwin.Async.Run(StartEmergencyProtocol())

    # Register handler
    alarmButton.AddButtonPressedHandler(OnAlarmButtonPressed)

These examples demonstrate how the Varwin Python API enables creating flexible, interactive, and integrable VR scenarios — from simple training tasks to complex industrial simulations.