A particle emitter is the base of all Particles emission. It defines a point or a shape where Particles will be spawned. Particle emitters are attached to a ParticleNetwork which may contain multiple ParticleEmitter that are placed and configure in a way to achieve a specific type of effect.

A Particle emitters are using a combination of ParticleModifier which will dictate the behaviors of each Particles emitted. Particle modifiers act as a node that handles a specific function or behavior to apply to each particle. By adding and combining multiple ParticleModifier you will be able to quickly and easily creates very complex effects.

Static Variables

Name	Description
`particlenetwork`	Parent ParticleNetwork reference where that active ParticleEmitter is attached.
Declaration ParticleNetwork *particlenetwork
`handler`	Handle scripting functionalities and callback for the active ParticleEmitter.
Declaration Handler handler
`emission`	Access the EmissionData properties for the active EmissionType of the ParticleEmitter.
Declaration EmissionData emission
`min`	Min. coordinate of world space AABB of the ParticleEmitter.
Declaration vec3 min
`max`	Max. coordinate of world space AABB of the ParticleEmitter.
Declaration vec3 max
`particlemodifier_count`	Total amounf of ParticleModifier attached to the active ParticleEmitter.
Declaration unsigned char particlemodifier_count
`uid`	Unique id to internally idendity the ParticleEmitter.
Declaration unsigned int uid
`particles`	Reference to the Particles managed by the active ParticleEmitter.
Declaration Particles *particles

Variables

Name Description

fps Controls the refresh rate of the ParticleEmitter.

Declaration

unsigned char fps

Range

0 to 120 Mhz

Note: A value of 0 represent that the ParticleEmitter should be updated every frame.

name Unique name to identify the ParticleEmitter within its parent ParticleNetwork.

Declaration

char *name

local_matrix Local transformation matrix relative to the pivot of the parent ParticleNetwork.

Declaration

mat4 *local_matrix

state Th active State of the current ParticleEmitter.

Declaration

State state

flags Bit mask that determine the active option(s) the ParticleEmitter is using.

Declaration

int flags

Cap	Value	Description
`PEM_FLAG_VISIBLE`	`bit.lshift(1,0)`	Show/hide the ParticleEmitter. Remarks Even if the emitter is hidden it will still update Particles.
`PEM_FLAG_LOCALIZE`	`bit.lshift(1,1)`	Localize Particles so that they are always relative to the parent ParticleNetwork the ParticleEmitter is attached to.
`PEM_FLAG_VOLUMETRIC`	`bit.lshift(1,2)`	When using a emission shape for the system to generate Particles using the volume of the shape. Else the Particles will be generating within its outside structure.
`PEM_FLAG_SELECTED`	`bit.lshift(1,3)`	Mark the active ParticleEmitter as selected.
`PEM_FLAG_OPEN`	`bit.lshift(1,4)`	Tag that the ParticleEmitter box should be opened (editor only).

height Toggle on/off the visible of the ParticleEmitter Particles.

Declaration

bool visible

Remarks: Same as settings the PEM_FLAG_VISIBLE flag.

localize Localize the ParticleEmitter Particles.

Declaration

bool localize

Remarks: Equivalent as setting the PEM_FLAG_LOCALIZE flag true/false.

volumetric Specify wether or not the ParticleEmitter should emmit Particles in a volumetric way or along the edges of the emission shape.

Declaration

bool volumetric

Remarks: Same as setting the PEM_FLAG_VOLUMETRIC flag on/off.

Note: This flag only apply to tri-dimensional emission shapes.

sync_time Last time the ParticleEmitter was re-evaluated.

Declaration

float sync_time

Functions

