PymunkRun

PymunkRun is the other way to get your simulation out of the space - and it's the one that's actually interesting if you're not just making bounce GIFs. Instead of rendering frames, it runs the physics and hands you the coordinates of every shape, every step, as JSON. If you want trajectories to drive something downstream - ControlNet conditioning, a mask that follows a ball, keyframes for an AnimateDiff-style video pipeline - this is the node to reach for.

This is also the half of the pack that doesn't care about pygame at all. No surface, no rendering, just numbers. Cleaner to debug, cheaper to run.

What it does, mechanically

You give it your space, a merged list of shapes, and two numbers, and it loops frame_length times. Each pass it calls space.step(delta_t) to advance the simulation, then records the current position of every shape's body. Positions get clamped to [0, width-1] by [0, height-1] so nothing wanders off the logical frame. The output is a JSON-encoded string.

tracking_points decodes to a list with one entry per shape, and each entry is a list of frame_length [x, y] pairs - effectively each shape's trajectory over the run, in the order you merged them. Parse that string in whatever consumes it and you've got real motion data.

The inputs that matter

• space - your PymunkSpace.
• shape - the SHAPE list (use PymunkShapeMerge if you have more than one body).
• delta_t - default 0.02. The size of each physics step. 0.02 means 50 simulation steps per second of sim-time. Smaller = slower, more precise motion; larger = faster, jankier steps that can tunnel through thin floors.
• frame_length - default 14. How many steps (and therefore trajectory points) you get. Bump it up to animate longer; just know every shape in your list accumulates a point per frame, so big scenes × long runs produce chunky JSON.
• width, height - default 576, 320. The coordinate clamp bounds, and nothing more - this node draws nothing. Keep them consistent with your PygameSurface if you later switch to rendering.

Wiring and a warning

The output is a STRING, not an image. Don't drag a PreviewImage onto it and wonder why there's nothing to see - feed it to a node that consumes text or JSON, or use it inside a custom pipeline. The output type mismatch catches people out more than anything else in this pack.

Installing the pack

Part of 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 models, no GPU load. Like the rest of the pack it's a small single-author project with no real community footprint, so the node docs you're reading are the docs you get. The good news: the trajectory data this node emits is plain and parseable, which makes it the friendliest output in the pack to build on.