kubakub scene pieces

If you've used Houdini's MOPS, you know the shape of this: take a set of loose parts, drive transforms across them with a wave, a pulse, a stagger or the kick drum, render the result. This is the same idea built in ComfyUI on top of a 3D facade, and kubakub scene pieces is step one - it decides which parts of the model are allowed to move.

The reason it's a separate node is that "which parts" is the interesting question. A stone that stands proud of the wall can jump out and read as relief. The wall panel it's stuck to can't - push that and the building falls over. So this node measures every loose part of the model, sorts them by size, and hands you the ones in the window you asked for.

The inputs

scene comes from kubakub scene render and carries the model, the camera and the passes. Nothing works without it.

min_size_m (default 0.2) is the floor, measured as the diagonal of the part's bounding box in metres. Anything smaller stays still - the crowd can't read it anyway, and you save render time. Raise it to 0.5 and you're moving window frames and cornice blocks; lower it to 0.15 and individual stones start participating.

max_size_m (default 0, meaning no limit) is the ceiling. Set it when you want to protect whole wall panels from being flung around.

keep_largest (default on) keeps the biggest part still - in practice, that's the wall the stones sit on. Turn it off only if your model is built so that the biggest part should move.

Then there's the region-aware half, and this is what makes it feel like a tool rather than a filter. Connect regions (from kubakub regions from id maps, masks, a cryptomatte - anything that gives you named regions on the projection view) and every part gets assigned to the region most of it falls inside. source then decides which unit moves:

• loose parts - the default. Each loose part moves on its own.
• regions: one piece each - every region moves as one block. A floor, a bay, all the windows, in one go.
• regions: parts inside - only the parts inside the regions you select move, and each still moves individually.

selection is where you say which ones, in the pack's normal selector syntax: region names, group:windows, tag:left, or a comma-separated list. Empty means everything. So "all the windows move as blocks, the wall stays" is a one-line string, not a rebuild.

Outputs

pieces is the thing you chain from - into kubakub pieces falloff (wave, pulse, stagger, noise, and kubakub pieces beat falloff for the director's timeline), then kubakub pieces transform to push, tilt, turn, roll, scale or jitter them, then kubakub pieces render to get frames. Several transforms chain and add up.

preview shows every piece in its own colour with the still parts grey. Look at this before you render anything: if the wall has an unexpected yellow highlight across it, your size window caught something it shouldn't. mask is 1 on the movable pieces at the scene's size - useful as a scope for other nodes, and for checking that your selection did what you meant. report gives counts, the size range in metres and the facade's dimensions.

Install and requirements

Part of the pack:

cd ComfyUI/custom_nodes && git clone https://github.com/kubakubkub/ComfyUI_KubaNodes
python -m pip install -r ComfyUI_KubaNodes/requirements.txt

Everything under 3d / pieces needs Blender 4.x on the machine, because the movement is computed in numpy but the vertices are moved and rendered by Blender. The pack keeps one Blender worker process alive between jobs by default (blender_idle = 600 seconds), so a chain of piece renders doesn't pay the startup cost each time. If you'd rather it didn't, blender_worker = off in kubakub.ini.

The sample model is ideal for learning this. Its ~640 loose parts are exactly the stones-and-frames structure the node expects, and template 08_moving_pieces runs a band across the facade with no AI model anywhere in the graph.

Traps

The big one is a scene that has few or no loose parts. If your model is one welded mesh - a sculpt, a scan, a boolean-ed Blender export - then everything is one piece and this node has nothing to give you. You'll see it in the preview: uniform grey. The fix is upstream in Blender (separate the objects you want to move), not here.

Second: the size numbers are metres, and they're only as real as your model's units. Get unit_scale right on scene render first, or your 0.2 m floor becomes a 20 m floor and every stone gets filtered out.

Third, more of an expectation than a bug: pieces move as rigid parts. There's no deformation, no bending, no soft-body. It's MOPS, not a simulation. Which is fine - the effect that lands on a facade is a wave of stones stepping out of the wall, and that's exactly what this gives you.