Name	Description
`SetEmissionType`	Specify the EmissionType of the active ParticleEmitter.
Declaration void SetEmissionType( const EmissionType type ) Parameters `type`: The new type of emission to use.
`SetEmissionWarmstart`	Warmstart the ParticleEmitter.
Declaration void SetEmissionWarmstart( float warmstart, bool randomize ) Parameters `warmstart`: The warmstart time (where 1.0 = 1sec.) to warmstart the ParticleEmitter. `randomize`: Determine whether or not the `warmstart` time should be randomize.
`SetEmissionGeometry`	Assign the Geometry to use for emission.
Declaration bool SetEmissionGeometry( const char name ) Parameters* `name`: The name of the uid of the Mesh Asset to use for geometric emission. To disconnect the Geometry set the `name` to `nil`. Return Value `true` if the EmissionType of the ParticleEmitter is set to `kShape`; else return `false`.
`SetEmissionSource`	Controls the linear motor settings.
Declaration bool SetEmissionSource( const char name ) Parameters* `name`: Another ParticleEmitter name that is attached to the same parent ParticleNetwork to use as source for EmissionType. Return Value `true` if the source `name` is valid (not the same as the active ParticleEmitter) and the active ParticleEmitter type is set as `kSource`; else return `false`.
`SetEmissionGoal`	Set the emission goal for a `kWire` EmissionType ParticleEmitter.
Declaration bool SetEmissionGoal( const vec3 source, const vec3 target ) Parameters `source`: The source location. `target`: The target location. Return Value `true` if the active ParticleEmitter type is `kWire`; else return `false` since this function cannot be applied.
`SetEmissionTrack`	Specify the Track to use for a specific axis of a `kWire` ParticleEmitter.
Declaration bool SetEmissionTrack( Track track, const unsigned char axis ) Parameters* `track`: The Track Asset to connect to the axis; pass `nil` to disconnect a previously connected Track. `axis`: The axis to assign the `track` to; where `0` is `X`, `1` is `Y` and `2` is `Z`. Return Value `true` is the operation succeed; `false` if the ParticleEmitter emission type is not `kWire`.
`SetParticleType`	Set the ParticleType to use for the active ParticleEmitter.
Declaration void SetParticleType( const ParticleType type, unsigned int count ) Parameters `type`: The type of Particles to use for the active ParticleEmitter. `axis`: The maximum amount of Particles the current ParticleEmitter can generate.
`SetEmissionEntity`	Specify the Entity that the ParticleEmitter will emit.
Declaration bool SetEmissionEntity( Entity entity ) Parameters* `entity`: A valid Entity reference to connect; to disconnect an existing Entity send `nil` to the function. Return Value `true` if the ParticleType is set to `kMatter`; else return `false`.
`AddParticleModifier`	Create a new ParticleModifier.
Declaration ParticleModifier AddParticleModifier( const char name, const ParticleModifierType type ) Parameters `name`: A name to identify the ParticleModifier. `type`: The ParticleModifierType to use for the new modifier. Return Value A reference to the newly created ParticleModifier.
`GetParticleModifier`	Retrive an existing ParticleModifier by name.
Declaration ParticleModifier GetParticleModifier( const char name ) Parameters `name`: Name of the ParticleModifier to retrieve. Return Value Reference to the ParticleModifier that matched the `name` received in parameter; else return `nil`.
`GetParticleModifierAt`	Retrive an existing ParticleModifier using its internal index.
Declaration ParticleModifier GetParticleModifierAt( unsigned char index ) Parameters* `index`: Index of the ParticleModifier to retrieve. Return Value A valid ParticleModifier reference on success; else return `nil`.
`GetParticleModifierIndex`	Get the internal index of an existing ParticleModifier connected to the active ParticleEmitter.
Declaration int GetParticleModifierIndex( const ParticleModifier particlemodifier ) Parameters* `particlemodifier`: The ParticleModifier reference to retrieve the index. Return Value `-1` if the `particlemodifer` reference is invalid; else return its internal index.
`SetParticleModifierIndex`	Modify the internal location of a specific ParticleModifier.
Declaration bool SetParticleModifierIndex( ParticleModifier particlemodifier, const unsigned char index ) Parameters* `particlemodifier`: Reference to a ParticleModifier maintained by the active ParticleEmitter. `index`: The new internal location where to place the `particlemodifier` reference. Return Value `true` if the ParticleModifier and the `index` are valid; else return `false`.
`RemoveParticleModifier`	Remove an existing ParticleModifier.
Declaration bool RemoveParticleModifier( ParticleModifier particlemodifier ) Parameters* `particlemodifier`: The ParticleModifier to remove. Return Value `true` if removed successfully; else return `false`.
`RemoveParticleModifierAt`	Remove an existing ParticleModifier by index.
Declaration bool RemoveParticleModifierAt( int index ) Parameters `index`: The internal index of the ParticleModifier to remove. Return Value `true` on success; `false` if the index reveived is invalid.
`SwapParticleModifiers`	Exchange the location of two ParticleModifier.
Declaration bool SwapParticleModifiers( unsigned char index0, unsigned char index1 ) Parameters `index0`: The source index to swap. `index1`: The destination index to swap it with. Return Value `true` if swapped successfully; else return `false` if either of the two index is invalid.
`Play`	Tell the ParticleEmitter to start emitting Particles.
Declaration bool Play( void )
`Pause`	Pause the Particles emission.
Declaration bool Pause( void )
`Stop`	Stop emitting Particles.
Declaration bool Stop( void )
`GetDuration`	Retrieve the duration time of the active ParticleEmitter (for how long particles are emitted).
Declaration float GetDuration( void )
`Sort`	Sort all existing ParticleModifier based on their location in the emission sequence.
Declaration void Sort( void )

