#include <LUA_API_Particle.h>

Public Member Functions
void	attach (int particleFX_HND, int EntityID, float x, float y, float z, int flipDirection)
	This Function attaches the particle to another object. More...

void	setEffectDuration (int duration)
	This Function sets a particle effects life time duration. More...

void	setEffectName (string name)
	This Function sets the name if the particle effect. More...

void	setEffectFile (String filename)
	Set the file name of the particle effect to load. More...

int	createParticleFX ()
	Creates a new Ogre particle effect ready for spawning. More...

int	createSkyParticleFX ()
	Creates a new SkyParticle effect ready for spawning. More...

int	spawnEffect (int particleFX_ID, float posx, float posy, float posz)
	This function will spawn an existing Ogre particle system to the provided position. More...

int	spawnSkyParticleEffect (int particleFX_ID, float posx, float posy, float posz)
	This function will spawn an existing SkyParticle effect to the provided position. More...

void	deleteParticleFX (int particleFX_hnd)
	This Function deletes a particle effect with the id of particleFX_ID. More...

void	setParticlePosition (int particleFX_ID, float posx, float posy, float posz)
	Set the position of the particle effect whose ID equals particleFX_ID. More...

void	setEmitting (int particleFX_hnd, int state)
	Sets whether a particle emitter is emitting particles or not. More...

void	setEmitterRate (int particleFX_hnd, int rate)
	Sets the rate of the particle emitter. More...

void	setParticleSpeed (int particleFX_hnd, float speed)
	Sets the Speed of the particle effects movements. More...

void	lookAtObj (int particleFX_ID, int objID)
	Aim the particle rotation towards an object. More...

void	lookAtPoint (int particleFX_ID, float x, float y, float z)
	Set the target position of the particle effect whose ID equals particleFX_ID. More...

void	setScale (int particleFX_ID, float scalex, float scaley, float scalez)
	Set the scale of the particle effect whose ID equals particleFX_ID. More...

void	setRotation (int particleFX_ID, float rotw, float rotx, float roty, float rotz)
	Set the Rotation of the particle effect whose ID equals particleFX_ID. More...

void	changeParticleData (int particleFX_ID, string filename)
	This Function Changes the template data for this sky particle to the data provide in the new file. More...

void particle	setRenderOrder (hndl, order)
	particle.setRenderOrder(hndl, order); More...

void	setVisibleDistance (float distance)
	Visible distance for the effect. More...

int	PU_Create ()
	Creates a new Particle Universe particle effect ready for spawning. More...

int	PU_Run (int PU_ID, float posx, float posy, float posz)
	This function will Run an existing Particle Universe(PU) effect in the provided position. More...

	PU_Stop (int PU_ID, int fadeoutTime)
	This function will Stop a running Particle Universe(PU) effect.. More...

	PU_Pause (int PU_ID, int pauseTime)
	This function will Pause a running Particle Universe(PU) effect for the time passed in the arg. More...

	PU_setRenderOrder (int PU_ID, int order)
	This function will set the render order of a Particle Universe(PU) effect. More...

Detailed Description

All Particle functions can be accessed through the use of this class. Use as particle.function()
The following is a working example of particle spawning, it also demonstrates many other Skyline Lua features. Copy and save the code to a new lua script, attach it to an entity then press the run button.

    --[[
        |-----------------------------------------------------------------
        | Spawn Sky particle example.
        
        | Instructions: Attach this script to an entity. 
        | Hit A key to Spawn Particles at random positions on the screen
        |-----------------------------------------------------------------
    --]]

    obj         = 0
    Fx_Data_ID  = 0
    hnd         = 0
    x           = 0
    y           = 0
    z           = 0

    function onInit( objID )
        ------------------------------------------------------------------
        -- Create our effect Data, only do this setup once.
        ------------------------------------------------------------------  
        obj = objID
        sky.lprint ( "\nLUA: onInit() Creating Sky Particle Effects\n" )

        effectDuration  = 2000      -- Time this effect will live in ms( 1000ms = 1sec )
        particleFile    = "Boom01"  -- this is a *.skyparticle file without the extension
        
        particle.setEffectDuration(effectDuration)
        particle.setEffectFile(particleFile)
        
        Fx_Data_ID = particle.createSkyParticleFX() -- create the particle template
        x,y,z = entity.getPosition(obj)
    end

    function onKeyDown( key )
        sky.lprint ( "\nLUA: KEY() ")
        posx = x + math.random(-60,60)
        posy = y + math.random(-60,60)
        hnd = particle.spawnSkyParticleEffect(Fx_Data_ID,posx,posy,z-100)
        sky.trace()
    end

