Particles

The particles module can be used to easily add particle effects to your app. You will be most concerned with using the EmitterSystem module directly, but be sure you have an EmitterSystem, ParticleSystem, and ParticleRenderer. You can use the Particle Panda 2 application to produce your own effects using a graphical editor.

Emitters

class kivent_particles.emitter.EmitterSystem(**kwargs)

Processing Depends On: EmitterSystem, PositionSystem2D, RotateSystem2D

The EmitterSystem manages attaching particle effects to entities. Each Entity can have up to particle_config.MAX_EMITTERS emitters attached at once. This defaults to 8. If you wish to have more emitters, change this value in particle_config.pxi and recompile kivent_particles.

You need to load an emitter before attaching it to an Entity. This can be done either through providing a dictionary of properties, using load_effect_from_data, or loading a .kep file, using load_effect. Emitters can then be added during init_entity by including the name of the effects to attach, or by calling add_effect.

This GameSystem will use the entities PositionSystem2D and RotateSystem2D components to influence the location of particles.

Attributes:

loaded_effects (list): Returns a list of the names for each effect that has been loaded.

particle_system (ObjectProperty): Reference to the ParticleSystem that will handle the creation and update of individual particles for the emitters of this system. Typically you will link this in your .kv file.

add_effect(self, unsigned int entity_id, str effect_name)

Args:

entity_id (unsigned int): Id of the entity to add the effect to.

effect_name (str): Name of the effect to add.

Return:

int: returns the index in the emitters list for the EmitterComponent of the new effect.

This function will create a new effect for your entity that already have an EmitterComponent. If MAX_EMITTERS is exceeded a TooManyEmitters exception will be raised.

clear_component(self, unsigned int component_index)

copy_data_into_emitter(self, ParticleEmitter to_emitter, str effect_name)

Args:

to_emitter (ParticleEmitter): Emitter to copy the state of the effect into.

effect_name (str): Name of the loaded effect you want to copy the state of.

This function will efficiently copy the prototype loaded under effect_name into the provided ParticleEmitter.

create_effect(self, str effect_name)

Args:

effect_name (str): Name of the loaded effect from which the new Emitter will copy its starting data.

Return:

ParticleEmitter: The new emitter.

Typically called internally as part of the init_component or add_effect functions, this function returns a new ParticleEmitter object that copies the state of the ParticleEmitter loaded under effect_name using either load_effect or load_effect_from_data.

flatten_effect_to_dict(self, ParticleEmitter emitter)

Args:

emitter (ParticleEmitter): The emitter to write out.

Takes a ParticleEmitter object and returns a dictionary containing property, value pairs. Used internally as part of saving an effect.

init_component(self, unsigned int component_index, unsigned int entity_id, str zone, args)

Args:

args (list): List of effect names to load, effect_name must be in loaded_effects.

The initialization arguments for an Emitter component is a list of the names of previously loaded effects to attach to your entity.

load_effect(self, str file_name)

Args:

file_name (str): Name of the file to load.

Return:

str: The name of the effect as it was loaded into memory.

Loads a previously saved effect, uses cPickle. The name of the effect will be returned.

load_effect_from_data(self, dict data, str effect_name)

Args:

data (dict): Dict containing ParticleEmitter property name, value pairs. Can contain all or a subset of the ParticleEmitter properties.

effect_name (str): Name of the new effect.

Loads an effect into memory from a dictionary.

pickle_effect(self, ParticleEmitter emitter, str file_name)

Args:

emitter (ParticleEmitter): The emitter to pickle.

file_name (str): The name of the file to write.

Uses cPickle to save an emitter to disk.

remove_component(self, unsigned int component_index)

remove_effect(self, unsigned int entity_id, int index)

Args:

entity_id (unsigned int): Id of the entity to remove the effect from.

index (int): Index of the emitter to be removed in the Entity’s EmitterComponent emitters list.

Removes an effect from an existing entity without destroying the whole component.

update(self, float dt)

class kivent_particles.emitter.EmitterComponent

The component associated with EmitterSystem. Do not modify emitters yourself. Prefer to use EmitterSystem.add_effect and remove_effect.

Attributes:

entity_id (unsigned int): The entity_id this component is currently associated with. Will be <unsigned int>-1 if the component is unattached.

emitters (list): List of length MAX_EMITTERS (defaults to 8, you can change this by recompiling kivent_particles after modifying particle_config.pxi). Any active emitters will be in this list, open spots will be None.

class kivent_particles.emitter.ParticleEmitter

The ParticleEmitter class controls the creation of particles for any particular effect. You should not create one directly but instead allow EmitterSystem to create them for you. Up to a max of MAX_EMITTERS as defined in particle_config.pxi can be attached to a single entity.

Attributes:

effect_name (str): The name of this effect, as loaded by EmitterSystem.load_effect or EmitterSystem.load_effect_from_data.

texture (str): The name of the texture being used for this particle as registered in resource_managers.TextureManager.

pos_offset (tuple): The (x, y) offset this Emitter should be from the parent Entity’s position component. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set pos_offset again.

x_offset (float): The x component of pos_offset.

y_offset (float): The y component of pos_offset.

emit_angle_offset (float): The offset in degrees from the parent Entity’s rotate component.

emit_angle_variance (float): The amount of variance in the angle offset of a particle.

life_span (float): The number of seconds a particle should exist for.

life_span_variance (float): The amount of variance in life_span for an individual particle.

paused (bool): If True this emitter will not create new particles.

emitter_type (int): The type of the emitter. Should be 0 for gravity emitter, and 1 for radial emitter.

