PygameSurface

PygameSurface is the pack's blank canvas. Give it a width and height and it returns a pygame surface - the thing PygameRun later draws your physics shapes onto, frame by frame. That's the entire job. In a pack full of bouncing bodies this is the node that provides the stage, and you can't render anything without it.

Note the boundary: this node only matters on the rendered path. If your workflow uses PygameRun to get actual images out, you need a PygameSurface wired into it. If you're instead using PymunkRun to extract raw trajectory coordinates and don't care about pixels, skip this node entirely - you'll never touch pygame.

The two inputs and what they're for

• width - default 576.
• height - default 320.

That's it. When the node runs, it calls pygame.init() and creates a blank pygame.Surface of that size. It does not fill the surface with anything - the commented-out screen.fill in the source shows the background was originally white, but these days PygameRun paints the background itself on every frame. So don't look for a background color setting here; there isn't one.

The one real gotcha is matching dimensions. PygameRun renders every frame at whatever size its screen input is, and PymunkRun clamps tracked coordinates against its own separate width/height inputs. The defaults happen to agree - both are 576×320 - and you should keep them that way. If your surface is smaller than the coordinate clamp box, shapes will appear to push against the edges of the frame; if it's bigger, you'll have a frame with nothing in it.

Wiring and install

The single output, screen, plugs directly into PygameRun. That's the only consumer in the pack, so the graph is as simple as it gets: PygameSurface → PygameRun, alongside your space and your merged shapes.

The node comes with the rest of chaojie/ComfyUI-Pymunk. Install the pack through ComfyUI Manager (search "ComfyUI-Pymunk") or:

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

Restart ComfyUI after installing. Dependencies are just pymunk and pygame - no model downloads, no VRAM worries, nothing heavy. pygame does ship compiled wheels, so on a clean environment Manager should pull it without complaint; if you're on an exotic Python build that's the one step that can hiccup, and pip install pygame into ComfyUI's Python environment fixes it.

Honestly, this is the node you'll think about the least. It exists to make PygameRun work. Set the size once, wire it once, and forget it.