EmissionType

Identifiers that specify the type of emission a ParticleEmitter will be producing.

kCentral: Particles are emitted from a single point in space.
kCylindrical: Creates Particles that are contained within the boundary of a cylinder.
kConical: Emits ref Particles within a cone.
kSectorial: Particles are emitted within a sector shape (a non-closed cylinder).
kCubical: Creates Particles within a cube boundary.
kSpherical: Creates Particles around the radius of a sphere; or optionally a hemisphere.
kShape: Use the vertex information of a specific geometry to generate particles (non-volumetric).
kWire: Create particles along a tri-dimensional path in space.
kSource: Use another existing ParticleEmitter Particles information to generate particles.
kMotion: Use an existing Object (or an optional Bone) location to generate particles.

CylindricalEmission

EmissionData variables available when the EmissionType is set to kCylindrical.

Variables

Name	Description
`radius`	Base radius of the cylinder.
Declaration float radius
`height`	Controls the height of the cylinder.
Declaration float height
`centered`	Controls whether the pivot point of the cylinder is located at the center of the shape or at the base.
Declaration bool centered
`step`	The step value to use to generate Particles around the cylindex.
Declaration float step Note If a value greater than `0` is specified this value will be used to increment the step every time a particle is generated forcing them to be generated in a circular fashion around the cylinder base radius.

ConicalEmission

EmissionData variables available when the EmissionType is set to kConical.

Variables

Name	Description
`radius`	Base radius of the cone.
Declaration float radius
`height`	Controls the height of the cone.
Declaration float height

SectorialEmission

EmissionData variables available when the EmissionType is set to kSectorial.

Variables

Name	Description
`angle`	The maximum angle of the sector.
Declaration float angle
`distance`	The radius of the sector.
Declaration float distance
`height`	The spanning area of the sector.
Declaration float height

CubicalEmission

EmissionData variables available when the EmissionType is set to kCubical.

Variables

Name Description

size Size of the cube for each axis.

Declaration

vec3 size

SphericalEmission

EmissionData variables available when the EmissionType is set to kSpherical.

Variables

Name	Description
`hemi`	Use half a sphere instead of a full sphere to generate Particles.
Declaration bool hemi
`radius`	The radius of the sphere.
Declaration float radius

ShapeEmission

EmissionData variables available when the EmissionType is set to kShape.

Static Variables

Name Description

geometry Reference to the Geometry to use for emission.

Declaration

Geometry *geometry

Variables

Name Description

restore Force the system to restore the Geometry vertices before emitting Particles.

