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.