For more information on how these functions can be used please visit the User Manual - https://home.aurasoft-skyline.co.uk

Member Function Documentation

void particle::attach	(	int	particleFX_HND,
		int	EntityID,
		float	x,
		float	y,
		float	z,
		int	flipDirection
	)

This Function attaches the particle to another object.

Parameters

particleFX_HND	:The handle of the spawned particle effect
EntityID	:The ID of the object to attach to.
x	y z : The positional offset
flip	: Int flip to change the direction along the z axis

This is a self managed attach. There is no need to deattach on deleting this effect
as this is automatically done for you on a call to delete effect.
The command can be seen as "attach particleFX_HND to object EntityID.

The following is a Small Example on how to use this function:

function onInit(objID)
    particle.setEffectDuration(effectDuration)
    particle.setEffectFile(particleFile)
    
    Fx_Data_ID = particle.createSkyParticleFX() -- create the particle template
    FX_HND = particle.spawnSkyParticleEffect(Fx_Data_ID,posx,posy,z-100)

    particle.attach( FX_HND, objID, x, y, z, 1 ); 
end

void particle::changeParticleData	(	int	particleFX_ID,
		string	filename
	)

This Function Changes the template data for this sky particle to the data provide in the new file.

Parameters

particleFX_ID	:The ID of the effect which you would like to change the data.
filename	:The name of the file containing the particle data.

The following is a Small Example on how to use this function:

function onInit(objID)
    particle.changeParticleData( particleFX_ID, "Cool Effect" ); 
end

int particle::createParticleFX ( )

Creates a new Ogre particle effect ready for spawning.

Parameters

None

Returns: particleFX_ID : This function will return the ID of the particle created.

Once you have defined the particle params a call to particle.createParticleFX()
will set your particle system up ready for spawning.

The following is a Small Example on how to use this function:

function onInit(objID)
    particleFX_ID = particle.createSkyParticleFX() 
end

int particle::createSkyParticleFX ( )

Creates a new SkyParticle effect ready for spawning.

Parameters

None

Returns: particleFX_ID : This function will return the ID of the particle created.

Create a new sky particle ready for loading a fresh template files or dynamic editing.

The following is a Small Example on how to use this function:

function onInit(objID)
    -- create the particle template
    particleFX_ID = particle.createSkyParticleFX()
end

void particle::deleteParticleFX ( int particleFX_hnd )

This Function deletes a particle effect with the id of particleFX_ID.

Parameters

particleFX_hnd :The ID of the spawned effect which you would like to delete.

NOTE: Pass the ID handle of the spawned particle, NOT the ID of the data used when creating the particle template.
ie.
particleFX_ID = particle.createSkyParticleFX()
particleFX_hnd = particle.spawnSkyParticleEffect(Fx_Data_ID,posx,posy,z-100);

The following is a Small Example on how to use this function:

function onStop(objID)
    particle.deleteParticleFX( particleFX_hnd );
end

void particle::lookAtObj	(	int	particleFX_ID,
		int	objID
	)

Aim the particle rotation towards an object.

Parameters

particleFX_ID	:The ID of the effect which you would like to affect.
objID	: the ID of the object to point the particle at

The following is a Small Example on how to use this function:

function onUpdate(objID)
    particle.lookAtObj(particle_ID, objID);
end

