Systems and Groups

Systems

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_global_controller(*controllers)

Add a global controller applied to all groups on update

add_group(group)

Add a particle group to the system

draw()

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_group(group)

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(time_delta)

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

Groups

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.

class lepton.group.ParticleGroup

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_controller()

Bind one or more controllers to the group

controllers

Controllers bound to this group

draw()

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

Renderer bound to this group

system

Particle system this group belongs to

unbind_controller()

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:
        group.kill(particle)

class lepton.group.ParticleProxy

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

position

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

velocity

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

size

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

up

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.

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.

color

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

mass

The mass of the particle as a float.

age

The age of the particle as a float.

class lepton.group.Vector

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.

Note

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.