Структура проекта
======

Структура файлов и папок
------------------------

При создании проекта в среде Varwin автоматически формируется следующая иерархия файлов и директорий:

.. code-block:: bash

    ├── Blockly.py
    ├── Main.py
    └── Varwin/
        ├── Varwin.py
        ├── SceneObjectTypes.py
        ├── SceneObjects.py
        └── Objects/

Каждый элемент этой структуры играет определённую роль в архитектуре приложения.

Blockly.py
----------

**Тип файла**: только для чтения  

**Назначение**: содержит логику, сгенерированную визуальным редактором блоков (Blockly).

Этот модуль автоматически обновляется при изменении в визуальном редакторе. 

Main.py
-------

**Тип файла**: редактируемый

**Назначение**: основная точка входа в приложение.

Этот файл предназначен для подключения пользовательских модулей, расширения или переопределения поведения, заданного в ``Blockly.py``, а также для реализации кастомной логики.

Пример содержимого:

.. code-block:: python

    import Varwin
    from SceneObjects import *
    import Blockly

    async def OnStart():
        # Пользовательская инициализация при запуске сцены
        pass

    async def OnUpdate():
        # Логика, выполняемая зацикленно
        pass

    # Регистрация пользовательских обработчиков
    Varwin.Async.AddStart(OnStart)
    Varwin.Async.AddUpdate(OnUpdate)

Varwin.py
----------------

**Тип файла**: только для чтения  

**Назначение**: предоставляет API для взаимодействия с объектами сцены, системными событиями и служебными функциями.

Основные возможности:

- Управление жизненным циклом сцены (например, ``Varwin.Async.AddStart``)
- Отладочный вывод (``Varwin.Debug.Log``)
- Доступ к объектам сцены
- Реализация корутин
- Стандартные поведения 

Полный перечень доступных классов, функций и методов с сигнатурами, параметрами и примерами использования приведён в разделе:

:doc:`../_generated/Varwin`

SceneObjectTypes.py
--------------------------

**Тип файла**: только для чтения  

**Назначение**: маппинг технических имён типов объектов на удобочитаемые псевдонимы.

Внутренние имена объектов имеют формат ``<C#_TypeName>_<Root_GUID>``. Этот модуль заменяет их на короткие и понятные имена.

.. warning::
    Если в проекте обнаружены конфликтующие имена (два разных типа с одинаковым псевдонимом),
    система автоматически использует полное имя с GUID, чтобы избежать неоднозначности.

SceneObjects.py
----------------------

**Тип файла**: только для чтения  

**Назначение**: содержит экземпляры всех объектов, размещённых на сцене.

Каждый объект представлен как переменная с именем, заданным в поле **«Имя переменной»** в редакторе сцены.

Пример:

.. code-block:: python
    
    from SceneObjectTypes import *

    # В редакторе сцены задано имя переменной: player
    player = PlayerWrapper(...)

Этот модуль автоматически генерируется и обновляется при изменении сцены.

.. tip::
    Используйте ``from SceneObjects import *`` в ``Main.py`` или других модулях
    для прямого доступа к объектам по их именам.

Пользовательские модули
-----------------------

**Тип файла**: редактируемый

**Назначение**: расширение функциональности приложения.

Varwin поддерживает **модульную архитектуру**, позволяя разделять логику на независимые Python-файлы.

Преимущества:

- **Читаемость**: каждая функциональная область вынесена в отдельный файл.
- **Изоляция**: каждый модуль имеет собственное пространство имён.
- **Повторное использование**: модули легко импортировать в других проектах.
- **Автоматическая загрузка**: платформа управляет порядком инициализации (при отсутствии циклических зависимостей).

Как использовать:

1. Создайте новый Python-файл (например, ``movement.py``).
2. Реализуйте в нём нужную логику.
3. Импортируйте модуль в ``Main.py`` или другом месте.

Пример:

Файл ``MyModule.py``:

.. code-block:: python

    import Varwin

    def hello():
        Varwin.Debug.Log("Привет, Мир!")

Файл ``Main.py``:

.. code-block:: python

    import Varwin
    import MyModule

    async def OnStart():
        MyModule.hello()

    Varwin.Async.AddStart(OnStart)

.. tip::
    Группируйте связанную логику в отдельные модули:
    
    - ``movement.py`` — управление перемещением объектов
    - ``sensors.py`` — обработка данных с датчиков
    - ``ui.py`` — взаимодействие с пользовательским интерфейсом
    - ``ai.py`` — поведенческие алгоритмы