Systems and Groups


A ParticleSystem is the top-level interface to Lepton. A system can contain ParticleGroups, and you can bind global controllers to it to be applied to all groups in the system. The system has methods for conveniently updating and rendering all of the groups it contains.

A default particle system is created for you when you import lepton, available as lepton.default_system.

The ParticleSystem object contains an update method which is designed to be scheduled to regularly invoke the groups’ controllers. It also has a draw method which can be called within the main loop or “on draw” event handler of the application. This allows the application to remain decoupled from the individual groups, controllers and renderers which may change dynamically at run-time.

class lepton.system.ParticleSystem(global_controllers=())

Add a global controller applied to all groups on update


Add a particle group to the system


Draw all particle groups in the system using their renderers.

This method is convenient to call from your Pyglet window’s on_draw handler to redraw particles when needed.


Remove a particle group from the system, raise ValueError if the group is not in the system

run_ahead(time, framerate)

Run the particle system for the specified time frame at the specified framerate to move time forward as quickly as possible. Useful for “warming up” the particle system to reach a steady-state before anything is drawn or to simply “skip ahead” in time.

time – The amount of simulation time to skip over.

framerate – The framerate of the simulation in updates per unit time. Higher values will increase simulation accuracy, but will take longer to compute.


Update all particle groups in the system. time_delta is the time since the last update (in arbitrary time units).

When updating, first the global controllers are applied to all groups. Then update(time_delta) is called for all groups.

This method can be conveniently scheduled using the Pyglet scheduler method: pyglet.clock.schedule_interval


ParticleGroup objects are the lowest level construct. Groups consist of an arbitrary number of Particles. Although in many ways a group is like a particle container, particles cannot exist independently outside of a group. All particles are created and destroyed via their group’s methods. A particle spends its entire existence within a single group.

By default, groups are automatically added to the default particle system when they are created. Most applications can simply use the default particle system object, but more complex applications can create their own systems as needed. A multi-window application might need separate systems for each window, or separately systems can be used if different graphics are updated in different timelines.

All particles in a group have the same general behavior and are rendered together using the same renderer.


Group of particles that share behavior via controllers and are rendered as a unit

ParticleGroup(controllers=(), renderer=None, system=particle.default_system)

Initialize the particle group, binding the supplied controllers to it and setting the renderer.

If a system is specified, the group is added to that particle system automatically. By default, the group is added to the default particle system (particle.default_system). If you do not wish to bind the group to a system immediately, pass None for the system.


Bind one or more controllers to the group


Controllers bound to this group


Draw the group using its renderer (if any)

kill(particle) → None

Destroy a particle in the group.

killed_count() → Number of killed particles not yet reclaimed
new(template) → particle reference

Create a new particle in the group with attributes copied from the specified template particle or specified via keyword arguments. Note new particles are not visible until they are incorporated by calling the update() method.

new_count() → Number of new particles not yet incorporated

Renderer bound to this group


Particle system this group belongs to


Unbind a controller from the group so it is no longer invoked on update. If the controller is not bound to the group raise ValueError

update(time_delta) → None

Incorporate new particles added since the last update, and optimize the particle list. Then invoke the controllers bound to the group to update the particles

Accessing individual particles

Groups may be iterated to access individual particles. The objects returned through iteration are ParticleProxy objects that serve as a convenient way to manipulate individual particles within the group.:

for particle in group:
    if particle.position.y < 0:

A reference to a particle within a group. Various attributes of the proxy can be read or set to update the underlying particle.


The position of the particle, as a 3-item Vector.


The velocity of the particle, as a 3-item Vector.


The size of the particle, as a 3-item Vector.


The current rotation the particle, as a 3-item Vector of euler angles.

If using the Billboard renderer, only the z component is in fact relevant; the other components are discarded.

The other renderers do not support rotation.


The rotation vector of the particle, as a 3-item Vector of euler angular velocities.

If using the Billboard renderer, only the z component is in fact relevant.


The color of the particle, as a 4-item Vector.


The mass of the particle as a float.


The age of the particle as a float.


A namedtuple-like proxy for access to vector attributes of a lepton object. Like a ParticleProxy, these refer to underlying memory within a group. You cannot create Vector instances.

Vectors behave as 3- or 4-item tuples. You can also access components of the vector with the attributes x, y, z, or r, g, b, and a.

clamp(min, max)

Clamp all values of the vector between min and max, in place.

Returns self.


Particles are not independent first-class objects; the particle data is actually stored in a contiguous memory array for efficiency.

ParticleProxy and Vector objects may become invalid whenever controllers run. You should not keep references to these objects outside of an update loop.