number_of_particles (int): The number of particles this effect should create.

gravity (tuple): The amount of gravity that will effect particles if emitter_type is 0 (Gravity Emitter). This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set gravity again.

gravity_x (float): The x component of gravity.

gravity_y (float): The y component of gravity.

start_scale (float): The scaling factor for the particles at the beginning of their life. Actual size of particle will be scale * size of texture.

start_scale_variance (float): The amount of variance in start_scale for an individual particle.

end_scale (float): The scaling factor for the particles at the end of their life. Actual size of particle will be scale * size of texture.

end_scale_variance (float): The amount of variance in end_scale for an individual particle.

start_rotation (float): The starting rotation for a particle in degrees.

start_rotation_variance (float): The variance in starting rotation for individual particles.

end_rotation (float): The ending rotation for a particle in degrees.

end_rotation_variance (float): The variance in ending rotation for individual particles.

pos_variance (tuple): The amount of variance from the location of emitter per particle. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set pos_variance again.

x_variance (float): The x component of pos_variance.

y_variance (float): The y component of pos_variance.

speed (float): The speed a particle will be emitted at if the emitter_type is 0 (Gravity emitter).

speed_variance (float): The variance in speed for particles generated by emitter_type 0 (Gravity emitter).

radial_acceleration (float): The amount of radial acceleration to be applied to particles generated by emitter_type 0 (Gravity emitters).

radial_acceleration_variance (float): The variation in radial_acceleration.

tangential_acceleration (float): The amount of tangential acceleration to be applied to particles generated by emitter_type 0 (Gravity emitters).

tangential_acceleration_variance (float): The variation in tangential_acceleration.

max_radius (float): The starting distance for particles being emitted by emitter_type 1 (radial emitters).

max_radius_variance (float): The variance in starting distance for radial emitters.

min_radius (float): The minimum radius before a particle is cleaned up when emitted by emitter_type 1 (radial emitters).

rotate_per_second (float): The amount of rotation in degrees that will happen per second for particles emitted by emitter_type 1 (radial emitters).

rotate_per_second_variance (float): The variation in rotate_per_second.

start_color (list): The starting color for particles. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set start_color again.

start_color_variance (list): The amount of variance in each channel for the starting color of particles. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set start_color_variance again.

end_color (list): The ending color for particles. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set end_color again.

end_color_variance (list): The amount of variance in each channel for the ending color of particles. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set end_color_variance again.

calculate_emission_rate(self)

This is called automatically when either number_of_particles or life_span is set. Emission rate is calculated by dividing the number_of_particles by the life_span.

Particles

class kivent_particles.particle.ParticleSystem(**kwargs)

Processing Depends On: ParticleSystem, PositionSystem2D, RotateSystem2D, ScaleSystem2D, ColorSystem

The ParticleSystem class handles creation, removal, and updating of individual particles created by an EmitterSystem.

Be sure to set ‘renderer_name’ to the system_id of the PartclesRenderer you want to render each particle.

You will typically not create an entity using ParticleSystem directly, instead an EmitterSystem will create the particle entities for you.

Attributes:

renderer_name (StringProperty): The system_id of the PartclesRenderer the particles will use.

particle_zone (StringProperty): The zone in memory particles will be created in.

clear_component(self, unsigned int component_index)

init_component(self, unsigned int component_index, unsigned int entity_id, str zone, ParticleEmitter emitter)

Args:

emitter (ParticleEmitter): The emitter the particle is coming from.

The initialization arg for a ParticleComponent is just the ParticleEmitter that is creating the component. Typically you will not initialize a particle yourself, instead EmitterSystem will call ParticleSystem.create_particle (a cdef’d function).

on_system_names(self, instance, value)

remove_component(self, unsigned int component_index)

update(self, float dt)

class kivent_particles.particle.ParticleComponent

The component associated with ParticleSystem

Attributes:

entity_id (unsigned int): The entity_id this component is currently associated with. Will be <unsigned int>-1 if the component is unattached.

current_time (float): The current time of this particle.

total_time (float): The total time for this particle, when current_time exceeds total_time the particle entity will be removed.

start_pos (tuple): The starting position of this particle. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set start_pos again.

start_x (float): The x component of start_pos.

start_y (float): The y component of start_pos.

velocity (tuple): The velocity of this particle. This property returns a copy of the data, not the data itself. Do not modify returned values directly, instead set velocity again.

velocity_x (float): The x component of velocity.

velocity_y (float): The y component of velocity.

radial_acceleration (float): The radial acceleration for this particle.

tangential_acceleration (float): The tangential acceleration for this particle.

emit_radius (float): The current location on the radius of this particle, used for emitter_type 1 emitters (Radial behavior).

emit_radius_delta (float): The rate of change for the emit_radius property.

rotation_delta (float): The rate of change for the rotation of this particle.

scale_delta (float): The rate of change for the scale of this particle.

emitter (ParticleEmitter): The emitter that this particle was created by.

color_delta (list): The rate of change for the color of this particle. Do not modify returned values directly, instead set velocity again.

Renderers

class kivent_particles.particle_renderers.ParticleRenderer

Processing Depends On: ParticlesRenderer, PositionSystem2D, ScaleSystem2D, RotateSystem2D, ColorSystem

The renderer draws with the VertexFormat9F4UB:

ctypedef struct VertexFormat9F4UB:
    GLfloat[2] pos
    GLfloat[2] uvs
    GLfloat[2] center
    GLfloat[2] scale
    GLubyte[4] v_color
    GLfloat rotate

update(self, force_update, dt)