Navigation

Particle controllers are bound to particle groups and invoked via the group’s
update() method. A typical controller will iterate all particles in a
group, apply some logic and mutate the particles or remove or add particles to
the group.

Lepton’s built-in controllers are written in C for performance, but Python
functions or classes with __call__() methods can also be used.

damping – A three-tuple velocity multiplier per unit time
in each respective dimension. A scalar may also be specified
if the damping is equal in all dimensions (thus .25 is equivilent
to (.25, .25. .25))

min_velocity – Minimum velocity scalar. Particle velocities
less than this are scaled up, except for particles with no
velocity since their velocity vectors have no direction

domain – Particles that collide with the surface of this domain are
redirected as if they bounced or reflected off the surface. This
alters the position and velocity of the particle. The domain must have
a non-zero area.

bounce – The coefficient of restitution multiplied by the normal
component of the collision velocity. This determines the deflection
velocity of the particle. If 1.0 (default) the particle is deflected
with the same energy it struck the domain with, if zero, the particle
will stick to the domain’s surface and not bounce off.

friction – The resistance presented by the domain surface to sliding
particle movement tangental to the domain. 1 - friction is multiplied
by the tangental component of the particles velocity. A value of 0
means no friction. if friction is negative, the particle will gain
velocity.

bounce_limit – The maximum number of bounces deflections calculated per
particle per iteration. Higher values can result in more accuracy
at potentially higher CPU cost. A value of -1 is effectively infinite.

callback – An optional function called when a particle collides
with the domain. Must have the signature:

Multiplied by the normal component of the collision velocity,
this determines the amount of deflection from the domain’s boundary.
If positive, the particle will bounce off of the domain. If zero
the particle will “stick” to the boundary. If negative, the particle
will be refracted across the boundary

The maximum number of bounces deflections calculated per particle
per iteration. Important for fast moving particles contained inside
small domains, or domains with corners. Small values may reduce CPU
cost, but also may allow particles to escape containment.

Multiplied by the tangental component of the collision velocity,
this determines the resistance to sliding tangentially across the
domain boundary. 1 - friction is multiplied by the tangental component
of the particle’s velocity.

As the distance between the particle and domain surface decreases the magnet’s force tends toward infinity. To improve stability, the value of epsilon is always added to the distance value when calculating the magnet force. The default value for epsilon is very close to zero, and provides a realistic simulation while avoiding infinite forces. Larger values may be desireable for certain visual effects where increased stability is more desirable than realistic physics. Using a value of zero for epsilon is not recommended to avoid infinite particle velocities.

color_times – A sequence of 2 or more (time, color) pairs where color
is a 3 or 4 tuple of floats representing the color and time is the
particle age when it is assigned that color. This list is used to create
a gradient of colors for the particles over time. If a particle’s age
is less than the smallest time or greater than the latest time, its
color is not changed. Note that the time values can be specified in any
order, but a particular time value should occur only once, a ValueError
is raised if a time value is repeated

resolution – The number of colors per unit time in the cached gradient.
A larger resolution will result in smoother color blending, but at
the cost of memory and performance. A reasonable value is the expected
frame rate of your application, or a lower value if the age span of
color_times is especially long or if the color changes are not rapid.
In general, pick the lowest value that gives acceptable visual results

If you continue to emit particles into a group then the number of particles
can grow in an unbounded way. To avoid this you should ensure there is some
reliable way in which particles can be destroyed.

Particles may be destroyed after a certain per-particle lifetime, or perhaps
when they move into or out of a domain.