Object Face Map Add

Object Face Map Add is the first step in a small family of nodes this pack ships for working with Blender's face maps - a named grouping of faces on a mesh, like a playlist you can add tracks to later. This node creates the (empty) playlist. It doesn't put anything in it.

How it works

It wraps bpy.ops.object.face_map_add(), which appends a new, empty face map to the object's list - visible in Blender's Object Data properties under Face Maps. Unlike the rest of this family (Object_FaceMapAssign, Object_FaceMapSelect, Object_FaceMapDeselect, Object_FaceMapRemoveFrom), which all require Edit Mode because they act on the current face selection, this one works in Object Mode too - it's just appending an entry to a list, not touching mesh selection state.

Worth knowing regardless of what you're building: face maps are an older Blender feature, later superseded by the general attribute system in newer Blender versions. If any node in this family throws an error about a missing face-map API, that's a bpy version mismatch, not a mistake in your graph.

The inputs and outputs that matter

There's exactly one input:

• BPY_OBJ - the object to add a new, empty face map to.

Output is a single BPY_OBJ, the same object with one more face map in its list.

How to install it

ComfyUI Manager: search "Avatar Graph", install, restart - or manually:

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

bpy is pinned to Python 3.10.x, no exceptions. Windows gets a prebuilt Python-3.10 ComfyUI zip from the README; macOS/Linux wants a dedicated conda create --name comfyui python=3.10 rather than an existing newer-Python setup. Add --enable-cors-header on restart (--force-fp16 too on Mac) for the live avatar preview; without it you still get full functionality via .glb/.gltf export.

Common issues & troubleshooting

Node not loading traces to the Python-version pin - check ComfyUI's startup console for a bpy import error before looking elsewhere.

Added a face map, but no faces are in it - that's correct, not broken. This node only creates the empty grouping; putting faces into it is the job of Object_FaceMapAssign, run afterward (in Edit Mode, with the faces you want selected).

Multiple calls, more maps than you expected - this node has no "already exists" check, so calling it repeatedly just keeps appending new, distinct empty face maps rather than reusing one. If you only meant to create one, make sure this node only runs once per object in your graph rather than once per pass through a loop.

If you're building a pipeline that depends on face maps for anything meaningful, it's worth confirming early - on a throwaway test object - that these operations behave as expected in your specific bpy build, before wiring several downstream nodes around the assumption that they exist.