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 plugin uses three configuration interfaces with distinct lifetimes:

• PluginConfig is application-scoped and owns global paths, detected installations, environment defaults, logging, and release-refresh preferences.
• ProjectConfig is project-scoped and owns executable selection, source layout, launch arguments, debugger behavior, and project environment.
• BlenderVersionCache stores application-scoped release metadata that supplements the built-in compatibility table.

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

State consumers 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.

Run and debug lifecycle

1. The run configuration validates the Blender path.
2. The launcher combines project arguments and environment settings.
3. Run generates a lightweight refresh script; Debug generates a full runtime bootstrap script.
4. PyCharm starts Blender as an external process.
5. In Debug, 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 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 active session.