void particle::lookAtPoint	(	int	particleFX_ID,
		float	x,
		float	y,
		float	z
	)

Set the target position of the particle effect whose ID equals particleFX_ID.

Parameters

particleFX_ID	:The ID of the effect which you would like to work with.
posx	:New X Position of the target.
posy	:New Y Position of the target.
posz	:New Z Position of the target.

The following is a Small Example on how to use this function:

function onUpdate(objID)
    particle.lookAtPoint(particle_ID, 2, 1, 2);
end

int particle::PU_Create ( )

Creates a new Particle Universe particle effect ready for spawning.

Parameters

None	This command needs to be called if you wish to run any Particle Universe effects.

The following is a Small Example on how to use this function:

obj     = 0;
PU_ID   = 0

function onInit(objID)
    sky.lprint("LUA: PU Particle Test Script Active!"); 
    obj = objID;

    --prepare PU effect
    effectDuration  = 2000;     -- Time this effect will live in ms( 1000ms = 1sec )
    particleFile    = "mp_torch";   -- this is a *.skyparticle file without the extension

    particle.setEffectDuration(effectDuration);
    particle.setEffectFile(particleFile);
    particle.setVisibleDistance(80);

    PU_ID = particle.PU_Create() -- create the PU particle 
    particle.setScale( PU_ID ,0.2, 0.2, 0.2)
end

particle::PU_Pause	(	int	PU_ID,
		int	pauseTime
	)

This function will Pause a running Particle Universe(PU) effect for the time passed in the arg.

Parameters

PU_ID : the PU effect ID for the previously created PU effect.

Returns: pauseTime : The time to pause the effect for in seconds.

The following is a Small Example on how to use this function:

obj     = 0;
PU_ID   = 0

function onInit(objID)
    sky.lprint("LUA: PU Particle Test Script Active!"); 
    obj = objID;
    --prepare PU effect
    effectDuration  = 2000;     -- Time this effect will live in ms( 1000ms = 1sec )
    particleFile    = "mp_torch";   -- this is a *.skyparticle file without the extension
    particle.setEffectDuration(effectDuration);
    particle.setEffectFile(particleFile);
    particle.setVisibleDistance(80);
    PU_ID = particle.PU_Create() -- create the PU particle 
end

function onKeyDown( key )
    x,y,z = entity.getPosition(obj);
    particle.PU_Run(PU_ID, x, y, z);
end

function onKeyUp( key )
    particle.PU_Pause(PU_ID, 1); --pause for 1 second
end

int particle::PU_Run	(	int	PU_ID,
		float	posx,
		float	posy,
		float	posz
	)

This function will Run an existing Particle Universe(PU) effect in the provided position.

Parameters

PU_ID	: the effect ID for the previously created PU effect.
posx	:X Position to spawn the skyParticle effect.
posy	:Y Position to spawn the skyParticle effect.
posz	:Z Position to spawn the skyParticle effect.

Returns: hndl : The handle of the spawned PU effect so we can gain access to it later.

This function will spawn an existing PU system at the position x,y,z. Note you must have
already created a PU particle system by the call to the command PU_Create()
The following is a Small Example on how to use this function:

obj     = 0;
PU_ID   = 0

function onInit(objID)
    sky.lprint("LUA: PU Particle Test Script Active!"); 
    obj = objID;

    --prepare PU effect
    effectDuration  = 2000;     -- Time this effect will live in ms( 1000ms = 1sec )
    particleFile    = "mp_torch";   -- this is a *.pu file without the extension

    particle.setEffectDuration(effectDuration);
    particle.setEffectFile(particleFile);
    particle.setVisibleDistance(80);

    PU_ID = particle.PU_Create() -- create the PU particle 
    particle.setScale( PU_ID ,0.2, 0.2, 0.2)
end

function onKeyDown( key )
    x,y,z = entity.getPosition(obj);
    particle.PU_Run(PU_ID, x, y+1.8, z);
end

particle::PU_setRenderOrder	(	int	PU_ID,
		int	order
	)

