PymunkSpace

If you want to bounce boxes and circles around inside ComfyUI, this is the node you drop first. PymunkSpace doesn't draw anything, render anything, or do anything exciting on its own - it just creates the world that everything else in the pack lives in. In pymunk terms that world is called a Space: it's the object that owns every body and shape, applies gravity, and resolves collisions when you tell it to step forward in time. No space, no simulation.

It's the least glamorous node in the pack and also the mandatory one. Every shape creator and both run nodes take its space output as an input, so your graph always has exactly one of these at the top feeding everything below. Think of it as the empty room before you add the floor, the walls, and the stuff that falls.

What the two knobs actually do

There are only two inputs, and they're the entire physics setup:

• xgravity - horizontal gravity, default 0.
• ygravity - vertical gravity, default 9.8.

They combine into the gravity vector applied to every dynamic body in the space. Here's the subtle bit worth internalizing: pymunk's math convention has y pointing up, but the pack's render nodes draw bodies at their raw coordinates on a pygame surface, where y grows downward on screen. Net effect: a positive ygravity looks like perfectly normal "things fall down" gravity. Leave both at their defaults and you get a gentle, floaty fall. Crank ygravity up toward 980 - which is what the bundled example workflow uses - and you get a snappy, video-game drop.

Wiring it

The single output, space, is the only wire you need. Send it into PymunkStaticLine to lay down a floor, into PymunkDynamicBox or PymunkDynamicCircle to drop bodies into the world, and finally into PymunkRun or PygameRun to step the whole thing forward. The order you connect things doesn't matter - gravity is just a property of the space, so everything added to it feels the same pull.

Installing the pack

This node ships with chaojie/ComfyUI-Pymunk, a small, obscure pack that does 2D rigid-body physics inside ComfyUI. The author's own pitch for it, from the launch post on r/StableDiffusion, is worth knowing: simulate a simple game-like scene deterministically first, then use that as the guide for AI video generation. Install it the usual way:

• ComfyUI Manager: search for "ComfyUI-Pymunk" and hit Install, then restart ComfyUI. Manager will read the pack's requirements.txt and pip-install its only two dependencies, pymunk and pygame.
• By hand:

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

  Then restart ComfyUI.

There are no model files to download and nothing GPU-heavy involved - this is one of the lightest custom nodes you'll ever install. Just don't expect much community support; the pack has essentially zero footprint, so if it breaks, the fix is usually on you.

Where people stumble with this specific node: nothing, really. It's two floats and a wire. The actual traps live downstream - in how you merge shapes and what you do with the run nodes' output - so go make a floor first.