PymunkShapeMerge

Every shape node in this pack - box, circle, static line - outputs exactly one thing, and the run nodes - PymunkRun and PygameRun - accept exactly one SHAPE input. So as soon as you want a floor and a couple of falling balls, you need this node, because it's the only way to hand multiple bodies to the run nodes at once.

It does one thing and does it dead simply: it takes two SHAPE values and concatenates them. That's it. No widgets, no settings, no physics of its own. It's the pack's scene assembler, and it exists purely because of a quirk of how this pack types things.

Why merge is necessary at all

Here's the detail that explains the whole design: in ComfyUI-Pymunk, the SHAPE type isn't a single pymunk shape - it's a Python list of shapes. Each creator node returns a one-element list. PymunkRun and PygameRun iterate over that list, stepping every body and tracking or drawing every shape in it. So a single box works wired straight in, because one-element list is still a list.

But if you connect two box outputs directly into one shape input, ComfyUI will happily pass the second one in and the list handling breaks - the run nodes get a shape where they expected a list. PymunkShapeMerge fixes this: shape1 + shape2 produces one flat list containing both bodies, which is exactly what the run nodes want.

Wiring it

• shape1 and shape2 - the two SHAPE values you want in the scene.
• shape - the merged result, feeding into PymunkRun or PygameRun.

Chain as many as you need. A typical scene is a static line for the floor merged with a circle, then that merged result merged with a box, and so on. The run nodes don't care how many shapes are in the list, only that it's a list.

One subtlety if you're following along in the code: the creators also expose an optional shape input that looks like it should do merging for you - but it's ignored, completely dead weight. Don't reach for it; this node is the only real way to combine.

Installing the pack

This node ships with chaojie/ComfyUI-Pymunk. Install via ComfyUI Manager (search "ComfyUI-Pymunk") and restart, or:

cd ComfyUI/custom_nodes
git clone https://github.com/chaojie/ComfyUI-Pymunk
cd ComfyUI-Pymunk && pip install -r requirements.txt

Restart afterwards. Dependencies are just pymunk and pygame; no model downloads, no GPU requirements. It's a small single-author pack with essentially no community footprint, so expect to debug solo - the upside is the source is one short file, and this node in particular is about four lines of it.

If your run node silently ignores half your shapes or errors on a "non-iterable," you've almost certainly missed a merge. When in doubt, merge.