Blender Scripting Assistant

Purpose

This Blender add-on provides a suite of tools that makes it easier for developers and artists to easily create other Blender add-ons.

Key Features

• A debugging server to connect Blender to external code editors (such as VS Code)
• A hot swap system that monitors files and folders for changes and immediately reloads the modified module into Blender

Long Term Goal

I want to build this project into the defacto tool for Blender add-on developers to use while making and debugging their own scripts and add-ons.

Ultimately, I aim to have this project included as a community add-on bundled with a future Blender release version.

History

This add-on is a diverging fork from Alan North's Blender Debugger for VS Code v2.2.0. This project expanded beyond Alan's original intent and desire to maintain. I owe many thanks to him for all of his hard work getting the debugging code working after reviewing this Blender Developer's blog post about connecting to PyCharm.

Getting Started

Overview

To use this add-on in your workflow, you require the following installed on your computer:

1. The minimum supported Blender release or later
2. Python 3.10 or later, with PIP

Suggested Additions:

1. The external code editor Visual Studio Code
2. The Python Extension for VS Code
3. The fake-bpy-module package installed by PIP

Installing Python and Getting Debugpy

Install Python 3 with PIP and check add to PATH.

• If you already have python installed and you can run it from the command line (aka PATH is set), the addon should find it. It checks where python or whereis python or which python to try and determine where python is and uses the first path given².

• If you are using something like Conda and want to use a virtual environment, to have the addon auto-detect the path you can: activate the environment, run Blender from the command line, and it should work.

   pip install debugpy
  

• For Visual Studio, the debugpy version that works depends on the Visual Studio version. I have never used Visual Studio, but you can find more info on setting everything up here: Remotely Debugging Python Code on Linux. (it is not Linux specific)

Setting up this Addon

Install the addon by downloading the latest release.

Then, open the Blender Preferences (Edit -> Preferences, or hotkey CTRL + ,). Navigate to the Add-ons tab, and click the "Install..." button.

Navigate to the location you saved the released .zip file in. Then, click the "Install Add-on" button.

Configuring the Scripting Assistant Addon

After installing, if it did not find the path it will say "debugpy not found". You will have to set this path manually. It's wherever Python is + "\lib\site-packages". NO trailing backslash.

If you want, increase the timeout for the confirmation. It'll print "Waiting..." in the console every second until it prints it's timedout. This does not mean the server has timed out just the confirmation listener.

Note: you can only start the server once. You cannot stop it, at least from what I understand. If you run it again it'll just tell you it's already running and start the timer again to check for a confirmation.

Connecting the Editor

Open your addon folder (e.g. "C:\Code\Blender Stuff\addons\myaddon").

Install the Python extension for VS Code if you haven't already. For Visual Studio see Installing Python Support.

In the lower left, VS Code should have auto detected your Python install and set it as the interpreter. For Visual Studio see Managing Python Environments.

Go to the Debugging tab and add a configuration. Pick Python. You'll want the configuration that looks like this, no need to change the defaults, you can delete the rest.

{
	"name": "Python: Attach",
	"type": "python",
	"request": "attach",
	"port": 5678,
	"host": "localhost"
}

Now when you run the debugger with this config in Blender and VS Code the console should print "Debugger is Attached" if it was still waiting (it should still attach even if it wasn't, it just won't tell you).

How to Use

At this point you should be able to add a breakpoint and when you trigger it in Blender, Blender should freeze and VS Code should pause on the breakpoint.

After enabling the add-on, you can control the options by using the new "Scripting Assistant" tab in the viewport's N-panel.

Press Toggle Terminal to see the output messages.

Start the debug server by pressing "Start Debug Server".

Start or stop monitoring by pressing "Start/Stop Monitoring".

Adjust the settings for these in the drop down menus.

Advanced Usage

Wait for Client

The debugger can be made to wait for a client to connect (this will pause all execution). This can be useful for debugging the connection or when running blender headless / in background mode.

To do so, call the server connect command from the python console or from a script/addon like so:

bpy.ops.debug.connect_debugger_vscode(waitForClient=True)

Running in Headless Mode

First make sure the addon is installed, enabled, and works when you run blender normally.

Blender can then be run in background mode with the -b/--background switch (e.g. blender --background, blender --background --python your_script.py).

See Blender Command Line.

You can detect when blender is run in background/headless mode and make the debugger pause and wait for a connection in your script/addon:

if bpy.app.background:
	bpy.ops.debug.connect_debugger_vscode(waitForClient=True)

This will wait for a connection to be made to the debugging server. Once this is established, the script will continue executing and VSCode should pause on breakpoints that have been triggered.

For addons, you will need to do this from a handler:

from bpy.app.handlers import persistent
#...
def register():
   bpy.app.handlers.load_post.append(load_handler)
#...
@persistent
def load_handler(dummy):
	# remove handler so it only runs once
   bpy.app.handlers.load_post.remove(load_handler)
   if bpy.app.background:
      bpy.ops.debug.connect_debugger_vscode(waitForClient=True)

See Application Handlers

Debugging/Editing Source Code

It is possible to edit the Blender source code but it can be a bit tricky to get it to detect changes (nevermind live editing is buggy anyways).

From blender you can right click just about anything and click "Edit Source" to get it in the text editor. Then to find the path of the file, go to Text > Save As and copy it from there.

Open the file in VS Code, connect to the debugging server, make a change and save it.

Now in Blender the text editor will show this little red button in the top left. Click that and reload the file. Then in Text Editor > Properties turn on Live Edit if you haven't already. Now to actually get Blender to detect any changes you made just type a single character (like add a space anywhere) and then it will detect your changes.

Debugging/Editing Scripts

To use breakpoints and debug, you must open the script where Blender installed it to.

C:\Users\<user name>\AppData\Roaming\Blender Foundation\Blender\<version>\scripts\addons

Troubleshooting

• Check you installed the correct debugpy version. With VS Code this should no longer be an issue, but I believe different versions of Visual Studio need different versions of debugpy (see Installing Python Support).
• To determine whether the problem is on Blender's side or your editor's: Close Blender and the testdebugpy test script.

python testdebugpy.py

Then, try to connect to the server with your editor. If you're still getting problems then the problem is with VS Code. Try:

• Check your detected your Python install, or set it manually.
• For VS Code try reinstalling the VS Code Python extension.
• Check that VS Code's Python extension is running on the same port in launch.json as the debug server port in Blender.

Otherwise, if none of that helped, don't hesitate to file an issue.

Support Policy

This add-on is maintained and supported. Submit a bug report if you encounter errors.

Tested

Help Wanted

This add-on should work on MacOS and Linux, but help is required to verify.

Needs verification on Blender 4.1.

License and Development

To help as many fellow artists and developers as possible, Blender Scripting Assistant and all other files in this repository are distributed as free and open-source software under the GPL v3.0 License, © 2022.

Both contributions and bug reports welcome.

If you find this project useful, please leave a 🌟 and subscribe to the Graphic Art Quest YouTube channel for more tutorials and 3D art adventures!

Contact

Maintained by M. Scott Lassiter.