Development Workflow
====================

This guide covers the core development activities using the Blender Extension Integration plugin, from running Blender to hot-reloading and building your extension.

Running Blender for Development
-------------------------------

The primary way to test your extension is using the **Start Blender** run configuration.

*   **Blender Version Dropdown**: Choose between Managed versions (automatically downloaded), **System Discovered** versions, or **Custom** paths.
*   **Sandbox Mode**: (Recommended) Runs Blender using a project-local directory (``.blender_sandbox``). This prevents development settings from affecting your main Blender installation.
*   **Import User Configuration**: When sandboxing is enabled, check this to copy your main Blender preferences into the sandbox.
*   **Addon Source Directory**: Specifies where your source code is located (defaults to ``src``).
*   **Addon Symlink Name**: The folder name inside Blender's extension repository that will point to your source.

Hot-Reloading
-------------

The plugin features a robust hot-reloading mechanism to see changes immediately without restarting Blender.

### Automatic Reload
1.  Go to **Settings** > **Tools** > **Blender Extension Integration**.
2.  Check **Auto-reload extension on save**.
3.  Whenever you save a file (``Ctrl+S``), the plugin sends a reload command to Blender.

### Manual Reload
*   **Keyboard Shortcut**: ``Ctrl+Alt+R``.
*   **Menu Action**: **Blender** > **Reload Extension**.

### How it Works
The reload process disables the extension, purges ``sys.modules``, refreshes repositories, and re-enables the extension for a clean import.

CLI Tools & Building
--------------------

Blender 4.2+ includes a dedicated CLI for extension management. The plugin provides integrated run configurations for these:

### Build
Runs ``blender --command extensions build``. Generates a ``.zip`` file for distribution based on your manifest's include/exclude patterns.

### Validate
Runs ``blender --command extensions validate``. Verifies IDs, versions, and permissions in ``blender_manifest.toml``.

### Custom Commands
Create a **Blender** run configuration with the **Command** template to run any arbitrary ``blender --command <cmd>`` operation.

Testing
-------

### Custom Splash Screens
In sandboxed mode, place a ``splash.png`` in your project root to override the development splash screen.

### Unit & Integration Testing
*   **Unit Tests**: Cover path resolution and manifest parsing.
*   **Headless Tests**: Verify TCP heartbeat and reload logic using a headless Blender instance.

### Offline Telemetry
Local-only telemetry records error reports and metrics within ``.blender_sandbox`` for debugging.