cocos.particle module

Particle system engine

exception ExceptionNoEmptyParticle

Bases: Exception

Particle system has no room for another particle.

class Color(r, g, b, a)

Bases: object

Representation of a rgba color

  • r (float) – red component
  • g (float) – green component
  • b (float) – blue component
  • a (float) – alpha component

Convert Color to a tuple.

Returns:tuple – r, g, b and a components.
class ParticleSystem(fallback=None, texture=None)

Bases: cocos.cocosnode.CocosNode

Base class for many flavors of cocos particle systems.

The easiest way to customize is to subclass and redefine some class attributes; see cocos.particle_systems for examples.

To define a per-class custom texture, override load_texture(). To use a per-instance custom texture, pass it in the __init__ texture kw-param

  • fallback (Optional[None, True, False]) –

    Defaults to None.

    • False: use point sprites, faster, not always available
    • True: use quads, slower but always available
    • None: autodetect, use the fastest available
  • texture (Optional[pyglet.image.Texture]) – The texture image to be used for the particles.
Code calling add_particle must either:

It is acceptable to try: ... except...: pass


Draw the particles system


Called instead of draw() when quads are used instead of Point Sprite.


Set initial particles state.


Sets the default texture used by all instances of this particles system.

Override this method to change the default texture.


By issue #168 the texture should hold only one image, so don’t use:

texture = pyglet.resource.image('z.png').texture # (produces an atlas, ie multiple images in a texture)

You can use instead:

texture = pyglet.image.load(...).get_texture()
# Or using pyglet resource mechanism
texture = pyglet.image.load('filename.png', file=pyglet.resource.file('filename.png')).get_texture()

Helper function creating quad vertices based on particles position.

on_cocos_resize(usable_width, usable_height)

Handler for windows resize.

  • usable_width (int) – New window width.
  • usable_height (int) – New window height.

Called everytime the Particle system enters the stage.


Called everytime the Particle system exits the stage.


Resets the particle system.


Called every frame to create new particles if needed and update the particles position.

If a duration was given to this particle system, the method will check if it needs to remove itself from its parent node when its time has arrived.

Parameters:delta (float) – time in seconds since last frame.

Stop the particle system.


Updates particles position.

Parameters:delta (float) – time in seconds since last frame.

Helper function to update particle quad colors based on particle color.


Helper function to update particle quad vertices based on particle position.

active = True

is the particle system active ?

angle = 0.0

The angle (direction) of the particles measured in degrees

angle_var = 0.0

Angle variance measured in degrees

blend_additive = False

blend additive

color_modulate = True

color modulate

duration = 0

duration in seconds of the system. -1 is infinity

elapsed = 0

time elapsed since the start of the system (in seconds)

emit_counter = None

How many particles can be emitted per second

end_color = Color(0.00, 0.00, 0.00, 0.00)

End color of the particles

end_color_var = Color(0.00, 0.00, 0.00, 0.00)

End color variance

gravity = Point2(0.00, 0.00)

Gravity of the particles

life = 0

How many seconds will the particle live

life_var = 0

Life variance

particle_count = None

Count of particles

pos_var = Point2(0.00, 0.00)

Position variance

position_type = 1

position type. Defaults to POSITION_GROUPED

radial_accel = 0.0

Radial acceleration in degrees per second

radial_accel_var = 0.0

Radial acceleration variance


The scaling factor of the object.

size = 0.0

Size of the particles

size_var = 0.0

Size variance

speed = 0.0

The speed the particles will have.

speed_var = 0.0

The speed variance

start_color = Color(0.00, 0.00, 0.00, 0.00)

Start color of the particles

start_color_var = Color(0.00, 0.00, 0.00, 0.00)

Start color variance

tangential_accel = 0.0

Tangential acceleration

tangential_accel_var = 0.0

Tangential acceleration variance

texture = None

texture for the particles, will be loaded in __init__ because Intel weakness, #235. Either override the load_texture() method in a subclass to define a common texture for all particles system of this class, or provide a texture argument to the __init__ method to define a custom texture for that instance.

total_particles = 0

Maximum particles

PointerToNumpy(a, ptype=ctypes.c_float)

Provides a ctype pointer to a Numpy array.

  • a (numpy.array) – The Numpy array.
  • ptype (ctypes) – The ctypes type contained in the array.

Pointer to the Numpy array.

Returns:bool – tells if point sprites are available.

For development and diagonostic cocos.particle.forced_point_sprites could be set to force the desired return value.


Function generating a random float beween -1.0 and 1.0.