BallpitEffect

Source: BallpitEffect.h

BallpitEffect

class BallpitEffect

src/light/effects/BallpitEffect.h:31

Inherits: EffectBase

Effect: falling balls that pile up and push each other aside.

The half of the particle kernel Fireworks leaves untouched, since sparks never notice each other. Here the balls rest on the floor, stack, and shove the pile aside rather than passing through.

Prior art: the WLED Particle System's ballpit family, where the impulse response is the kernel's.

Public Attributes

uint8_t balls = 30 : How many balls share the pit.

uint8_t gravity = 8 : How hard they fall.

uint8_t size = 2 : The contact radius, which is how far apart two balls sit when touching.

uint8_t bounce = 120 : Restitution: how much speed a contact keeps.

uint8_t tilt = 0 : A sideways force, which turns the pit into a slope.

uint8_t drag = 6 : Damping, so the heap settles rather than sloshing forever.

Public Methods

virtual inline const char * tags() const override : Catalog tags: this effect is the power-function showcase.

virtual inline Dim dimensions() const override : Writes the z=0 slice, which extrude fills through a volume.

virtual inline void defineControls() override : Publish the population, the physics and the slope.

virtual inline void prepare() override : Size the pool's storage and wire the view over it.

virtual inline void tick() override : Fill the pit when the count changes, run the physics, then draw each ball as a disc.

More info

Piling is emergent

Gravity pulls everything down, the floor stops it, and contact between neighbors does the rest. So the heap's shape is whatever the collisions produce, with nothing scripting it.

tilt shows why a force belongs in the kernel: one call turns the pit into a slope. The whole heap then slides and re-settles, with no code here that knows about slopes.

Collisions are the non-linear part

They cost pair checks rather than one pass, so the pool is deliberately small. collide runs once a frame before the move, and nearly every pair rejects on one axis alone.