Blender Professional Extension Scaffold

A highly modular, testable, and scalable architectural foundation for building production-grade Blender addons.

This project is not a finished tool, but a framework designed to solve the common "spaghetti code" problem in Blender development by enforcing a strict separation of concerns between the Blender API (bpy), business logic, and the user interface.

---

🏗️ Architecture (The "Shape")

The codebase follows a layered, unidirectional dependency flow. This prevents the common pitfall of embedding heavy logic inside Blender operators.

Dependency Flow: UI Components $\rightarrow$ Service Layer $\rightarrow$ Bridge Interface $\rightarrow$ [bpy (Real) OR Mock (Testing)]

Layer Breakdown:

1. UI Layer (ui/): Purely responsible for visual representation. It contains Panels (layouts) and Operators (command triggers). Operators should do nothing more than call a method in the Service Layer.
2. Service Layer (core/services.py): The "brain" of your extension. This is where your actual business logic lives. It interacts with Blender only through the Bridge. This layer is pure Python and can be unit-tested without Blender.
3. Bridge Layer (core/bridge.py): An abstraction layer that uses the Composition Pattern. Instead of one giant class, it provides specialized sub-interfaces (e.g., bridge.mesh, bridge.materials) to make the API discoverable and modular.
4. Shared Layer (shared/): Common data models, math utilities, and logging wrappers used across all layers.

---

✨ Key Features

• Modular Bridge Pattern: Highly discoverable API via sub-interfaces (objects, mesh, materials, scene).
• Zero-Blender Testing: Includes a MockBlenderBridge that simulates Blender's behavior, allowing you to run your entire service logic in a standard Python environment (e.g., via pytest).
• Service-Oriented Design: Encourages clean, reusable logic decoupled from the UI.
• UI Scaffolding: Pre-built templates for Sidebar Panels, Operators, and Addon Preferences.
• Lifecycle Orchestration: A centralized registration.py that handles the complex order of registering/unregistering Blender classes.
• Persistent Configuration: Built-in support for bpy.types.AddonPreferences.

---

⚠️ Current Limitations & Caveats

As this is a scaffold, please be aware of the following:

• Scope: The current Bridge only implements a subset of bpy. You must extend the BridgeInterface and its Real implementations as your tool grows.
• Mock Depth: The MockBlenderBridge is a lightweight simulation. Complex bpy interactions (like advanced geometry nodes or specific shader math) will require manual mocking in your tests.
• Manual Implementation Required: This framework provides the pipes, but you still need to write the water (your specific tool logic).

---

🚀 Roadmap (Potential Improvements)

The following enhancements are planned to evolve this scaffold into a complete development ecosystem:

🛠️ Infrastructure

• Advanced Error Reporting: A bridge-level mechanism to automatically catch Python exceptions and pipe them into Blender's UI header or a custom popup.
• Visual Async Feedback: Integration between the Service Layer background tasks and the UI Layer to provide visual progress bars or status icons in the N-panel.
• Automated Bridge Generation: A utility to help scaffold new Bridge sub-interfaces based on bpy documentation.

🧩 Feature Modules

• Pre-flight Validation Suite: A standardized way to define and run "Scene Health Checks" before performing operations (e.g., "Are all scales applied?", "Are naming conventions met?").
• Asset Browser Sync: Built-in bridge methods to automatically register/manage assets in Blender's native Asset Browser.
• Metadata Persistence: A service to handle custom property persistence during complex export/import workflows.

---

🛠️ Developer Guide

How to add a new feature:

1. Define the API: If you need a new Blender capability, add an interface to core/bridge.py and implement it in both RealBlenderBridge and MockBlenderBridge.
2. Write the Logic: Create a new method in core/services.py that uses your new bridge method.
3. Create the UI:
   • Add an Operator in ui/operators.py to call the service.
   • Add a Panel entry in ui/panels.py to trigger the operator.
4. Register: Ensure your new classes are added to the OPERATOR_CLASSES or PANEL_CLASSES lists in their respective files.

Running Tests:

# Run tests in a standard python environment (no Blender needed)
pytest tests/