Declaration

bool restore

Remarks: Leaving this value to false can allow you to generate Particles on a Geometry that has previously been deformed by a SkeletalMesh, DynamicMesh or manually (by the user).

WireEmission

EmissionData variables available when the EmissionType is set to kWire.

Static Variables

Name	Description
`curve_x`	Reference to the Curve used on the `X` axis.
Declaration Curve *curve_x
`curve_y`	Reference to the Curve used on the `Y` axis.
Declaration Curve *curve_y
`curve_z`	Reference to the Curve used on the `Z` axis.
Declaration Curve *curve_z

Variables

Name	Description
`resolution`	Amount of samples to generate along the wire.
Declaration unsigned int resolution
`relative`	If enabled the system will use the resolution value to compute the playback time of the curves.
Declaration bool relative Remarks If this variable is set to `false` the ParticleEmitter curves will be synced with the application time and the evaluated curves values using their own individual playback time.
`cycle_mode_x`	Specify the CycleMode to use for the `X` axis Curve.
Declaration CycleMode cycle_mode_x
`cycle_mode_y`	Specify the CycleMode to use for the `Y` ayis Curve.
Declaration CycleMode cycle_mode_y
`cycle_mode_z`	Specify the CycleMode to use for the `Z` azis Curve.
Declaration CycleMode cycle_mode_z
`color_x`	Color to identify the `X` axis Curve inside the Molecules Editor.
Declaration vec4 color_x
`color_y`	Color to identify the `Y` ayis Curve inside the Molecules Editor.
Declaration vec4 color_y
`color_z`	Color to identify the `Z` azis Curve inside the Molecules Editor.
Declaration vec4 color_z

SourceEmission

EmissionData variables available when the EmissionType is set to kSource.

Static Variables

Name Description

particleemitter Unique id of the ParticleEmitter to use as source.

Declaration

unsigned int particleemitter

MotionEmission

EmissionData variables available when the EmissionType is set to kMotion.

Variables

Name	Description
`target`	Unique id of the Object to use for motion Particles emission.
Declaration unsigned int target
`target_bone`	Set the index of the Bone to use for motion emission.
Declaration int target_bone Note In the event, the target Object is a SkeletalMesh an optional Bone index can be specified; and its position will be used to emit Particles. If you do not require the ParticleEmitter to track a specific Bone location set this variable to `-1`.

EmissionData

A structure that contains the variables and properties available for each specific EmissionType. Take note that each specific reference to an emission structure will only be accessible if there's a type match. For example, if the type is set to kSource the cylinder properties of the EmissionData will return nil.

Static Variables

Name	Description
`type`	The active EmissionType used by the ParticleEmitter.
Declaration EmissionType type
`warmstart`	Active warmstart value.
Declaration float warmstart
`randomize`	Determine if the `warmstart` should be randomized.
Declaration bool randomize
`cylinder`	Reference to the properties of a CylindricalEmission.
Declaration CylindricalEmission *cylinder Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kCylindrical`.
`cone`	Access the properties of a ConicalEmission.
Declaration ConicalEmission *cone Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kConical`.
`sector`	Reference to the properties of a SectorialEmission.
Declaration SectorialEmission *sector Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kSectorial`.
`cube`	Access the properties of a CubicalEmission.
Declaration ConicalEmission *cube Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kCubical`.
`sphere`	Reference to the properties of a SphericalEmission.
Declaration SphericalEmission *sphere Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kSpherical`.
`shape`	Access the properties of a ShapeEmission.
Declaration ShapeEmission *shape Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kShape`.
`wire`	Reference to the properties of a WireEmission.
Declaration WireEmission *wire Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kWire`.
`source`	Access the properties of a SourceEmission.
Declaration SourceEmission *source Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kSource`.
`motion`	Reference to the properties of a MotionEmission.
Declaration MotionEmission *motion Warning Will be `nil` if the EmissionType of the ParticleEmitter is not `kMotion`.

Events

