PymunkDynamicBox

PymunkDynamicBox is where the physics actually happens. Unlike the static line, a dynamic body is fully under gravity's control: it falls, gains speed, bounces off whatever it hits, and collides with other dynamic bodies. If you're building a falling-crates scene or a stacking game visual, this is the node.

It's one of two ways to make a dynamic shape in this pack - the other being PymunkDynamicCircle. Box vs. circle mostly changes the collision character: boxes land flat and stack, circles roll. Pick by what your scene needs.

The inputs that matter

• space - your PymunkSpace. Everything dynamic needs one.
• x, y - the starting position of the box's center, in pixels. Set y low if you want it to start high on screen.
• width, height - the box dimensions, default 10 each.
• radius - default 1. This is not a physics object. It's passed to pymunk as the corner radius of the box, so 1 means "slightly rounded corners." Crank it up and you get a squircle, but collisions still use the full box.
• mass - default 1. Heavier boxes push lighter ones around and resist being shoved. Pymunk handles the math for you: when you set the shape's mass, the body's mass and moment of inertia update automatically, so you never manage inertia by hand.
• elasticity - default 1, i.e. a perfectly bouncy box. For a crate that thuds rather than pings, drop it toward 0.1–0.3.

The optional shape input is decorative - the node accepts it and never reads it. Ignore it.

How it works and what comes out

Under the hood: a fresh pymunk.Body() gets positioned at (x, y), a box polygon is built around it with Poly.create_box, and the shape's mass and elasticity are set before both are added to the space. The output, box, is a SHAPE value - in this pack that means a one-element list of pymunk shapes, which the run nodes are built to consume. In PygameRun, box shapes render as green polygons, so you'll see your crates in green.

Two practical notes. First, nothing moves until a run node steps the space, so a bare DynamicBox wired nowhere is just a sleeping crate. Second, remember the coordinate convention: y grows downward on screen, so a positive ygravity in your PymunkSpace makes the box fall down the frame - exactly what you'd expect, and a small mercy given how much else in ComfyUI fights convention.

Installing the pack

This node is 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 afterwards. Dependencies are just pymunk and pygame; no models, no GPU demands. This pack is a small single-author project with essentially no community footprint, so the troubleshooting is mostly on you - but the source file is short enough to read top to bottom in a minute if something misbehaves.

The most common beginner stumble: multiple boxes you want in one scene, feeding each one's box output separately into a run node. That doesn't work - the run nodes take a single SHAPE input. You need PymunkShapeMerge to chain them into one list first. Go read that node before you add a second crate.