https://github.com/IRCSS/comfyUI-blender-wrapper
a simple generic wrapper to call blend files and python scripts as a node in comfyUI
https://github.com/IRCSS/comfyUI-blender-wrapper
Last synced: about 2 months ago
JSON representation
a simple generic wrapper to call blend files and python scripts as a node in comfyUI
- Host: GitHub
- URL: https://github.com/IRCSS/comfyUI-blender-wrapper
- Owner: IRCSS
- License: mit
- Created: 2025-10-18T13:37:55.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-11-26T11:10:18.000Z (4 months ago)
- Last Synced: 2025-11-28T10:17:00.227Z (4 months ago)
- Language: Python
- Size: 25.5 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-comfyui - **comfyUI-blender-wrapper** - art / asset-pipeline tasks like cleanup, decimation, unwrap, baking, rigging, etc. (Workflows (3998) sorted by GitHub Stars)
README
# ComfyUI Blender Wrapper
**ComfyUI Blender Wrapper** lets you call Blender in headless mode from ComfyUI (or any Python environment), run reusable pipeline stages stored inside `.blend` files, and pass configs in/out via JSON. It’s meant for tech-art / asset-pipeline tasks like cleanup, decimation, unwrap, baking, rigging, etc.
## What this repo gives you
- A **generic `wrapper.py`** that:
- reads env vars from a caller,
- imports input assets into Blender,
- loads a `.blend` stage file,
- executes scripts stored as **Text blocks** inside that `.blend`,
- returns results via JSON.
- A **ComfyUI node** example showing how to call the wrapper.
- Example stage `.blend` files (e.g., mesh cleanup, simple rig, etc.) you can copy and modify.
- Some modifications to Kijai's Hunyuan wrapper, so that it plays nicely with my example of batch processing meshes (dealing with Windows Path issues and generations colliding with eachother in terms of file read write permissions)
## Why this exists
Blender already has a ridiculous amount of built-in functionality (mesh ops, baking, UVs, geo nodes, rigging, rendering…). Instead of re-implementing pipelines in your engine or custom tools, you can:
**Caller → Blender headless → wrapper.py → stage.blend scripts**
Write the actual stage logic once (inside a `.blend`), reuse it anywhere.
## Requirements
- Tested on Blender 4.5, but should work on most
- Python 3.9+ (same environment as ComfyUI if you use the node)
## Installation
1. Clone this repo in your Comfy Custome Nodes folder.
2. Make sure Blender is installed and set the path to the exe file in the blender_tools_config.json. Alternatively you can modify my code to get the path from system env variables and set it there.
3. Restart ComfyUI
## How to use it
You can call the generic wrapper like this:
Blend file is the path to whatever blend file should be used to run the stage, Input model is path to the model the wrapper imports for blender to act on, config file is a path to a json file that holds a dic of balancing paramters. This is only if your pipeline stage blend file needs it, if not you can leave it empty. Whether the stage needs it is up to whoever implements the code in the blend file. FBX path is where the model is exported once blender is done and the output config is a way to allow the person implementing the pipeline stage to talk up to the next node in comfy.
For more in depth explaination of how everything works, read this post: https://medium.com/@shahriyarshahrabi/blender-as-a-pipeline-engine-make-rigged-characters-with-comfyui-3a1e81a3e623
## How to write your own stage
If you are interested in writing your stage, you can look at the mesh clean up blend file and simple rig file I provided as examples in the repo. Here is all you need to know:
1. Best would be to have one python text file in the Blend file named Main
2. The wrapper will import whatever is passed on to it in a collection called INPUT. In your Python code you can get all the objects in that collection to know what mesh to act on
3. The wrapper has passed down some info for you from Comfy. The important ones are input_model (path to the model imported, in case you want to export something next to it), blend_file, path to the blend file being called, and config itself. To get access to these properties, your blend file you need to do:
``` blend_file = globals().get("blend_file", None) ```
The config itself is already loaded into a Blender friendly dic. To accesss what is inside you can easily do:
```
if config and isinstance(config, dict):
if "decimate_ratio" in config:
try:
DECIMATE_RATIO = float(config["decimate_ratio"])
log(f"Decimate ratio overridden by config: {DECIMATE_RATIO}")
except Exception as e:
log(f"Warning: invalid decimate_ratio in config ({config['decimate_ratio']}): {e}")
```
You can also get a reference to output json and populate it like this:
``` OUTPUT_JSON = os.getenv("OUTPUT_JSON") ```
For how your json should look like have a look at the example.
## On the Example Provided
The example provided is for generating 3D rigged characters. You can read the blog post for more info. I did modify Kijais wrapper to play nicely with very annoying windows issues. The changes are in the files ```ComfyUI-Hunyuan3DWrapper\nodes.py``` and ``ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\postprocessors.py``. You will find both files included here, you can copy them over if you are hitting issues with permission for read and write. License wise all rights go to Kijai.