This function will set the render order of a Particle Universe(PU) effect.

Parameters

PU_ID : the PU effect ID for a previously created PU effect.

Returns

order : The render order, 0 - 99 where 99 is the top most "layer" The following is a Small Example on how to use this function:

particle::PU_Stop	(	int	PU_ID,
		int	fadeoutTime
	)

This function will Stop a running Particle Universe(PU) effect..

Parameters

PU_ID : the PU effect Handle for the previously created PU effect.

Returns: fadeoutTime : the fade out time to apply to this effect.

This function will stop a running PU system. By passing a fadeoutTime = 0 a fast stop will be activated
any time other than zero will add a fade out to the PU effect. the Fade out time is set by the arg "fadeoutTime"
this is use in seconds fadeoutTime = 1 will fade out over one second once the effect sequence has completed.

The following is a Small Example on how to use this function:

obj     = 0;
PU_ID   = 0

function onInit(objID)
    sky.lprint("LUA: PU Particle Test Script Active!"); 
    obj = objID;
    --prepare PU effect
    effectDuration  = 2000;     -- Time this effect will live in ms( 1000ms = 1sec )
    particleFile    = "mp_torch";   -- this is a *.skyparticle file without the extension
    particle.setEffectDuration(effectDuration);
    particle.setEffectFile(particleFile);
    particle.setVisibleDistance(80);
    PU_ID = particle.PU_Create() -- create the PU particle 
end

function onKeyDown( key )
    x,y,z = entity.getPosition(obj);
    particle.PU_Run(PU_ID, x, y, z);
end

function onKeyUp( key )
    particle.PU_Stop(PU_ID, 1);
end

void particle::setEffectDuration ( int duration )

This Function sets a particle effects life time duration.

Parameters

duration :Sets the lifetime duration (ms) for the particle effect to exist. Note: 1000ms = 1sec

The following is a Small Example on how to use this function:

function onInit(objID)
    particle.setEffectDuration( 2000 ); 
end

void particle::setEffectFile ( String filename )

Set the file name of the particle effect to load.

Parameters

filename :File name of the particle effect to load.

NOTE: The file name string does NOT need to include the file extension, "myParticle" not "myParticle.effect"
The following is a Small Example on how to use this function:

function onInit(objID)
    particleFile    = "Boom01";  -- this is a *.skyparticle file without the extension
    particle.setEffectFile( particleFile );
end

void particle::setEffectName ( string name )

This Function sets the name if the particle effect.

Parameters

name	:set the particle name

The following is a Small Example on how to use this function:

function onInit(objID)
    particle.setEffectName( "myParticle" ); 
end

void particle::setEmitterRate	(	int	particleFX_hnd,
		int	rate
	)

Sets the rate of the particle emitter.

Parameters

particleFX_ID	:The handle of the effect which you would like to change the position.
rate	: number of particles per second

This will set the number of particles to be fired by the emitter per second.

function onUpdate(objID)
    particle.setEmitterRate(particleFX_hnd, 10);
end

void particle::setEmitting	(	int	particleFX_hnd,
		int	state
	)

Sets whether a particle emitter is emitting particles or not.

Parameters

particleFX_ID	:The handle of the effect which you would like to change the position.
state	: 1 = true, 0 = false - this sets the emitter to spit particles out or not.

This effect is useful for moving particles that only need particles to emit at certain points, e.g. a vehicle's tire breaking traction. The following is a Small Example on how to use this function:

function onUpdate(objID)
    particle.setEmitting(particleFX_hnd, 1);
end

void particle::setParticlePosition	(	int	particleFX_ID,
		float	posx,
		float	posy,
		float	posz
	)

Set the position of the particle effect whose ID equals particleFX_ID.

Parameters

particleFX_ID	:The ID of the effect which you would like to change the position.
posx	:New X Position of the effect.
posy	:New Y Position of the effect.
posz	:New Z Position of the effect.

The following is a Small Example on how to use this function:

function onUpdate(objID)
    particle.setParticlePosition(particleFX_ID, 0, 10, 0);
