Object Collection Instance Add

This wraps bpy.ops.object.collection_instance_add() - Blender's "Add > Collection Instance" operator. It creates a lightweight Empty object that instances (references, doesn't copy) an existing Collection, so every object inside that Collection shows up wherever you place the instance, without duplicating any geometry.

Where it fits in Avatar Graph

Avatar Graph (avatechai/avatar-graph-comfyui) rigs a flat character image into a real-time interactive avatar - segmentation, mesh layers, a "Shape Flow" runtime graph, exported via Avatar Main Output. The README documents a small set of nodes for that flow; this one isn't in it. It's part of the much larger family the pack generates by exposing Blender's Object operators directly, and it's genuinely useful Blender functionality if you're assembling a scene around your avatar (repeating a prop or background element cheaply), just not something the documented rigging pipeline itself calls for.

How it works

Blender Collections aren't groups of geometry copies - they're references. Instancing one drops a single Empty into the scene whose "job" is to display everything in that Collection at the Empty's transform, live-updating if the Collection's contents change later. It's the cheap way to repeat a set of objects many times without the memory and edit overhead of actually duplicating them.

Inputs and outputs

• collection - a B_ENUM picking which existing Collection to instance.
• name (default "Collection") - the name given to the new instance object.
• location, rotation, scale - where the instance sits.
• align - WORLD, VIEW, or CURSOR, controlling the instance's initial orientation basis.
• session_uuid, drop_x, drop_y - leftover fields from the same underlying operator family used by Blender's drag-and-drop asset placement; safe to leave at their 0 defaults for a manually-wired node.
• BPY_OBJ (optional) - present for consistency with the rest of the family.

Output: BPY_OBJ - the new instance Empty, ready to feed into further Object_* nodes (a constraint, a collection link, and so on).

How to install it

ComfyUI Manager: search "avatar-graph-comfyui", install, restart. Manual clone:

cd ComfyUI/custom_nodes
git clone https://github.com/avatechai/avatar-graph-comfyui
cd avatar-graph-comfyui && python -m pip install -r requirements.txt

The real requirement: bpy needs Python 3.10.x, nothing later. Windows users get a prebuilt Python 3.10 ComfyUI zip from the README; on Mac/Linux, set up a dedicated conda env (conda create --name comfyui python=3.10). Restart with --enable-cors-header if you want the live avatar preview panel to work with editor.avatech.ai - exports don't need it.

Common issues & troubleshooting

Install trouble almost always comes back to Python version - a 3.11/3.12 environment, the default on most current ComfyUI installs, won't load bpy. There's also a real report of Avatar Graph leaving a ComfyUI Desktop install badly broken (an oversized logo, an unexpected audio-permission popup) after install, bad enough that a full reinstall didn't fully clear it - test in a spare, portable ComfyUI instance first if you're not already isolated on 3.10.

For the node itself: if collection doesn't list the Collection you expect, it's almost always because that Collection doesn't exist yet in the current file's data at the point this node runs - a Collection has to already be created (by another node earlier in the graph, or already present in the file) before you can instance it here.