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.

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)

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

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).

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

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

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