end

void particle::setParticleSpeed	(	int	particleFX_hnd,
		float	speed
	)

Sets the Speed of the particle effects movements.

Parameters

particleFX_ID	:The handle of the effect which you would like to change the position.
speed	: > 1 is faster movements, < 1 is slower movements.

function onUpdate(objID)
    particle.setParicleSpeed(particleFX_hnd, 2);
end

void particle particle::setRenderOrder	(	hndl	,
		order
	)

particle.setRenderOrder(hndl, order);

Parameters

Handle	:
Order	:

Set the render order of particles.

The following is a Small Example on how to use this function:

function onInit(objID)
    example coming soon
end

void particle::setRotation	(	int	particleFX_ID,
		float	rotw,
		float	rotx,
		float	roty,
		float	rotz
	)

Set the Rotation of the particle effect whose ID equals particleFX_ID.

Parameters

particleFX_ID	:The ID of the effect which you would like to change the scale.
rotw	:New X Rotation of the effect.
rotx	:New X Rotation of the effect.
roty	:New Y Rotation of the effect.
rotz	:New Z Rotation of the effect.

The following is a Small Example on how to use this function:

function onUpdate(objID)
    particle.setRotation(particle_ID,w,x,y,z);
end

void particle::setScale	(	int	particleFX_ID,
		float	scalex,
		float	scaley,
		float	scalez
	)

Set the scale of the particle effect whose ID equals particleFX_ID.

Parameters

particleFX_ID	:The ID of the effect which you would like to change the scale.
posx	:New X Scale of the effect.
posy	:New Y Scale of the effect.
posz	:New Z Scale of the effect.

The following is a Small Example on how to use this function:

function onUpdate(objID)
    particle.setParticleScale(particle_ID, 0.5, 0.5, 0.5);
end

void particle::setVisibleDistance ( float distance )

Visible distance for the effect.

Parameters

distance :thde distance in m untill the effect will be visible.

once the camewra hs moved further than the visible distance this effect will pause
helping keep performance up.

The following is a Small Example on how to use this function:

function onInit(objID)
    particle.changeParticleData( particleFX_ID, "Cool Effect" ); 
end

int particle::spawnEffect	(	int	particleFX_ID,
		float	posx,
		float	posy,
		float	posz
	)

This function will spawn an existing Ogre particle system to the provided position.

Parameters

particleFX_ID	: the ID for the previously created particle effect.
posx	:X Position to spawn the particle effect.
posy	:Y Position to spawn the particle effect.
posz	:Z Position to spawn the particle effect.

Returns: effect_ID :The ID for the spawned effect so we can gain access to it later.

This function will spawn an existing particle system to the position x,y,z. Note you must have already
creates a particle system by the call to the command createParticleFX() and the file must be of type *.particle

The following is a Small Example on how to use this function:

function onInit(objID)
    particle.spawnEffect(particleFX_ID, 0, 10, -50) 
end

int particle::spawnSkyParticleEffect	(	int	particleFX_ID,
		float	posx,
		float	posy,
		float	posz
	)

This function will spawn an existing SkyParticle effect to the provided position.

Parameters

particleFX_ID	: the ID for the previously created skyParticle effect.
posx	:X Position to spawn the skyParticle effect.
posy	:Y Position to spawn the skyParticle effect.
posz	:Z Position to spawn the skyParticle effect.

Returns: effect_ID :The ID for the spawned effect so we can gain access to it later.

This function will spawn an existing Sky particle system to the position x,y,z. Note you must have
already creates a particle system by the call to the command createParticleFX() and the file must
be of type *.skyparticle

The following is a Small Example on how to use this function:

function onInit(objID)
    posx = x + math.random(-60,60);
    posy = y + math.random(-60,60);
    hnd = particle.spawnSkyParticleEffect(Fx_Data_ID,posx,posy,z-100);
end

The documentation for this class was generated from the following file:

LUA_API_Particle.h

Public Member Functions

Detailed Description

Member Function Documentation