kubakub pieces falloff

Every piece-motion chain in this pack needs one thing in the middle: something that says how much - and when - each stone, window frame or cornice block gets moved. That's this node. It doesn't transform anything. It hands kubakub pieces transform a weight per piece per frame, and the transform does the pushing.

If you've used MOPS in Houdini, this is the falloff channel. If you haven't, here's the mental model: you are a wave, or a band, or a queue, running across a building measured in metres.

Pick a type and you've picked a personality

type has five options and they are genuinely different effects, not presets of each other:

• wave - a front runs across the facade at speed (metres per second) with a soft edge width metres wide, and pieces the front has passed stay moved. This is the "the building just did that" motion in the pack's demos. It's also the one that makes an audience think the geometry changed.
• pulse - a band width metres wide travels across; pieces rise as it arrives and come back down as it leaves. More readable as an animation, less monumental.
• stagger - one piece after the other, in direction order, spaced over spread seconds, each taking duration. hold says how long they sit there before going back (-1 means they never come back). Great for a facade that assembles itself window by window.
• noise - every piece drifts on its own at frequency changes per second. Use it as a subtle life layer under something else, or don't use it at all. Unmodulated noise on architecture reads as a broken model.
• all - every piece fully, the whole time. That's the "I just want the whole facade to move" case, and it's the fastest to render mentally because there's nothing to tune.

The metres thing, and why it matters

speed is in metres per second and width is in metres on the facade - not fractions of the image or seconds. That's deliberate, and it's the best design decision in the node: a 40-metre facade and an 8-metre one get the same physical-looking motion, and the same numbers work whether you swap the model or re-render at a different resolution. It also gives you arithmetic you can do in your head - speed 6 crosses a 40 m facade in under seven seconds.

start is when a wave, pulse or stagger begins, in seconds from the first frame. Negative values are allowed and useful: -2 means the front is already halfway across when frame one arrives, so your shot opens mid-move instead of waiting for it.

spread, duration, hold are stagger's dials. spread is the gap between the first piece starting and the last one starting - 0 is everything at once. loop repeats a wave or pulse every N seconds (0 = once). amount multiplies the falloff and a negative value runs it the other way; invert flips who moves, so the pieces the front reached rest and the rest move. seed only bites on random directions and noise.

Wiring it up

falloff goes into kubakub pieces transform, falloff input. Go from kubakub scene pieces into the transform, and out to kubakub pieces render. You can chain transforms - a wave push, then a stagger scale on top - and they add up, but each needs its own falloff if you want them to run on different rhythms. A pieces transform with nothing connected to falloff moves everything at full strength all the time.

Install

Manager → search kubakub nodes, or:

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

The pip line installs OpenCV and nothing else; the rest of the pack's requirements come with ComfyUI. You do need ComfyUI 0.37.0+ and, for anything in the 3d / pieces group, Blender 4.x on the machine. The nodes still load without Blender - they just fail when they try to render.

Gotchas worth knowing before you spend an evening

This is the node that changed behaviour in 0.3.0. The changelog is blunt about it: start and speed used to do nothing and stagger ignored direction. They work now, which means an old workflow saved with speed 5 and start 0 looks the same, and one with anything else now moves differently. If a graph you downloaded behaves oddly, that's why.

Stagger over too long a spread never finishes. With spread 20 seconds and duration 1 on a 4-second render, the last pieces never move at all. The falloff is evaluated per frame; there's no "catch up".

Piece selection is upstream, not here. If a stone refuses to move, or the whole wall moves when you wanted the windows, the fix is in kubakub scene pieces (min_size_m, max_size_m, keep_largest) or in the regions you connected there. This node can't rescue a bad piece set.

Test it without rendering. The pack ships model-free tests in tests/, and tests/test_pieces.py exercises exactly this motion maths - worth a look if you want to check a hypothesis without waiting on Cycles.