Skyline Lua API  Version 1.0
Lua Script Reference for Skyline Game Engine.
particle Class Reference

#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.
xy 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
NoneThis 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: