Particle System File Format (.kglp)

Simulant uses a custom file format to define particle system properties. These files are JSON files with a particular set of keys and values.

System properties

The JSON file should have a root dictionary which defines the particle system, it can have the following properties:

• name (string): This is a human readable description for the particle system
• quota (integer): This is the maximum number of live particles that the particle system can create across all emitters
• particle_width (float): This is the width of the particle sprites in world units
• particle_height (float): This is the height of the particle sprites in world units
• cull_each (boolean): If true each particle will be individually culled (not yet implemented)
• emitters (array): A list of dictionaries, each defining the properties of a particle emitter
• manipulators (array): A list of dictionaries, each defining a rule that affects particles each frame
• material (string): Either a path to a material file, or the name of a built-in material (e.g. "TEXTURED_PARTICLE")
• material.XXXXX: These keys allow you to set individual material properties on the specified material, their type depends on the property type of the Material property.

Emitter properties

• type (string): This is the type of emitter the valid options are "point" or "box"
• direction (string): This is the (relative) direction the particles travel. It's a space separated list of x, y, z floats.
• velocity (float): This is the speed at which particles are emitted
• ttl_min (float): The minimum time in seconds that a particle lives
• ttl_max (float): The maximum time in seconds that a particle lives
• angle (float): The angle in degrees from the direction vector that the particle can travel. The greater the angle, the more the particle spread
• colour (string): The colour of the particles emitted. This is a space separated list of r, g, b and alpha values (between 0.0 and 1.0)
• emission_rate (integer): A many particles can be emitted per second
• duration (float): How long in seconds that the emitter should last. Zero means forever
• repeat_delay (float): If set, the emitter will restart it's duration after this many seconds (e.g. repeated bursts of particles)

Manipulator properties

• type (string): The type of the affector, valid options are: size, colour_fader, direction, direction_noise_random

Additional properties depend on the type of the affector

Size

• rate (float): A value between -1.0 and +1.0, the amount per second to reduce the size of the particle
• curve (string): This can be used instead of rate to use a curve function for the sizing. Options are linear(rate), or bell(peak, deviation).

Colour Fader

• colours(array): A list of strings in the format "R G B A" or "R G B" where each element is a floating point number between 0.0 and 1.0
• interpolate(bool): Whether or not to blend between colours

Direction

• force (string): A vector described in the format "X Y Z" which defines the force per second to be applied to each particle's position

Direction Noise Random

• force (string): A vector described in the format "X Y Z" which defines the force per second to be applied to each particle's position
• noise_amount (string): A vector described in the format "X Y Z" which defines how much noise per second is added to each particle's direction