Modify Shape Key

Of the twenty-odd raw Blender mesh operators this pack exposes, this is the one that's actually the point. Avatar Graph exists to turn a single character image into a real-time interactive avatar - something that blinks, breathes, and moves its mouth when you talk - and shape keys are the mechanism that makes that possible. This node is how you sculpt one, by name, without touching Blender's UI at all.

What it is and why you'd reach for it

A shape key is Blender's term for a named, blendable deformation of a mesh - 0% is the base shape, 100% is fully deformed, and you can drive that percentage from code or, in this pack's case, from a runtime "Shape Flow" graph that listens for things like eye-blink timing or lipsync audio. Avatech's whole real-time avatar demo - people animating a pixel-art sprite or a doodled character so it blinks and talks, which is exactly the kind of clip that showed up on r/StableDiffusion when this pack was new - runs on shape keys built this way. This node is the one documented in the pack's own README (as "Mesh Modify Shape Key"): give it a shape key name and a vertex group, and it nudges that group's vertices by a transform.

How it works

Rather than making you hand-sculpt every vertex, it applies a proportional, localized transform - scale, offset, rotation - around an adjustable origin, with a radius and falloff controlling how far the effect bleeds outward. Think of it as Blender's proportional-editing brush baked into a repeatable, named operation: pick a region (via a vertex group), nudge it, and the falloff blends the edit into the surrounding mesh instead of leaving a hard boundary.

The inputs and outputs that matter

This is the one node in the batch with a real parameter list, and every field maps to something you'd actually want to control:

• shape_key_name (default "EyeBlinkLeft") - the name of the shape key you're creating or editing. The default hints at the pack's bread-and-butter use case: rigging eye blinks and mouth shapes for lipsync.
• target_vertex_group - which named group of vertices this edit applies to (an eyelid, a lip, whatever you painted upstream).
• scale_x/scale_y, offset_x/offset_y, rotate - the actual deformation: squash, slide, or rotate the target region.
• origin_offset_x/origin_offset_y - moves the pivot the transform happens around, independent of the group itself.
• transform_radius (0–1) and falloff - how large the affected zone is and how softly it blends into untouched mesh around it.

It outputs a single BPY_OBJ - the mesh with the new or updated shape key baked in, ready to chain into another Mesh_ModifyShapeKey call for the next shape key, or downstream into Create Shape Flow / Avatar Main Output.

How to install it

ComfyUI Manager: search Avatar Graph, install, restart. By hand:

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

Python has to be 3.10.x exactly - the pack depends on bpy (Blender-as-a-package), which only publishes wheels for specific minor versions, and the README calls this out directly. Windows users get a dedicated embedded-Python-3.10 zip to avoid the mismatch; on Mac/Linux, use a pinned conda env. Launch with --enable-cors-header (plus --force-fp16 on Mac) to get the live avatar preview in the corner of ComfyUI, which is genuinely worth having while you're tuning shape keys - you want to see the blink happen, not just trust the numbers.

Common issues

Nothing happens visually: double-check target_vertex_group actually exists on the mesh you're feeding in - this node modifies an existing group, it doesn't create one for you. Weird pinching instead of a smooth blink: transform_radius and falloff are fighting each other - a small radius with aggressive falloff gives you a hard, unnatural crease; widen the radius or soften the falloff. And if the install itself won't go through, it's almost always the Python-version mismatch, not a broken dependency - verify python --version says 3.10 before you chase anything else.