Nodes/Avatar Graph/Object Data Instance Add
ComfyUI Node

Object Data Instance Add

ComfyUI Node Guide

By avatechai·Created 3 years ago·Updated 2 years ago· 264
Object Data Instance Add
  • BPY_OBJ
  • location
  • rotation
  • scale
  • BPY_OBJ
name
session_uuid0
type
align
drop_x0
drop_y0

This one's a power-user node, and it's worth being upfront about that. Object Data Instance Add is part of Avatar Graph, Avatech's pack for rigging character illustrations into interactive real-time avatars in ComfyUI - but this particular node isn't an avatar-specific tool, it's a low-level Blender scene-building primitive that the pack exposes because it wraps a huge chunk of Blender's object-creation API wholesale.

It's a direct wrapper of bpy.ops.object.data_instance_add, which is the operator behind Blender's "Add object from existing data-block" behavior - the same mechanism that fires when you drag an asset from Blender's Asset Browser into your scene, or use certain Add-menu shortcuts that reference already-existing data rather than creating something new from scratch. Instead of generating fresh geometry, it creates a new object that instances a data-block you already have - an existing mesh, armature, camera, collection, image, and so on.

The parameters reflect that low-level origin closely:

  • type - which kind of data-block to instance. This is a big enum (38 options in the schema, covering things like ACTION, ARMATURE, CAMERA, COLLECTION, CURVE, IMAGE, and dozens more) - essentially every ID type Blender tracks internally.
  • name - which specific existing data-block of that type to instance, by name.
  • session_uuid - Blender's internal disambiguation ID, used when two data-blocks share a name and the name alone isn't enough to pick the right one. You'll typically only need this if name collisions are actually happening in your session.
  • location, rotation, scale, align - standard placement for the new object, same as any Add operator.
  • drop_x, drop_y - leftovers from this operator's origin as a drag-and-drop handler in Blender's UI. They don't do anything meaningful in a scripted ComfyUI graph; safe to leave at default.

Output is a new BPY_OBJ referencing the instanced data.

Realistically, most people building an avatar rig won't reach for this node directly - it's the kind of thing more likely used internally by Avatech's own preset templates (instantiating a base rig cage, a reference armature, or similar) than something a beginner wires up by hand. If you're not sure whether you need it, you probably don't; the pack's Create Mesh Layer and Join Meshes nodes cover the actual avatar-building path far more directly.

Installing it: no standalone install - it's bundled with the whole Avatar Graph pack. Easiest is ComfyUI Manager, searching "Avatar Graph" or avatar-graph-comfyui. Manual: cd ComfyUI/custom_nodes, git clone https://github.com/avatechai/avatar-graph-comfyui, cd in, pip install -r requirements.txt, restart.

The install issue that actually gets people: Avatar Graph needs Python 3.10.x, exactly, because its bpy dependency only ships wheels for that version - a newer Python (common on fresh ComfyUI setups) means the install just fails. The README recommends a dedicated environment: conda create --name comfyui python=3.10, activate, install ComfyUI's own requirements first, then this pack's. For the live preview in Avatech's web editor, launch with --enable-cors-header (Mac: add --force-fp16); skip it and everything still runs, you just export .glb/.gltf instead of a live in-browser preview.

Categoryblender

Inputs (10)

NameTypeDefaultDescription
BPY_OBJoptBPY_OBJ
nameoptSTRING
session_uuidoptINT0-2147483648–2147483647
typeoptCOMBO38 options: ACTION, ARMATURE, BRUSH, CACHEFILE, CAMERA, COLLECTION, +32
alignoptCOMBO3 options: WORLD, VIEW, CURSOR
locationoptB_VECTOR3
rotationoptB_VECTOR3
scaleoptB_VECTOR3
drop_xoptINT0-2147483648–2147483647
drop_yoptINT0-2147483648–2147483647

Outputs (1)

NameTypeDescription
BPY_OBJBPY_OBJ