PymunkDynamicCircle

A dynamic circle is the workhorse of this pack, and honestly the most fun node in it. Drop one into a space with gravity and a static line underneath and you get exactly what you're picturing: a ball that falls, bounces, and rolls. The example GIF on the repo is basically this node doing its thing, and it's still the most reliable demo of why the pack exists.

It's the round sibling of PymunkDynamicBox. Boxes stack and thud; circles roll and bounce. For anything where you want smooth motion and no corners, this is the node you reach for.

The inputs that matter

• space - your PymunkSpace, required.
• x, y - the ball's starting position in pixels. Screen y grows downward, so a low y value starts it high in the frame.
• radius - default 1. Here it's a real physics radius, not a corner radius like the box node. Set it to something that reads visually on your frame - on the default 576×320 canvas, a radius of 10–20 is a decent ball, not a speck.
• mass - default 1. Matters when two dynamic bodies collide: heavier balls keep their momentum and shove lighter ones. Setting it also updates the body's moment of inertia for you, so you never touch that math.
• elasticity - default 1, a perfectly elastic bounce. This is the single most fun knob in the pack. 1.0 with a bouncy floor gives that happy, never-ending ping-pong energy; drop to 0.2 and the ball thuds to a stop.

The optional shape input, same as on the other shape creators, is accepted and completely ignored by the code. Leave it unplugged.

How it works and what comes out

The node creates a pymunk.Body(), positions it, wraps a Circle shape around it, sets mass and elasticity, and adds both to the space. The output, circle, is a SHAPE value - a one-element list of pymunk shapes, which is what the run nodes are designed to receive. In PygameRun, circles render as red, so your balls come out red on the white background.

And remember: nothing moves until a run node steps the space. A lone circle is a frozen ball until you feed it into PymunkRun or PygameRun.

Installing the pack

Part of chaojie/ComfyUI-Pymunk. Install through 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 after. Only dependencies are pymunk and pygame - no models, no VRAM cost, one of the lightest packs you'll install. It's a tiny single-author project with basically no web presence, so don't expect a support community; the whole source is one readable file if you ever need to check what a node actually does.

The one trap worth naming: with the default radius of 1 and a small frame, your "ball" can be smaller than the line thickness you gave your floor, and the collision math gets fiddly. Give your balls a real radius and your floors a real thickness, and things just work.