Callbacks	Description
`OnPlay`	Called when the ParticleEmitter start playing and emitting Particles.
Declaration function OnPlay()
`OnPause`	Triggered when the ParticleEmitter gets paused and stop generating particles.
Declaration function OnPause()
`OnResume`	Event triggered when the ParticleEmitter was paused and the play function is called resuming the emission.
Declaration function OnResume()
`OnStop`	The emitter is stop function have been triggered all particles are removed.
Declaration function OnStop()
`OnCreate`	Triggered when one or more Particles have been created.
Declaration function OnCreate()
`OnDestroy`	One or more particles have been destroyed or have finished their life cycle.
Declaration function OnDestroy()
`OnContact`	Event trigger upon physics collision if one or more particles are in contact with their physics World.
Declaration function OnContact() Note Extended information about the collision will be available within the function callback (see AppEvent).
`OnUpdate`	Trigger when the ParticleEmitter gets updated.
Declaration function OnUpdate()

Material Script & Shader

To help you get started right away with Particles rendering; the Shader and Material Script below is the base that allows you to draw Particles.

Material Script

Lua

function OnDraw()
    Gfx:Enable(Graphics.EnableCap.kBlend);              -- Enable Alpha Blending.
    Gfx:BlendEquation(Graphics.BlendFunction.kAdd );    -- Toggle Additive Blending.
    Gfx:BlendFunc(Graphics.BlendingFactorSrc.kSrcAlpha, -- Combine the alpha value.
                  Graphics.BlendingFactorDst.kDstOne);
    Gfx:Disable(Graphics.EnableCap.kDepthMask);         -- Do not write to the depth buffer.
    Gfx:DepthFunc(Graphics.StencilFunction.kLequal);    -- Less or equal
    Gfx:Disable(Graphics.EnableCap.kCullFace);          -- Draw double-sided (sprite only).
end

function OnDisplay()   
    Gfx:Disable(Graphics.EnableCap.kBlend);    -- Disable blending.
    Gfx:Enable(Graphics.EnableCap.kDepthMask); -- Enable depth write.
    Gfx:Enable(Graphics.EnableCap.kCullFace);  -- Enable cull face.
end

Vertex Shader

GLSL

//#define POINT_SPRITE // Uncomment if you are using kPointSprite
attribute vec2 TEXCOORD0;
attribute vec3 POSITION;
attribute vec4 COLOR0;
attribute float POINTSIZE;

uniform mat4 gfx_ModelViewProjectionMatrix;
uniform mat4 gfx_ModelViewMatrix;
uniform mat4 gfx_ProjectionMatrix;
uniform vec4 gfx_Viewport;

varying vec2 texcoord0;
varying vec4 color0;

void main(void) {
    texcoord0 = TEXCOORD0;
    color0 = COLOR0;
    #ifdef POINT_SPRITE // kPointSprite
        vec4 eyePos = gfx_ModelviewMatrix * vec4( POSITION, 1.0 );
        vec4 projCorner = gfx_ProjectionMatrix * vec4( POINTSIZE * 0.5,
                                                       POINTSIZE * 0.5, 
                                                       eyePos.z,
                                                       eyePos.w );
        gl_PointSize = gfx_Viewport.z * projCorner.x / projCorner.w;
        gl_Position = gfx_ProjectionMatrix * vec4( eyePos );
    #else // kSprite, kTrail
        gl_Position = gfx_ModelViewProjectionMatrix * vec4( POSITION, 1.0 );
    #endif
}

Fragment Shader

GLSL

//#define POINT_SPRITE // Uncomment if you are using kPointSprite
uniform sampler2D SAMPLER0;

varying mediump vec2 texcoord0;
varying lowp vec4 color0;

void main(void) { 
    #ifdef POINT_SPRITE // kPointSprite    
        gl_FragColor = texture2D( SAMPLER0, gl_PointCoord ) * color0;
    #else // kSprite, kTrail
        gl_FragColor = texture2D( SAMPLER0, texcoord0 ) * color0;
    #endif
}