Project structure
======

File and Folder Structure
------------------------

When creating a project in the Varwin environment, the following file and directory hierarchy is automatically generated:

.. code-block:: bash

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

Each element in this structure plays a specific role in the application architecture.

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

**File Type**: Read-only  

**Purpose**: Contains logic generated by the visual block editor (Blockly).

This module is automatically updated when changes are made in the visual editor.

Main.py
-------

**File Type**: Editable

**Purpose**: Main application entry point.

This file is intended for importing custom modules, extending or overriding behavior defined in ``Blockly.py``, and implementing custom logic.

Example content:

.. code-block:: python

    import Varwin
    from SceneObjects import *
    import Blockly

    async def OnStart():
        # Custom initialization when scene starts
        pass

    async def OnUpdate():
        # Logic executed in loop
        pass

    # Register custom handlers
    Varwin.Async.AddStart(OnStart)
    Varwin.Async.AddUpdate(OnUpdate)

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

**File Type**: Read-only  

**Purpose**: Provides API for interacting with scene objects, system events, and utility functions.

Key capabilities:

- Scene lifecycle management (e.g., ``Varwin.Async.AddStart``)
- Debug output (``Varwin.Debug.Log``)
- Access to scene objects
- Coroutine implementation
- Standard behaviors

Complete list of available classes, functions, and methods with signatures, parameters, and usage examples can be found in:

:doc:`../_generated/Varwin`

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

**File Type**: Read-only  

**Purpose**: Maps technical type names to human-readable aliases.

Internal object names follow the format ``<C#_TypeName>_<Root_GUID>``. This module replaces them with short and clear names.

.. warning::
    If conflicting names are detected in the project (two different types with the same alias),
    the system automatically uses the full name with GUID to avoid ambiguity.

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

**File Type**: Read-only  

**Purpose**: Contains instances of all objects placed in the scene.

Each object is represented as a variable with the name specified in the **"Variable Name"** field in the scene editor.

Example:

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

    # Variable name set in scene editor: player
    player = PlayerWrapper(...)

This module is automatically generated and updated when the scene changes.

.. tip::
    Use ``from SceneObjects import *`` in ``Main.py`` or other modules
    for direct access to objects by their names.

Custom Modules
-----------------------

**File Type**: Editable

**Purpose**: Extending application functionality.

Varwin supports **modular architecture**, allowing logic to be separated into independent Python files.

Advantages:

- **Readability**: Each functional area is separated into its own file.
- **Isolation**: Each module has its own namespace.
- **Reusability**: Modules can be easily imported into other projects.
- **Automatic loading**: The platform manages initialization order (when there are no circular dependencies).

How to use:

1. Create a new Python file (e.g., ``movement.py``).
2. Implement the required logic in it.
3. Import the module in ``Main.py`` or elsewhere.

Example:

File ``MyModule.py``:

.. code-block:: python

    import Varwin

    def hello():
        Varwin.Debug.Log("Hello, World!")

File ``Main.py``:

.. code-block:: python

    import Varwin
    import MyModule

    async def OnStart():
        MyModule.hello()

    Varwin.Async.AddStart(OnStart)

.. tip::
    Group related logic into separate modules:
    
    - ``movement.py`` — object movement control
    - ``sensors.py`` — sensor data processing
    - ``ui.py`` — user interface interaction
    - ``ai.py`` — behavioral algorithms