PygameRun

This is the payoff node of ComfyUI-Pymunk. Everything else builds a physics scene; PygameRun is what steps it forward and draws it, returning actual image frames you can turn into a video. It's the node at the end of the author's own example workflow, and it's the one that makes the bouncing-ball GIF on the repo happen.

The pitch behind the whole pack is worth remembering here: simulate a simple game-like scene deterministically, render it, and then use those frames as a guide for AI video generation. PygameRun is the "render it" step - the deterministic, exactly-repeatable half of the plan.

How it works

You hand it your screen (from PygameSurface), your space, a merged list of shapes, and two numbers. Each frame it calls space.step(delta_t) to advance the physics, wipes the surface white, and draws every shape in your list by type:

• Poly (dynamic boxes) draw as green filled polygons
• Segment (static lines) draw as black lines
• Circle draw as red circles

The surface is then converted to a PIL image, normalized to 0–1, and packed into a torch tensor. The output, image, holds every frame - the whole animation comes out of this one wire.

The inputs that matter

• screen - the PygameSurface you created. Its size is the frame size.
• space - your PymunkSpace.
• shape - the merged SHAPE list (PymunkShapeMerge if you have more than one body).
• delta_t - default 0.02. Physics step size; 0.02 is 50 steps per sim-second. Smaller = slower, smoother; large values risk bodies tunneling through thin floors.
• frame_length - default 14. How many frames you get. This is also your animation length, so raise it for longer clips. The bundled example runs 140 frames at a gentle 8fps to make a ~17s loop.

The output gotcha worth knowing

The image output is technically an IMAGE, but it's shaped like [1, frames, height, width, 3] - one big tensor holding every frame, with the frame dimension in an unusual spot rather than the usual ComfyUI [B, H, W, C] layout. Downstream nodes that assume the standard layout can get confused. The pack's own workflow feeds this output straight into VHS_VideoCombine to assemble the mp4, so treat that as the intended consumer. If a random node complains about a weird tensor shape, now you know why.

Also note the background: the node fills the surface white every frame, so there are no motion trails by design. Each frame is a clean snapshot. If you want persistence, that's a feature you'd have to add yourself.

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 after. Dependencies are just pymunk and pygame - no model files, no VRAM cost. This is a small single-author pack with essentially zero web footprint (the launch post on r/StableDiffusion got one lukewarm comment), so you're mostly on your own if something breaks. The flip side is that the entire source is one short file, and PygameRun is readable in a couple of minutes.

Start simple: a floor, one circle, gravity, 14 frames. You'll have your first bounce GIF before you've finished a coffee.