Architecture overview

Blender Development combines IntelliJ Platform extension points with project services and a bundled Python runtime executed inside Blender.

Main surfaces

• The Blender Project generator creates project files through PyCharm’s native Python environment workflow.
• Project Blender Manager edits project-scoped launch and runtime settings.
• Settings > Tools > Blender Development stores application-wide discovery, environment, and logging settings.
• The Blender run configuration starts the external Blender process.
• Runtime actions communicate with an active Debug session.

Service boundaries

Responsibility	Scope
Build commands and launch Blender	Project
Discover Blender installations	Project scan with application-level cached results
Persist launch and runtime settings	Project
Persist global paths and environment variables	Application
Extract runtime resources and clean stale scripts	Project startup

Project state is stored in the project’s .idea configuration. Application state is stored in PyCharm’s configuration area.

State scopes and interface ownership

The state-flow refactor uses three configuration interfaces with distinct lifetimes and ownership:

• PluginConfig is application-scoped. It owns global paths, detected installations, environment defaults, logging, and release-refresh preferences shared by every project.
• ProjectConfig is project-scoped. It owns the active project’s executable selection, source layout, launch arguments, debugger behavior, and project environment.
• BlenderVersionCache is application-scoped cached release metadata. It supplements the built-in compatibility table with patch versions discovered online, rather than acting as another user-editable configuration form.

The following matrix is the ownership contract for UI surfaces. Read and write means the surface may issue mutations through the owning service; read only means it may observe snapshots but must not change that backend.

Surface	PluginConfig	ProjectConfig	BlenderVersionCache
Project Blender Manager	Read detected installations only	Read and write	No direct access
Global Settings	Read and write	No access	Read and write

Project Blender Manager may use application configuration to present detected executable choices, but global paths and installation policy remain owned by Settings. Project-specific executable selection, launch behavior, and source-layout decisions remain owned by Project Blender Manager.

State consumers should receive immutable snapshots. Each backend keeps its mutable IntelliJ persistence representation private, publishes updates through a read-only flow, and accepts changes through explicit mutation functions. UI collectors must use the shortest applicable lifecycle and return to Swing’s event dispatch thread before rendering.

Run and debug lifecycle

1. The run configuration validates the Blender path.
2. The launcher combines project arguments and environment settings.
3. Run mode generates a lightweight refresh script. Debug mode generates a full runtime bootstrap script.
4. PyCharm starts Blender as an external process.
5. In Debug mode, the Blender runtime reports its debugpy endpoint and PyCharm attaches through Python DAP.
6. Runtime commands and optional reload-on-save remain active until Blender exits.
7. The plugin releases session state and removes generated scripts.

Bundled runtime

The build packages the Python sources into blender-runtime.zip. The plugin extracts that archive under the IDE configuration area and refreshes it when the plugin version or archive hash changes.

The runtime provides add-on loading, script execution, reload, stop, logging, and debugger coordination inside Blender. Localhost communication is limited to the lifetime of the active session.