The online
bouncing ball simulator

The physics part of a bouncing ball simulator is not difficult. Reflecting a velocity vector off a surface and applying a constant downward acceleration covers most of it, and a competent developer can build that in an afternoon. This is why there are so many free bouncing ball demos online and why almost none of them are useful for making video.

The hard part is control. A clip that holds attention needs the run to change over its duration, needs the collisions to line up with audio, and needs to end at a definite moment rather than trailing off. Those requirements are what separate a simulator you can publish from a simulator you can watch.

That is the gap this tool is built to close. Gravity and bounciness are exposed because they set the character of the motion, but so are speed build-up rate, population ceilings, size growth curves and note mapping, because those are what determine whether a finished export is worth uploading.

These two settings interact more than any other pair. Bounciness is restitution, the fraction of speed retained through a collision. At exactly 1.0 a ball returns to the same height every time. Below that it settles toward the floor of the container. Above it, the ball gains energy on every contact and the run accelerates without you setting any speed values at all.

Gravity determines how quickly the ball returns to a surface, which sets the collision rate. High gravity with low bounciness gives a fast, tight, percussive run. Low gravity with high bounciness gives long floating arcs with widely spaced impacts. If you are syncing to music, the collision rate is effectively your tempo, so it is worth setting gravity before you attach the audio.

A practical starting point for a music-synced run is gravity near the middle of its range with bounciness just under 1.0, then raising bounce randomness slightly so repeated impacts do not settle into an obvious repeating pattern.

Accumulate runs are the format most associated with bouncing ball video, and the instinct is to push the count as high as it goes. Max balls tops out at 500, and in a small arena the frame stops reading as individual balls well before that. Past that point you are rendering texture, and the viewer loses the thing that made the format interesting, which is watching a countable number of balls become an uncountable one.

Max balls and Wait between new balls are the two controls that shape this. The cap sets where the run plateaus, and the wait sets how fast it gets there, so the interesting middle section gets its full share of the clip. Setting both deliberately is usually the difference between a run that builds and a run that simply fills.