rigz.timelinefx: Functions Types Modinfo Source  

TimelineFX for BlitzMax

TimelineFX is a system for creating particle effects within your games and applications

Big thanks to the following: Bruce Henderson (Brucey) for all the great modules, Garritt Grandberg (gman) for the zipengine module, Manel Ibáñez (Ziggy) for a great IDE, Doug Stastny for the DX9 module and Mark Sibly of course for everything Blitz.

For more help and tutorials that expand on the Docs below visit www.rigzsoft.co.uk

Functions Summary

CopyAttributeNodes Copy a list of attribute nodes.
CopyCompiledEffect Makes a copy of the effect passed to it.
CopyEffect Makes a copy of the effect passed to it.
CopyEmitter Makes a copy of the emitter passed to it.
CopyParticle Copy a particle.
CreateEffect Create a new effect.
CreateEmitter Create a new emitter.
CreateParticle Create a new Emitter.
CreateParticleManager Create a new particle manager.
LoadEffects Load an effects library.
SetLookupFrequency Set the lookup frequency for base, variation and global attributes.
SetLookupFrequencyOvertime Set the lookup frequency for overtime attributes.
UpdateEffect Replace the effect properties, inlcuding emitters with the effect properties you pass to it.

Types Summary

tlAttributeNode Attribute Node type.
tlEffect Effect type - extension of tlEntity.
tlEffectsLibrary Effects library for storing a list of effects and particle images/animations.
tlEmitter Emitter Type - Extension of tlEntity.
tlEmitterArray An attribute array type.
tlParticle Particle Type - extends tlEntity.
tlParticleManager Particle manager for managing a list of effects and all the emitters and particles they contain.

Functions

Function CopyAttributeNodes:TList(e:TList)
ReturnsA new list of attribute nodes.
DescriptionCopy a list of attribute nodes.

Function CopyCompiledEffect:tlEffect(e:tlEffect, ParticleManager:tlParticleManager, copydirectory:Int = False)
ReturnsA new clone of the effect entire, including all emitters and sub effects.
DescriptionMakes a copy of the effect passed to it.
InformationThis copies an effect that uses lookup arrays instead of interpolating attributes in real time. This is a quicker copy funtion then the copy effect, but bear in mind that this will not copy the attribute graph data so you won't be able to use iterpolation mode when updating the particles. See SetUpdateMode.

Function CopyEffect:tlEffect(e:tlEffect, ParticleManager:tlParticleManager, copydirectory:Int = False)
ReturnsA new clone of the effect entire, including all emitters and sub effects.
DescriptionMakes a copy of the effect passed to it.

Function CopyEmitter:tlEmitter(em:tlEmitter, ParticleManager:tlParticleManager)
ReturnsA new clone of the emitter.
DescriptionMakes a copy of the emitter passed to it.
InformationGenerally you will want to copy an effect, which will in turn copy all emitters within it recursively.

Function CopyParticle:tlParticle(e:tlParticle)
Returnsa tlParticle clone of the particle you pass to the function.
DescriptionCopy a particle.

Function CreateEffect:tlEffect(parent:tlEmitter = Null)
ReturnsA new effect with a default set of attributes.
DescriptionCreate a new effect.
InformationPass the parent emitter if it is to be a sub effect.

Function CreateEmitter:tlEmitter()
DescriptionCreate a new emitter.

Function CreateParticle:tlEmitter(parent:tlEffect)
Returnsa New tlEmitter with a default set of attribute values.
DescriptionCreate a new Emitter.

Function CreateParticleManager:tlParticleManager(Particles:Int = tlPARTICLE_LIMIT, Layers:Int = 1)
ReturnsA new tlParticleManager.
DescriptionCreate a new particle manager.
InformationParticle manager maintains a list of effects. See tlParticleManager.

Function LoadEffects:tlEffectsLibrary(filename:String, compile:Int = True)
ReturnsNew tlEffectsLibrary.
DescriptionLoad an effects library.
Information

Pass the url of the library and pass TRUE or FALSE for compile if you want to compile all the effects or not.

Effects can be retrieved from the library using GetEffect


Function SetLookupFrequency(v:Float)
DescriptionSet the lookup frequency for base, variation and global attributes.
InformationDefault is 30 times per second. This means that the lookup tables for attribute nodes will be accurate to 30 milliseconds which should be accurate enough.

Function SetLookupFrequencyOvertime(v:Float)
DescriptionSet the lookup frequency for overtime attributes.
InformationDefault is 1 time per second. This means that the lookup tables for attribute nodes will be accurate to 1 millisecond which is as accuarte as it can be. Higher values will save memory but effect will judder more and be less accurate the higher you go. The memory foot print is very small so 1 should be fine for 99% of apps.

Function UpdateEffect(eff:tlEffect, e:tlEffect)
DescriptionReplace the effect properties, inlcuding emitters with the effect properties you pass to it.
InformationYou can use this to overwrite an effect with another effect.

Types

Type tlAttributeNode
DescriptionAttribute Node type.
Information

An Attribute Node is basically a type used to store effect and emitter attributes. They are in effect nodes on a line graph so that when an effect plays out the attribute value is looked up on the line graph and interpolated if the current time is imbetween 2 attribute nodes. Think of the x-axis of the graph as the time in milliseconds and the y-axis representing the value of the attribute. The line don't have to just be linear either, they can also be curves, see togglecurve and setcurvepoints. The Timeline Particle Editor that comes with this module uses graphs to design the particle effects.

Methods Summary
SetCurvePoints Set the curve points for the emitterchange.
ToggleCurve Toggle whether this attribute node is curved or linear.
Method SetCurvePoints(x0:Float, y0:Float, x1:Float, y1:Float)
DescriptionSet the curve points for the emitterchange.
Informationx0 and y0 are the coordinates of the point to the left of the attribute node, x1 and y1 are the coordinates to the right of the attribute node. Setting these will create a bezier curve. The bezier curves are restricted so that they cannot be drawn so that they loop over or behind the frame of the attribute nodes.
Method ToggleCurve()
DescriptionToggle whether this attribute node is curved or linear.

Type tlEffect Extends tlEntity
DescriptionEffect type - extension of tlEntity.
Information

Effect types are the main containers for emitters and has a set of global attributes that can effect any emitters it stores.

The basic entity structure of an effect is: Effect -> Emitter(s) -> Particle(s)

Both Effect types and Emitter types have a set of attributes that control how the Particles behave over the duration of the effect and over the duration of the particles lifetime. Most of the effects' attributes scale the equivalent attribute of the emitters to enable a more global control of the emitters within the effect.

The value of these attributes is then looked up over the course of the effect using methods that interpolate between values - the equivalent to looking them up on a graph. There are 2 ways of doing this: either by interpolating in realtime, or by pre-compiling into lookup tables stored in arrays for faster performance. There is very little difference in accuracy between the two.

To do this the tlemitterarray is used which stores the value of each attribute overtime for each frame. A frame can be whatever length of time in millisecs you set it to, eg. 30 millisecs. Because there are 2 types of attribute - base attributes and overtime - you can can change the resolution of each one separately. It's more necessary to have a higher resolution for overtime attributes as it becomes much more noticable. The default resolution for overtime attributes is 1 millisec - the most precise resolution possible.

To adjust the resolution of the lookup tables you can call SetLookupFrequency which affects the base attributes resolution and SetLookupFrequencyOvertime to adjust the overtime attributes.

The following table shows each method used to either interpolate in realtime, or compile and lookup the values in an array plus the method used to actually add an attribute value. Click on the add methods for a more detailed description of what that attribute actually does.

Interpolation MethodsEquivalent Compiler MethodsLookup Table MethodsAdd Methods
interpolate_amountcompile_amountget_life addlife
interpolate_lifecompile_lifeget_amount addamount
interpolate_sizexcompile_sizexget_sizex addsizex
interpolate_sizeycompile_sizeyget_sizey addsizey
interpolate_velocitycompile_velocityget_velocity addvelocity
interpolate_weightcompile_weightget_weight addweight
interpolate_spincompile_spinget_spin addspin
interpolate_alphacompile_alphaget_alpha addalpha
interpolate_emissionanglecompile_emissionangleget_emissionangle addemissionangle
interpolate_emissionrangecompile_emissionrangeget_emissionrange addemissionrange
interpolate_widthcompile_widthget_width addwidth
interpolate_heightcompile_heightget_height addheight
interpolate_anglecompile_angleget_angle addangle

Generally most of the values returned by these values are stored temporarily in the following variables for quicker access rather then having to look them up again that frame:

Variable name
currentamount
currentlife
currentsizex
currentsizey
currentvelocity
currentweight
currentspin
currentalpha
currentemissionangle
currentemissionrange
currentwidth
currentheight

To precompile all attributes in the effect and any emitters and sub effects then you can call compile_all

Methods Summary
addalpha Add an alpha attribute node.
addamount Add an amount attribute node.
addangle Add an angle attribute node.
AddEffect Add a new effect to the directory including any sub effects and emitters. Effects are stored using a map and can be retrieved using GetEffect.
addemissionangle Add an emission angle attribute node.
addemissionrange Add an emission range attribute node.
AddEmitter Add a new emitter to the directory. Emitters are stored using a map and can be retrieved using GetEmitter. Generally you don't want to call this at all,
addglobalz Add a globalz attribute node.
addheight Add a height attribute node.
addlife Add a life attribute node.
addsizex Add a size x attribute node.
addsizey Add a size y attribute node.
addspin Add a spin attribute node.
addstretch Add a stretch attribute node.
addvelocity Add a velocity attribute node.
addweight Add a weight attribute node.
addwidth Add a width attribute node.
assignParticleManager Assign Particle Manager.
assignshapes Assigns a shape to each emitter.
compile_all Pre-Compile all attributes.
DoNotTimeout Stop the effect from timing out and be automatically removed.
emittercount Get count of emitters within this effect.
getanimheight Get the Height of the animation.
getanimwidth Get the width of the animation.
getanimx Get the x offset of the effect in the animation.
getanimy Get the y offset of the effect in the animation.
getclass Get class.
getdistancesetbylife Gets whether the distance along the traversed line is determined by the particle age.
GetEffect Retrieve an effect from the directory of the effect.
getEffectlength Get the effect length.
GetEllipseArc get the range in degrees of the arc.
getemissiontype Get the current emission type.
getemitatpoints Get wheter the effect is currently set to emit at points.
GetEmitter Retrieve an emitter from the of the effect.
getendbehaviour Gets the end behaviour for when particles reach the end of the line.
getframeoffset Get the frame offset of the animation.
getframes Get the number of frames in the animation.
gethandlecenter Get whether the effect's handle is automatically set to center.
gethandlex Get the x handle of the effect.
gethandley Get the y handle of the effect.
getlockaspect Returns the lockaspect
getlooped Get whether the animation is looped or not.
getmgx Get the current maximum grid points along the width.
getmgy Get the current maximum grid points along the height.
getparent Get the parent entity of the effect.
getparentEmitter Get the parent emitter of the effect.
getParticlecount Gets the current number of particles spawned by this effects' emitters including any sub effects.
getpath Get the path of the entity.
getreversespawn Gets whether the particles should spawn in the opposite direction.
getseed Get the current random seed value of the animation.
gettraverseedge Get whether particles should traverse the line (if it's a line effect)
getzoom Get the current zoom factor of the animation.
hardkill Hard kill an effect.
hideall Hide all Emitters.
SetAmount Set the Global attribute Amount of the effect.
setanimheight Sets the anim height.
setanimwidth Sets the anim width.
setanimx Sets the x offset.
setanimy Sets the y offset.
SetAreaSize Set the area size of the effect.
setclass Set the class of the Effect.
setdistancesetbylife Set to true to make the distance travelled determined by the life of the particle.
SetEffectAlpha Set the Global attribute Alpha of the effect.
SetEffectAngle Set the Angle of the effect.
SetEffectEmissionRange Set the Global attribute EmissionRange of the effect.
setEffectlength Set the length of the effect.
SetEffectParticleSize Set the Global attribute Sizex of the effect.
SetEllipseArc Set range in degrees of the arc.
SetEmissionAngle Set the Emission Angle of the effect.
setemissiontype Set the emission type.
setemitatpoints Sets whether the effect should emit at points.
setendbehaviour Set the end behaviour of particles traversing a line.
setframeoffset Sets the frame offset of the animation.
setframes Sets the number of frames.
SetGroupParticles Sets the current state of whether spawned particles are added to the particle managers pool, or the emitters own pool. True means that.
sethandlecenter Sets to true to center the handle of the effect.
sethandlex Sets the x handle of the effect.
sethandley Sets the y handle of the effect.
SetLife Set the Global attribute Life of the effect.
SetLineLength Set the line length of the effect.
setlockaspect Sets lockaspect.
setlooped Sets the whehter the animation loops seamlessly.
setmgx Set maximum width grid points.
setmgy Set maximum height grid points.
setname Set Name.
setparentEmitter Set the parent emitter.
setparticlemanager Set the effects particle manager.
setreversespawn Set the order particles spawn.
setseed Sets the random seed for the effect animation.
SetSizex Set the Global attribute Sizex of the effect.
SetSizey Set the Global attribute Sizey of the effect.
setspawndirection This sets the direction particles are spawned.
SetSpin Set the Global attribute Spin of the effect.
SetStretch Set the Global attribute Stretch of the effect.
settraverseedge Set to true for particles to traverse line type effects.
SetVelocity Set the Global attribute velocity of the effect.
SetWeight Set the Global attribute Weight of the effect.
SetZ Set the current zoom level of the effect.
setzoom Sets the zoom of the animation.
showall Show all Emitters.
showone Show one Emitter.
softkill Softly kill an effect.
sortall Sort all attribute lists.
update Updates the effect.
Method addalpha:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an alpha attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

Alpha effects the visibility of all particles within the effect. Global alpha is a scaling factor, so a value of 1 will not effect any of the individual alpha values of particles. A global alpha value of 0.5 will half the value of all particle alpha values. For example if global alpha is 0.5 and a particles alpha is 1 then the particles alpha wil be reduced to 0.5 (0.5*1=0.5). Note that this attribute will instantly effect all particles within the effect.

Method addamount:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an amount attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This scales the number of particles that are spawned per second for all particles within the effect.

Method addangle:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an angle attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

Controls the angle of the effect over the life time of the effect. Particles that are set to Relative will rotate according to the effect, otherwise they will only take into account the effect angle when they spawn.

Method AddEffect(e:tlEffect)
DescriptionAdd a new effect to the directory including any sub effects and emitters. Effects are stored using a map and can be retrieved using GetEffect.
Method addemissionangle:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an emission angle attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

Emission angle determines the direction particles will travel initially when they spawn.

Method addemissionrange:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an emission range attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This specifies the range of direction that particles will spawn and travel. Each degree on the graph represents both sides of the emission angle. So for example if you set it to 10 degrees that means 10 degrees to the left and 10 degrees to the right of the emission angle equally a total arc of 20 degrees. So setting an emission range of 180 degrees will mean particles travel 360 degrees randomly around the emission angle.

Method AddEmitter(e:tlEmitter)
DescriptionAdd a new emitter to the directory. Emitters are stored using a map and can be retrieved using GetEmitter. Generally you don't want to call this at all,
Method addglobalz:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a globalz attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This will affect the overal scale of the effect, effecticvely zooming into or out of the effect

Method addheight:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a height attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

If the effect is of an area or ellipse type this controls the height. If the effect is a line then this control is not used. New particles that are created will only spawn within the area defined here.

Method addlife:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a life attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This scales each particle's lifetime attribute within the effect thus affecting how Long the particles last for. Note that this attribute only effects the lifetime as they are spawned and will not extend or reduce the lifetime of particles already in existence.

Method addsizex:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a size x attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This scales each particle's width attribute within the effect thus controlling the overall width of the particle.

If lockaspect is set to true then this attribute is used to control the particles height aswell so it scales uniformly

Method addsizey:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a size y attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This scales each particle's height attribute within the effect thus controlling the overall height of the particle.

if lockaspect is set to true then this attribute will not have any effect.

Method addspin:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a spin attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

Global spin scales each particle's spin attribute within the effect thus controlling how fast the particle spins. Note that this attribute will instantly effect all particles within the effect.

Method addstretch:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a stretch attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This will scale the stretch overtime attribute of all particles within the effect.

Method addvelocity:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a velocity attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This scales each particle's basespeed attribute within the effect thus controlling fast the particle can travel. Note that this attribute only effects the base speed of the particle therefore only effecting newly spawned particles. It does not effect the partciles over their lifetime.

Method addweight:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a weight attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This scales each particle's baseweigth attribute within the effect thus controlling how much the particle is effected by gravity. Note that this attribute only effects the base weight of the particle therefore only effecting newly spawned particles. It does not effect the partciles over their lifetime.

Method addwidth:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a width attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

If the effect is of an area or ellipse type this controls the width. If the effect is a line then this controls the line length. New particles that are created will only spawn within the area defined here.

Method assignParticleManager(partman:tlParticleManager)
DescriptionAssign Particle Manager.
InformationSets the Particle Manager that this effect is managed by. See tlParticleManager.
Method assignshapes(shapes:TList)
DescriptionAssigns a shape to each emitter.
Information

Recursively goes through each emitter within this effect and any sub effects and assigns a shape to each emitter.

The list passed to the method should contain the list of shapes, which will then be searched using the name stored in emitter.image.name and assigned if one is found, Otherwsie null is assign to the shape. Generally used only when the effects library is loaded.

Method compile_all()
DescriptionPre-Compile all attributes.
InformationIn order to use look-up arrays to access attribute values over the course of the effects life you need to compile all of the attribute values into an array. This method will compile all of them together in one go including all of it children emiters and any sub effects and so on.
Method DoNotTimeout(v:Int = True)
DescriptionStop the effect from timing out and be automatically removed.
InformationBy default, if the effect has no particles, it will timeout and destroy itself after a certain amount of time as dictated by the particle manager it belongs to. Call this method to stop the process from happening. Bear in mind that if you do this you will have to destroy the effect yourself, either by calling Destroy, Hardkill ir Softkill. This method propergates to all subeffects as well. For best results this method should called when the effect is created before it starts spawning particles.
Method emittercount:Int()
ReturnsNumber of emitters.
DescriptionGet count of emitters within this effect.
InformationUse this to find out how many emitters the effect has.
Method getanimheight:Int()
DescriptionGet the Height of the animation.
Method getanimwidth:Int()
DescriptionGet the width of the animation.
Method getanimx:Int()
DescriptionGet the x offset of the effect in the animation.
Method getanimy:Int()
DescriptionGet the y offset of the effect in the animation.
Method getclass:Int()
ReturnsThe current class of the effect - tlAREA_EFFECT, tlLINE_EFFECT, tlELLIPSE_EFFECT or tlPOINT_EFFECT.
DescriptionGet class.
Method getdistancesetbylife:Int()
ReturnsEither TRUE or FALSE.
DescriptionGets whether the distance along the traversed line is determined by the particle age.
Method GetEffect:tlEffect(name:String)
ReturnstlEffect.
DescriptionRetrieve an effect from the directory of the effect.
Information

Use this to get an effect from the effect directory by passing the name of the effect you want. Example:

local explosion:tlEffect=MyEffectsLibrary.Geteffect("explosion")

All effects and emitters are stored using a directory like path structure so to get at sub effects you can do:

local explosion:tlEffect=MyEffectsLibrary.Geteffect("Effect/Emitter/Sub Effect/Another Emitter/A deeper sub effect")

Note that you should always use forward slashes.

Method getEffectlength:Int()
ReturnsLength in millisecs.
DescriptionGet the effect length.
Method GetEllipseArc:Int()
Descriptionget the range in degrees of the arc.
Informationsee SetEllipseArc.
Method getemissiontype:Int()
ReturnsThe current emission type: tlEMISSION_INWARDS, tlEMISSION_OUTWARDS, tlEMISSION_SPECIFIED, tlEMISSION_IN_AND_OUT.
DescriptionGet the current emission type.
Method getemitatpoints:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet wheter the effect is currently set to emit at points.
Method GetEmitter:tlEmitter(name:String)
ReturnstlEmitter.
DescriptionRetrieve an emitter from the of the effect.
Information< p > Use this To get an emitter from the effect directory by passing the name of the emitter you want. All effects And emitters are stored using a map with a directory like path structure. So retrieving an emitter called blast wave inside an effect called explosion would be done like so:

local blastwave:tlemitter=MyEffectsLibrary.GetEmitter("explosion/blast wave")

Note that you should always use forward slashes.

Method getendbehaviour:Int()
ReturnsEither tlEND_KILL, tlEND_LOOPAROUND, tlEND_LETFREE.
DescriptionGets the end behaviour for when particles reach the end of the line.
Method getframeoffset:Int()
DescriptionGet the frame offset of the animation.
Method getframes:Int()
DescriptionGet the number of frames in the animation.
Method gethandlecenter:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether the effect's handle is automatically set to center.
Method gethandlex:Int()
DescriptionGet the x handle of the effect.
Method gethandley:Int()
DescriptionGet the y handle of the effect.
Method getlockaspect:Int()
ReturnsEither TRUE or FALSE.
DescriptionReturns the lockaspect
Method getlooped:Int()
Returnseither TRUE or FALSE.
DescriptionGet whether the animation is looped or not.
Method getmgx:Int()
DescriptionGet the current maximum grid points along the width.
Method getmgy:Int()
DescriptionGet the current maximum grid points along the height.
Method getparent:tlEntity()
DescriptionGet the parent entity of the effect.
Method getparentEmitter:tlEmitter()
DescriptionGet the parent emitter of the effect.
Method getParticlecount:Int()
DescriptionGets the current number of particles spawned by this effects' emitters including any sub effects.
Method getpath:String()
DescriptionGet the path of the entity.
Informationthe path will be the address of where the entity is within the hierarchy of parent and child entities.
Method getreversespawn:Int()
ReturnsEither TRUE or FALSE.
DescriptionGets whether the particles should spawn in the opposite direction.
Method getseed:Int()
DescriptionGet the current random seed value of the animation.
Method gettraverseedge:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether particles should traverse the line (if it's a line effect)
Method getzoom:Float()
DescriptionGet the current zoom factor of the animation.
Method hardkill()
DescriptionHard kill an effect.
Informationimmediatley kills an effect by destroying all particles created by it.
Method hideall()
DescriptionHide all Emitters.
InformationSets all emitters to hidden so that they will no longer be rendered. This also applies to any sub effects and their emitters.
Method SetAmount(amount:Float)
DescriptionSet the Global attribute Amount of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Amount.
Method setanimheight(v:Int)
DescriptionSets the anim height.
InformationCurrently only relevent to the Timeline Particles editor.
Method setanimwidth(v:Int)
DescriptionSets the anim width.
InformationCurrently only relevent to the Timeline Particles editor.
Method setanimx(v:Int)
DescriptionSets the x offset.
InformationCurrently only relevent to the Timeline Particles editor.
Method setanimy(v:Int)
DescriptionSets the y offset.
InformationCurrently only relevent to the Timeline Particles editor.
Method SetAreaSize(Width:Float, Height:Float)
DescriptionSet the area size of the effect.
InformationFor area and ellipse effects, use this function to override the graph and set the width and height of the area to whatever you want.
Method setclass(v:Int)
DescriptionSet the class of the Effect.
Information

Sets the effect to one of 4 types - point, area, ellipse and line. To set one of these use one of the 4 corresponding consts: tlPOINT_EFFECT, tlAREA_EFFECT, tlLINE_EFFECT, tlELLIPSE_EFFECT

Method setdistancesetbylife(v:Int)
DescriptionSet to true to make the distance travelled determined by the life of the particle.
InformationWhen traverseedge is set to true and endbehaviour is set to true then the distance travelled along the line will be determined by the age of the particle.
Method SetEffectAlpha(Alpha:Float)
DescriptionSet the Global attribute Alpha of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Alpha.
Method SetEffectAngle(_angle:Float)
DescriptionSet the Angle of the effect.
InformationThis overides the whatever angle is set on the graph and sets the angle of the effect.
Method SetEffectEmissionRange(EmissionRange:Float)
DescriptionSet the Global attribute EmissionRange of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute EmissionRange.
Method setEffectlength(v:Int)
DescriptionSet the length of the effect.
InformationEffects can be looped by setting the effect length. Just pass it the length in milliseconds that you want it to loop by or set to 0 if you don't want the effect to loop.
Method SetEffectParticleSize(Sizex:Float, Sizey:Float)
DescriptionSet the Global attribute Sizex of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Sizex and sizey.
Method SetEllipseArc(degrees:Float)
DescriptionSet range in degrees of the arc.
InformationWhen an effect uses an ellipse as its effect type, you can adjust how far round the ellipse particles will spawn by setting the ellipse arc. 360 degrees will spawn around the full amount.
Method SetEmissionAngle(angle:Float)
DescriptionSet the Emission Angle of the effect.
InformationThis overides whatever angle is set on the graph and sets the emission angle of the effect. This won't effect emitters that have UseEffectEmission set to FALSE.
Method setemissiontype(v:Int)
DescriptionSet the emission type.
Information

In area, line and ellipse effects the emission type determines the direction that the particles travel once spawned. Use the following consts to determine the direction:

tlEMISSION_INWARDS: Particles will emit towards the handle of the effect.
tlEMISSION_OUTWARDS: Particles will emit away from the handle of the effect.
tlEMISSION_SPECIFIED: Particles will emit in the direction specified by the emission_angle and emission_range attributes.
tlEMISSION_IN_AND_OUT: Particles will alternative between emitting towards and away from the handle of the effect.

Method setemitatpoints(v:Int)
DescriptionSets whether the effect should emit at points.
InformationIf set to true then the particles within the effect will emit from evenly spaced points with the area, line or ellipse. The number of points is determined by mgx and mgy. The value is not applicable to point effects.
Method setendbehaviour(v:Int)
DescriptionSet the end behaviour of particles traversing a line.
Information

If an effect if set so that particles traverse the edge of the line, then this makes the particles behave in one of 3 ways when they reach the end of the line. By passing it either of the following const they can:

tlEND_LOOPAROUND: The particles will loop back round to the beginning of the line.
tlEND_KILL: The particles will be killed even if they haven't reached the end of their lifetimes yet.
tlLET_FREE: The particles will be free to continue on their merry way.

Method setframeoffset(v:Int)
DescriptionSets the frame offset of the animation.
InformationCurrently only relevent to the Timeline Particles editor.
Method setframes(v:Int)
DescriptionSets the number of frames.
InformationCurrently only relevent to the Timeline Particles editor.
Method SetGroupParticles(v:Int)
DescriptionSets the current state of whether spawned particles are added to the particle managers pool, or the emitters own pool. True means that.
Method sethandlecenter(v:Int)
DescriptionSets to true to center the handle of the effect.
InformationIf set to true then then position of the handle is automatically set to to the center of the effect.
Method sethandlex(v:Int)
DescriptionSets the x handle of the effect.
InformationThis effects where the effect will be placed on screen. A value of 0 represents the left of the effect.
Method sethandley(v:Int)
DescriptionSets the y handle of the effect.
InformationThis effects where the effect will be placed on screen. A value of 0 represents the top of the effect.
Method SetLife(life:Float)
DescriptionSet the Global attribute Life of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Life.
Method SetLineLength(Length:Float)
DescriptionSet the line length of the effect.
InformationFor line effects, use this function to override the graph and set the length of the line to whatever you want.
Method setlockaspect(v:Int)
DescriptionSets lockaspect.
Information

Set to true to make the size of particles scale uniformly

Method setlooped(v:Int)
DescriptionSets the whehter the animation loops seamlessly.
InformationCurrently only relevent to the Timeline Particles editor.
Method setmgx(v:Int)
DescriptionSet maximum width grid points.
InformationIn area and ellipse effects this value represents the number of grid points along the width, in the case of area and line effect, or around the circumference, in the case of ellipses.
Method setmgy(v:Int)
DescriptionSet maximum height grid points.
InformationIn area effects this value represents the number of grid points along the height, it has no relevence for other effect types.
Method setname(v:String)
DescriptionSet Name.
InformationSets the name of the effect.
Method setparentEmitter(v:tlEmitter)
DescriptionSet the parent emitter.
InformationEffects can be sub effects within effects. To do this emitters can store a list of effects that they attach to particles they spawn. This sets the emitter that the effect is parented to.
Method setparticlemanager(v:tlParticleManager)
DescriptionSet the effects particle manager.
InformationEvery effect needs a particle manager. For more info see tlParticleManager.
Method setreversespawn(v:Int)
DescriptionSet the order particles spawn.
InformationA vlaue of true means that in area, line and ellipse effects, particles will spawn from right to left or anti-clockwise.
Method setseed(v:Int)
DescriptionSets the random seed for the effect animation.
InformationCurrently only relevent to the Timeline Particles editor.
Method SetSizex(Sizex:Float)
DescriptionSet the Global attribute Sizex of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Sizex.
Method SetSizey(Sizey:Float)
DescriptionSet the Global attribute Sizey of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Sizey.
Method setspawndirection()
DescriptionThis sets the direction particles are spawned.
Informationtheres no need to call this, as its called internally by the emitter depending on the reverse spawn flag. see setreversespawn.
Method SetSpin(spin:Float)
DescriptionSet the Global attribute Spin of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Spin.
Method SetStretch(v:Float)
DescriptionSet the Global attribute Stretch of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Stretch.
Method settraverseedge(v:Int)
DescriptionSet to true for particles to traverse line type effects.
InformationOnly applying to line effects, setting this to true makes the particles travel along the length of the line always remaining relative to it.
Method SetVelocity(velocity:Float)
DescriptionSet the Global attribute velocity of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute velocity.
Method SetWeight(Weight:Float)
DescriptionSet the Global attribute Weight of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Weight.
Method SetZ(v:Float)
DescriptionSet the current zoom level of the effect.
InformationThis overides the graph the effect uses to set the Global Attribute Global Zoom.
Method setzoom(v:Float)
DescriptionSets the zoom of the animation.
InformationCurrently only relevent to the Timeline Particles editor.
Method showall()
DescriptionShow all Emitters.
InformationSets all emitters to visible so that they will be rendered. This also applies to any sub effects and their emitters.
Method showone(emm:tlEmitter)
DescriptionShow one Emitter.
InformationSets the emitter passed to the method to visible so that it will be rendered, all the other emitters are made invisible.
Method softkill()
DescriptionSoftly kill an effect.
InformationCall this to kill an effect by stopping it from spawning any more particles. This will make the effect slowly die about as any remaining particles cease to exist. Any single particles are converted to one shot particles.
Method sortall()
DescriptionSort all attribute lists.
InformationSorts all the graph nodes into the proper order for every effect attribute.
Method update()
DescriptionUpdates the effect.
InformationCall this once every frame to update the effect. Updating effects is handled by the Particle Manager unless you want to manage things on your own.

Type tlEffectsLibrary
DescriptionEffects library for storing a list of effects and particle images/animations.
InformationWhen using LoadEffects, all the effects and images that go with them are stored in this type.
Methods Summary
AddEffect Add a new effect to the library including any sub effects and emitters. Effects are stored using a tMap and can be retrieved using GetEffect.
AddEmitter Add a new emitter to the library. Emitters are stored using a map and can be retrieved using GetEmitter. Generally you don't want to call this at all unless.
ClearAll Clear all effects in the library.
Create Create an effect library for storing your effects.
GetEffect Retrieve an effect from the library.
GetEmitter Retrieve an emitter from the library.
Method AddEffect(e:tlEffect)
DescriptionAdd a new effect to the library including any sub effects and emitters. Effects are stored using a tMap and can be retrieved using GetEffect.
Method AddEmitter(e:tlEmitter)
DescriptionAdd a new emitter to the library. Emitters are stored using a map and can be retrieved using GetEmitter. Generally you don't want to call this at all unless.
Method ClearAll()
DescriptionClear all effects in the library.
InformationUse this to empty the library of all effects and shapes.
Method Create:tlEffectsLibrary()
ReturnsA new tlEffectsLibrary.
DescriptionCreate an effect library for storing your effects.
Method GetEffect:tlEffect(name:String)
ReturnstlEffect.
DescriptionRetrieve an effect from the library.
Information

Use this to get an effect from the library by passing the name of the effect you want. Example:

local explosion:tlEffect=MyEffectsLibrary.Geteffect("explosion")

All effects and emitters are stored using a directory like path structure so to get at sub effects you can do:

local explosion:tlEffect=MyEffectsLibrary.Geteffect("Effect/Emitter/Sub Effect/Another Emitter/A deeper sub effect")

Note that you should always use forward slashes.

Method GetEmitter:tlEmitter(name:String)
ReturnstlEmitter.
DescriptionRetrieve an emitter from the library.
Information

Use this To get an emitter from the library by passing the name of the emitter you want. All effects And emitters are stored using a map with a directory like path structure. So retrieving an emitter called blast wave inside an effect called explosion would be done like so:

local blastwave:tlemitter=MyEffectsLibrary.GetEmitter("explosion/blast wave")

Note that you should always use forward slashes.


Type tlEmitter Extends tlEntity
DescriptionEmitter Type - Extension of tlEntity.
Information

An emitter type is an entity whose sole purpose is to spawn particles. Like the effect type it too has number of attributes that can tell the particles that it spawns how to move, orientate and scale themselves on screen to create the effects.

The attributes an emitter has can be put into a few different categories:

Base Attributes

Base attributes set the base level that life overtime values will scale to. The x axis of the graph represents the time in seconds the the effect has been running for. So for example you may set the velocity to 200 for at the start of the effect then have it slowly reduce to 0 over 5 seconds of the effect running.

Life

This attribute determines how long the particle will live before before ceasing to exist. You can plot points on the graph so that the life of particles will vary over the lifetime of the effect.

Amount

This controls how many particles per second that the emitter will spawn at that point in time of the effect running.

Size

Size controls the base level that the size over-life attributes scale to. By right clicking the particle attributes list you can toggle "Uniform Size" which will enable the size attribute to split into width and height attributes so that these can be changed independantly of each other.

Velocity

This controls the base speed of the particles being spawned that the velocity over-life attributes scale to.

Spin

Spin controls the base speed with which particles rotate in either direction and determines what the spin over-life scales too.

Weight

This controls the base weight of the particle that the weight over-life attribute is scaled to.

Variation Attributes

Variation attributes represent random values that are added to the base values in order to add some variation and unpredicatability to the particles behaviour.

Life Variation

This will add a random amount of seconds onto the base attribute of life so that particles that spawn will vary in the amount of time they stay alive.

Amount Variation

This will apply variation to the base amount attribute so that the amount of particles spawned over the effect's life time will vary.

Size Variation

Applies a random value onto the base size so the particles spawned will vary in size.

Velocitiy Variation

This will vary the base velocity of the particle based by the amount you plot on the graph so that partcicles will spawn and move with varying speeds.

Spin Variation

This will vary the speed at which the particles spawned will rotate.

Weight Variation

Applies a random amount of weight onto the base weight of the particles that are spawned.

Motion Randomness

Motion randomness does not vary any of the base values, but it does dictate to what degree the particle will move about in a random fashion. Motion randomness effects the speed and direction of the particle so the higher this value the more erratically the particles will move about.

Overtime Attributes

These attribute control how the particle behaves over the lifetime of the particle. The x axis of the graph represents the life time of the particle so you can control exactly how the particle behaves at each stage of its life. The y axis represents a percentage of the base value set in the Base Attributes and Variation Attrbutes. So if for example you have velocity set at 100 and the velocity overtime is set to 0.5 then the particle will therefore be travelling at half it's speed; 50 pixels per second.

Alpha Overtime

This doesn't actually scale any base attribute, it simply controls the alpha value of the particle, or how visible the particle is. Values should range from 0 to 1.

Size Overtime

This enables you to control the size of the particle over its life time by scaling the base size attribute.

Velocity Overtime

This enables you to control how fast the the partcle travels over its life time by scaling the base velocity attribute.

Spin Overtime

This controls the speed with which the particle spins by scaling the base spin attribute.

Weight Overtime

This controls the weight overtime of the particle by scaling the base weight attribute.

Direction Overtime

This dictates the direction that the particle travels in over its lifetime.

Motion Randomness Overtime

This scales the Motion Randomness attribute over the particles lifetime so you can finely tune how erratically the particle moves.

Frame Rate

If the particle is set to animate then you can use this attribute to control how fast is animates over the lifetime of the particle.

Velocity Adjuster

This attribute scales the speed of all particles currently in existence for a more global control

Adding and retrieving attribute values

This is all handled by the effect, emitter and particle update methods so theres not much need to worry about these methods but here is some info about how this is achieved.

To add a value to each of these attributes use the corresponding add method ie., addlife

As in the effect type the values of attributes are looked up using interpolation or pre compiled in arrays. The following table lists all the interpolation methods and their equivalent compiler methods, look-up methods and add methdods for adding new attribute values.

Interpolation MethodsEquivalent Compiler MethodsLookup Table MethodsAdd Methods
interpolate_amountcompile_amountget_amount addamount
interpolate_lifecompile_lifeget_life addlife
interpolate_sizexcompile_sizexget_sizex addsizex
interpolate_sizeycompile_sizeyget_sizey addsizey
interpolate_basespeedcompile_basespeedget_basespeed addbasespeed
interpolate_baseweightcompile_baseweightget_baseweight addbaseweight
interpolate_basespincompile_basespinget_basespin addbasespin
interpolate_emissionanglecompile_emissionangleget_emissionangle addemissionangle
interpolate_emissionrangecompile_emissionrangeget_emissionrange addemissionrange
interpolate_velvariationcompile_velvariationget_velvariation addvelvariation
interpolate_weightvariationcompile_weightvariationget_weightvariation addweightvariation
interpolate_lifevariationcompile_lifevariationget_lifevariation addlifevariation
interpolate_amountvariationcompile_amountvariationget_amountvariation addamountvariation
interpolate_sizexvariationcompile_sizexvariationget_sizexvariation addsizexvariation
interpolate_sizeyvariationcompile_sizeyvariationget_sizeyvariation addsizeyvariation
interpolate_spinvariationcompile_spinvariationget_spinvariation addspinvariation
interpolate_directionvariationcompile_directionvariationget_directionvariation adddirectionvariation
interpolate_alphacompile_alphaget_alpha addalpha
interpolate_rcompile_rget_r addr
interpolate_gcompile_gget_g addg
interpolate_bcompile_bget_b addb
interpolate_scalexcompile_scalexget_scalex addscalex
interpolate_scaleycompile_scaleyget_scaley addscaley
interpolate_spincompile_spinget_spin addspin
interpolate_velocitycompile_velocityget_velocity addvelocity
interpolate_weightcompile_weightget_weight addweight
interpolate_directioncompile_directionget_direction adddirection
interpolate_directionvariationotcompile_directionvariationotget_directionvariationot adddirectionvariationot
interpolate_frameratecompile_framerateget_framerate addframerate
interpolate_globalvelocitycompile_globalvelocityget_globalvelocity addglobalvelocity

There are also a number of properties that controll further how the particles look, how they're spawned and how they're drawn:

Property
setimage
setframe
setangleoffset
setuniform
setsplatter
setangletype
setuseeffectemission
setsingleparticle
setrandomcolor
setzlayer
setanimate
setrandomstartframe
setanimationdirection
setcolorrepeat
setalpharepeat
setoneshot
sethandlecenter
setParticlesrelative
settweenspawns
Methods Summary
addalpha Add an alpha attribute node.
addamount Add a Base amount attribute node.
addamountvariation Add an amount variation attribute node.
addas Currently unused, will probably be deleted at some point.
addb Add a Colour Blue attribute node.
addbasespeed Add a Base Speed attribute node.
addbasespin Add a Base spin attribute node.
addbaseweight Add a Base weight attribute node.
adddirection Add a direction attribute node.
adddirectionvariation Add a direction variation attribute node.
adddirectionvariationot Add a direction variaiton overtime attribute node.
addeffect Add an effect to the emitters list of effects.
addemissionangle Add an emission angle attribute node.
addemissionrange Add an emission range attribute node.
addframerate Add a framerate overtime attribute node.
addg Add a Colour Green attribute node.
addglobalvelocity Add a global velocity attribute node.
addlife Add a Base life attribute node.
addlifevariation Add a life variation attribute node.
addr Add a Colour Red attribute node.
addscalex Add a scale x attribute node.
addscaley Add a scale y attribute node.
addsizex Add a Size x attribute node.
addsizexvariation Add a Size x variation attribute node.
addsizey Add a Size y attribute node.
addsizeyvariation Add a Size y variation attribute node.
addspin Add a spin attribute node.
addspinvariation Add a spin variation attribute node.
addsplatter Add a splatter overtime attribute node.
addstretch Add a stretch overtime attribute node.
addvelocity Add a Velocity attribute node.
addvelvariation Add a velocity variation attribute node.
addweight Add a weight attribute node.
addweightvariation Add a weight variation attribute node.
ChangeDob Change the dob of the emitter. dob being date of birth, or time it was created.
controlparticle Control a particle.
drawcurrentframe Draws the current image frame.
getalpharepeat Get the number of times the alpha cycles over the lifetime of the particles spawned by this emitter.
getangleoffset Get the current angle offset used by angletype (see setangletype)
getanglerelative Get whether particles spawned will have there angle relative to the parent.
getangletype Get the current angletype for particles spawned by this emitter.
getanimate Get whether this emitter spawns particles that animate.
getanimationdirection Get the current animation direction.
getcolorrepeat Get the number of times the colour cycles over the lifetime of the particles spawned by this emitter.
getframe Get the animation frame of the tAnimImage used by the emitter.
getgroupparticles Returns the current state of whether spawned particles are added to the particle managers pool, or the emitters own pool. True means that.
gethandlecenter Get whether the handle of the particles spawned by this emitter are set to the center.
getimage Get the tAnimImage currently used by the emitter.
getlockangle Get whether particles spawned are having their angles locked to direction.
getonce Returns the current state of whether spawned particles playback the animation just once.
getoneshot Get whether this emitter spawns a one shot particle (see setoneshot)
getparentEffect Get the current parent effect.
getParticlesrelative Get whether the particles spawned by this emitter remain relative to the containg effect.
getpath Get the path of the entity.
getrandomcolor Get whether the emitter chooses a random colour for the particles it spawns.
getrandomstartframe Get whether the emitter chooses a random start frame for the particles it spawns.
getsingleparticle Find out if the emitter spawns a single particle.
gettweenspawns Get whether particles are being spawned from the old effect coordinates to the new.
getuniform Get whether the particles spawned by this emitter scale uniformally.
getuseeffectemission Get whether the emitter uses the effect emission instead of its own.
getvisible Get the visibility status of the emitter.
getzlayer Get the current z layer of the emitter.
hideall Hide all Emitters.
nextframe Cycle forward through the image frames.
previousframe Cycle backwards throught the image frames.
setalpharepeat Set to the number of times the alpha of the particle should cycle within the particle lifetime.
setangleoffset Set the angle offset or variation.
setanglerelative Set to TRUE to make th particles spawned have their angle of rotation relative to the parent effect.
setangletype Set the angle type.
setanimate Set whether the particle should animate.
setanimationdirection Set the direction the animation plays in.
setcolorrepeat Set to the number of times the colour should cycle within the particle lifetime.
setframe Set the image frame.
SetGroupParticles Sets the current state of whether spawned particles are added to the particle managers pool, or the emitters own pool. True means that.
sethandlecenter Set the handle of the particle to its center.
setimage Set image.
setlockangle Set to TRUE to make th particles spawned have their angle of rotation locked to direction.
setonce Set to TRUE to make the particles spawned playback the animation just once.
setoneshot Make a particle a one shot particle or not.
setparentEffect Set Parent Effect.
setParticlesrelative Set wheter the particles and emitter remain relative to the effect.
SetRadiusCalculate Set the Radius Calculate value for this tlEntity object.
setrandomcolor Sets whether the particle chooses random colour from the colour attributes.
setrandomstartframe Set the particles to spawn with a random frame.
setsingleparticle Set Single Particle.
settweenspawns Set to TRUE for particles to spawn imbetween th effects old and new coordinates.
setuniform Set Uniform.
setuseeffectemission Set Use effect emission.
setvisible Set to FALSE to stop drawing the particles this emitter spawns.
setzlayer Set the z layer.
showall Show all Emitters.
sortall Sort all attribute lists.
update Update the emitter.
updatechildren Updates all the particles this emitter has spawned.
updatespawns Spawns a new lot of particles if necessary and assign all properties and attributes to the particle.
Method addalpha:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an alpha attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for adjust the visibility of the particle over its lifetime where 1 is opaque and 0 is transparent.

Method addamount:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Base amount attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting how many particles are spawned per second by the emitter.

Method addamountvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an amount variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for varying how many particles are spawned per second by the emitter. So if amount is 50, and the amountvariation is 10 then the amount spawned can vary from 50-60.

Method addas:tlAttributeNode(f:Float, v:Float)
DescriptionCurrently unused, will probably be deleted at some point.
Method addb:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Colour Blue attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for effecting the Blue colour channel of the particle. Values can range from 0 to 255.

Method addbasespeed:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Base Speed attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting the base speed of the particle. Speed is then scaled over the lifetime of the particle using the Overtime Attribute Velocity

Method addbasespin:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Base spin attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting the base spin of the particle which effects the speed of rotation of the particle. You can also effect the direction that the particle spins by using values less then 0. Spin is then scaled over the lifetime of the particle using the Overtime Attribute spin

Method addbaseweight:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Base weight attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting the base weight of the particle. weight is then scaled over the lifetime of the particle using the Overtime Attribute weight

Method adddirection:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a direction attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for effecting the direction the particle travels in over the lifetime of the particle.

Method adddirectionvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a direction variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for giving particles a degree of motion randomness. This value is further scaled by directionvariationot

Method adddirectionvariationot:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a direction variaiton overtime attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute scaling the direction variation over the lifetime of the particle. This gives the particle a motion randomness effecting its direction and speed at vary degrees of variation.

Method addeffect(e:tlEffect)
DescriptionAdd an effect to the emitters list of effects.
InformationEffects that are in the effects list are basically sub effects that are added to any particles that this emitter spawns which in turn should contain their own emitters that spawn more particles and so on.

Method addemissionangle:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an emission angle attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This attribute controls the direction newly spawned particles travel in but only if useeffectemission is false.

Method addemissionrange:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd an emission range attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This attribute controls the random range newly spawned particles travel in but only if useeffectemission is false. So if the emission range is 45 degrees and the emission angle is 0 then the range can vary from -45 to 45 degrees (or 315-45 degrees). emission range can be passed any value from 0-180

Method addframerate:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a framerate overtime attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for controlling the framerate of particles that have more then one frame of animation. This attribute is only relevant if animate is true.

Method addg:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Colour Green attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for effecting the Green colour channel of the particle. Values can range from 0 to 255.

Method addglobalvelocity:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a global velocity attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This attribute effects all particles currently in existance that the emitter has spawned. It will instantly scale the velocity of all particles essentially controlling their speed globally.

Method addlife:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Base life attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting how long the particle lives for in milliseconds.

Method addlifevariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a life variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for varying how long the particle lives for. So if life is 5000, and the lifevariation is 1000 then the life can vary from 4000-6000 milliseconds.

Method addr:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Colour Red attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for effecting the red colour channel of the particle. Values can range from 0 to 255.

Method addscalex:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a scale x attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute, meaning it is a scaling factor for the equivalent Base Attribute - in this case sizex. This enables you to control the width of the particle over its life time by scaling the sizex attribute. If uniform is set to true then this also controls the height of teh particle aswell

So for example, if you pass addscalex(0.5,2), this will tell the particle to be twice it's base width (sizex) halfway through its life.

Method addscaley:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a scale y attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute, meaning it is a scaling factor for the equivalent Base Attribute - in this case sizex. This enables you to control the width of the particle over its life time by scaling the sizex attribute. If uniform is set to true then this attribute is ignored and only scalex is used

So for example, if you pass addscaley(0.5,2), this will tell the particle to be twice it's base height (sizey) halfway through its life.

Method addsizex:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Size x attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting the base width of the particles.This value is Then scaled using the Overtime Attribute Scalex. If uniform is true then this attribute also sets the base height.

Method addsizexvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Size x variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for effecting how much the base sizex attribute varies. So if sizex is 100, and the sizexvariation is 50 then the base particle width can cary from 100-150.

Method addsizey:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Size y attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Base Attribute for setting the base height of the particles. This value is then scaled using the Overtime Attribute Scaley. If uniform is true then this attribute is ignored.

Method addsizeyvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Size y variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for effecting how much the base sizey attribute varies. So if sizey is 100, and the sizeyvariation is 50 then the base particle height can vary from 100-150. This attribute is ignores if uniform is true.

Method addspin:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a spin attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for scaling the base spin of the particle.

Method addspinvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a spin variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for effecting how much the base spin attribute varies. So if basespin is 50, and the spinvariation is 25 then the base particle spin can vary from 25-75 degrees per second.

Method addsplatter:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a splatter overtime attribute node.
Information

Pass the time in milliseconds (f) and the value (v)

This will control how close to the point the particle will spawn. Higher values mean the particle will appear randomnly around the point of spawning.

Method addstretch:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a stretch overtime attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for controlling how much the particle stretches depending on the speed it is travelling.

Method addvelocity:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a Velocity attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for scaling the base speed of the particle. For example if you wanted a particle to start off travelling fast and slow down to a stop over the course of its life time you would add the following attribute values:

addbasespeed(0,200)
addvelocity(0,1)
addvelocity(1,0)

This would mean that the particle starts out travelling at 200 pixels per second which reduces to 0 over the particles lifetime.

Method addvelvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a velocity variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for effecting how much the base speed attribute varies. So if basespeed is 100, and the velvariation is 50 then the base particle speed can vary from 50-150 pixels per second.

Method addweight:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a weight attribute node.
Information

Pass the method a value between 0 and 1 representing the percentage of the lifetime of the particle (f) and the value (v)

This is an Overtime Attribute for scaling the base weight of the particle.

Method addweightvariation:tlAttributeNode(f:Float, v:Float)
ReturnsEmitter change object.
DescriptionAdd a weight variation attribute node.
Information

Pass the method the time in millisecs (f) and the value (v)

This is a Variation Attribute for effecting how much the base weight attribute varies. So if weight is 20, and the weightvariation is 10 then the base particle width can cary from 10-30.

Method ChangeDob(_DoB:Float)
DescriptionChange the dob of the emitter. dob being date of birth, or time it was created.
InformationThis will also change the dob of any effects the emitter contains. This is more of an internal method used by the tlParticleManager method AddPreLoadedEffect.
Method controlparticle(e:tlParticle)
DescriptionControl a particle.
InformationAny particle spawned by an emitter is controlled by it. When a particle is updated it calls this method to find out how it should behave.
Method drawcurrentframe(x:Float = 0, y:Float = 0, w:Float = 128, h:Float = 128)
DescriptionDraws the current image frame.
InformationDraws on screen the current frame of teh image the emitter uses to create particles with. Mainly just a Timeline Particles Editor method.
Method getalpharepeat:Int()
DescriptionGet the number of times the alpha cycles over the lifetime of the particles spawned by this emitter.
Method getangleoffset:Int()
DescriptionGet the current angle offset used by angletype (see setangletype)
Method getanglerelative:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether particles spawned will have there angle relative to the parent.
Method getangletype:Int()
Returnseither tlANGLE_ALIGN, tlANGLE_RANDOM or tlANGLE_SPECIFY.
DescriptionGet the current angletype for particles spawned by this emitter.
Method getanimate:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether this emitter spawns particles that animate.
Method getanimationdirection:Int()
ReturnsEither -1 for reverse playback or 1 for normal playback for particles spawned by this emitter.
DescriptionGet the current animation direction.
Method getcolorrepeat:Int()
DescriptionGet the number of times the colour cycles over the lifetime of the particles spawned by this emitter.
Method getframe:Int()
DescriptionGet the animation frame of the tAnimImage used by the emitter.
Method getgroupparticles:Int()
DescriptionReturns the current state of whether spawned particles are added to the particle managers pool, or the emitters own pool. True means that.
Method gethandlecenter:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether the handle of the particles spawned by this emitter are set to the center.
Method getimage:TAnimImage()
ReturnstAnimimage.
DescriptionGet the tAnimImage currently used by the emitter.
Method getlockangle:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether particles spawned are having their angles locked to direction.
Method getonce:Int()
DescriptionReturns the current state of whether spawned particles playback the animation just once.
Method getoneshot:Int()
Returnseither TRUE or FALSE.
DescriptionGet whether this emitter spawns a one shot particle (see setoneshot)
Method getparentEffect:tlEffect()
ReturnstlEffect.
DescriptionGet the current parent effect.
Method getParticlesrelative:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether the particles spawned by this emitter remain relative to the containg effect.
Method getpath:String()
DescriptionGet the path of the entity.
Informationthe path will be the address of where the entity is within the hierarchy of parent and child entities.
Method getrandomcolor:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether the emitter chooses a random colour for the particles it spawns.
Method getrandomstartframe:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether the emitter chooses a random start frame for the particles it spawns.
Method getsingleparticle:Int()
ReturnsEither TRUE or FALSE.
DescriptionFind out if the emitter spawns a single particle.
Method gettweenspawns:Int()
ReturnsEither TRUE or FALSE.
DescriptionGet whether particles are being spawned from the old effect coordinates to the new.
Method getuniform:Int()
ReturnsTRUE or FALSE.
DescriptionGet whether the particles spawned by this emitter scale uniformally.
Method getuseeffectemission:Int()
Returnseither TRUE or FALSE.
DescriptionGet whether the emitter uses the effect emission instead of its own.
Method getvisible:Int()
Returnseither TRUE or FALSE.
DescriptionGet the visibility status of the emitter.
Method getzlayer:Int()
ReturnsValue from 0 - 8.
DescriptionGet the current z layer of the emitter.
Method hideall()
DescriptionHide all Emitters.
InformationSets all emitters to hidden so that they will no longer be rendered. This also applies to any sub effects and their emitters.
Method nextframe()
DescriptionCycle forward through the image frames.
Method previousframe()
DescriptionCycle backwards throught the image frames.
Method setalpharepeat(v:Int)
DescriptionSet to the number of times the alpha of the particle should cycle within the particle lifetime.
InformationTimeline Particles editor allows values from 1 to 10. 1 is the default.
Method setangleoffset(v:Int)
DescriptionSet the angle offset or variation.
InformationDepending on the value of angletype (tlANGLE_ALIGN, tlANGLE_RANDOM or tlANGLE_SPECIFY), this will either set the angle offset of the particle in the case of tlANGLE_ALIGN and tlANGLE_SPECIFY, or act as the range of degrees for tlANGLE_RANDOM.
Method setanglerelative(v:Int)
DescriptionSet to TRUE to make th particles spawned have their angle of rotation relative to the parent effect.
Method setangletype(v:Int)
DescriptionSet the angle type.
Information

Angle type tells the particle how it show orientate itself when spawning. Either tlANGLE_ALIGN, tlANGLE_RANDOM or tlANGLE_SPECIFY.

tlANGLE_ALIGN: Force the particle to align itself with the direction that it's travelling in.
tlANGLE_RANDOM: Choose a random angle.
tlANGLE_SPECIFY: Specify the angle that the particle spawns with.

Use angleoffset to control the either both the specific angle, random range of angles and an offset if aligning.

Method setanimate(v:Int)
DescriptionSet whether the particle should animate.
InformationOnly applies if the particle's image has more then one frame of animation.
Method setanimationdirection(v:Int)
DescriptionSet the direction the animation plays in.
InformationSet to 1 for forwards playback and set to -1 for reverse playback of the image aniamtion.
Method setcolorrepeat(v:Int)
DescriptionSet to the number of times the colour should cycle within the particle lifetime.
InformationTimeline Particles editor allows values from 1 to 10. 1 is the default.
Method setframe(v:Int)
DescriptionSet the image frame.
InformationIf the image has more then one frame then setting this can determine which frame the particle uses to draw itself.
Method SetGroupParticles(v:Int)
DescriptionSets the current state of whether spawned particles are added to the particle managers pool, or the emitters own pool. True means that.
Method sethandlecenter(v:Int)
DescriptionSet the handle of the particle to its center.
InformationSet to TRUE for the hande to be placed automatically at the center of the particle, or FALSE for the handle to be dictated by handlex and handley.
Method setimage(v:TAnimImage)
DescriptionSet image.
InformationWhen Particles are spawned this image is the image that is assigned to them. Not a tImage but a tAnimImage, a custom image type written by indiepath.
Method setlockangle(v:Int)
DescriptionSet to TRUE to make th particles spawned have their angle of rotation locked to direction.
Method setonce(v:Int)
DescriptionSet to TRUE to make the particles spawned playback the animation just once.
Method setoneshot(v:Int)
DescriptionMake a particle a one shot particle or not.
InformationEmitters that have this set to true will only spawn one particle and that particle will just play out once and die. The is only relevant if singleparticle is also set to true.
Method setparentEffect(v:tlEffect)
DescriptionSet Parent Effect.
InformationAssigns the effect that is the parent to this emitter.
Method setParticlesrelative(v:Int)
DescriptionSet wheter the particles and emitter remain relative to the effect.
InformationEmitters that are relative spawn particles that move and rotate with the effect they're contained in.
Method SetRadiusCalculate(Value:Int)
DescriptionSet the Radius Calculate value for this tlEntity object.
InformationThis overides the tlentity method so that the effects list can be updated too.
Method setrandomcolor(v:Int)
DescriptionSets whether the particle chooses random colour from the colour attributes.
Method setrandomstartframe(v:Int)
DescriptionSet the particles to spawn with a random frame.
InformationOnly applies if the particle has more then one frame of animation.
Method setsingleparticle(v:Int)
DescriptionSet Single Particle.
InformationYou can have particles that do not age and will only be spawned once for point emitters, or just for one frame with area, line and ellipse emitters. Single particles will remain until they are destroyed and will one behave according the values stored in the first temmiterchange nodes - in otherwords they will not change at all over time.
Method settweenspawns(v:Int)
DescriptionSet to TRUE for particles to spawn imbetween th effects old and new coordinates.
InformationThis creates better spawning behaviour especially for smoke trails.
Method setuniform(v:Int)
DescriptionSet Uniform.
InformationDictates whether the particles size scales uniformally. Set to either TRUE or FALSE.
Method setuseeffectemission(v:Int)
DescriptionSet Use effect emission.
InformationSet to TRUE by default, this tells the emitter to take the emission range and emission angle attributes from the parent effect, otherwise if set to FALSE it will take the values from the emitters own emission attributes.
Method setvisible(v:Int)
DescriptionSet to FALSE to stop drawing the particles this emitter spawns.
Method setzlayer(v:Int)
DescriptionSet the z layer.
InformationEmitters can be set to draw on different layers depending on what kind of effect you need. By default everything is drawn on layer 0, higher layers makes those particles spawned by that emitter drawn on top of emitters below them in layers. The layer value can range from 0-8 giving a total of 9 layers.
Method showall()
DescriptionShow all Emitters.
InformationSets all emitters to visible so that they will be rendered. This also applies to any sub effects and their emitters.
Method sortall()
DescriptionSort all attribute lists.
InformationSorts all the graph nodes into the proper order for every emitter attribute.
Method update()
DescriptionUpdate the emitter.
InformationThis is an internal method called by the parent effect when updating each frame. This method will update its position and spawn new particles depending on whatever settings the emitter has by calling updatespawns.
Method updatechildren()
DescriptionUpdates all the particles this emitter has spawned.
InformationThis method is called by update each frame.
Method updatespawns(esingle:tlParticle = Null)
DescriptionSpawns a new lot of particles if necessary and assign all properties and attributes to the particle.
InformationThis method is called by update each frame.

Type tlEmitterArray
DescriptionAn attribute array type.
InformationThis Type stores the Attribute node graphs inside arrays for a faster lookup rather then having to interpolate in real-time. See Compile_All.

Type tlParticle Extends tlEntity
DescriptionParticle Type - extends tlEntity.
InformationThis is the object that is spawned by emitter types and maintained by a Particle Manager. Particles are controlled by the emitters and effects they're parented to.
Methods Summary
reset Resets the particle so it's ready to be recycled by the particle manager.
setx Set the current x coordinate of the particle and capture the old value.
sety Set the current y coordinate of the particle and capture the old value.
setz Set the current zoom factor of the particle and capture the old value.
update Updates the particle.
Method reset()
DescriptionResets the particle so it's ready to be recycled by the particle manager.
Method setx(v:Float)
DescriptionSet the current x coordinate of the particle and capture the old value.
Method sety(v:Float)
DescriptionSet the current y coordinate of the particle and capture the old value.
Method setz(v:Float)
DescriptionSet the current zoom factor of the particle and capture the old value.
Method update()
DescriptionUpdates the particle.
InformationThis is called by the emitter the particle is parented to.

Type tlParticleManager
DescriptionParticle manager for managing a list of effects and all the emitters and particles they contain.
Information

The particle manger is the main type you can use to easily manage all of the effects you want to use in your application. It will automatically update all of the effects and draw the particles with a simple call to Update and DrawParticles.

The simplist use of the particle manager would be to, create it, add an effect and then update and draw in your main loop:

Local MyEffectsLib:tlEffectsLibrary=LoadEffects("MyEffects.eff")
local MyEffect:tlEffect=MyEffectsLib.GetEffect("Explosion")
local MyParticleManager:tlParticleManager=CreateParticleManager()
MyParticleManager.SetScreenSize(GraphicsWidth(),GraphicsHeight())
MyParticleManager.AddEffect(MyEffect)
Repeat
cls
MyParticleManager.Update()
MyParticleManager.DrawParticles()
flip
Forever

The particle manager maintains 2 lists of particles, an Inuse list for particles currently in the rendering pipeline and an UnUsed list for a pool of particles that can be used by emitters at any time. You can control the maximum number of particles a particle manager can use when you create it:

local MaximumParticles:int=2500
local MyParticleManager:tlParticleManager=CreateParticleManager(MaximumParticles)

When emitters need to spawn new particles they will try and grab the next available particle in the Unused list.

The command SetScreenSize tells the particle manager the size of the viewport currently being rendered to. With this information it locates the center of the screen. This is important because the effects do not locate themselves using screen coordinates, they instead use an abritrary set of world coordinates. So if you place an effect at the coordinates 0,0 it will be drawn at the center of the screen. But don't worry, if you want to use screen coordinates to place your effects you can use the SetOrigin command to offset the world coordinates to screen space:

MyParticleManager.SetScreenSize(GraphicsWidth(),GraphicsHeight())
MyParticleManager.SetOrigin(GraphicsWidth()/2,GraphicsHeight()/2)

This will place the origin at the top-left of the viewport so effects placed at 0,0 now will be drawn in the top-left corner of the screen in the same way DrawImage would. If however you application uses it's own world coordinate system to postion entities then it should be easy to use SetOrigin to syncronise the location of any effects with your app.

You can now also define a number of effect layers when creating a particle manager. This enables you to control more easily the order in which effects are drawn. For example, if you create a particle manager with 10 layers, when you use AddEffect you can specify which layer the effect is added to. Effects on layers 1 will draw on top of layers on layer 0, 2 over 1 etc. The layer index starts from 0, so if you create 10 layers, their index will range from 0 to 9.

Example
SuperStrict

Framework brl.max2d
Import rigz.timelinefx
Import rigz.tweener
Import brl.glmax2d

SetGraphicsDriver GLMax2DDriver()

'Load the effects library
Local MyEffectsLib:tlEffectsLibrary = LoadEffects("effects/examples.eff", False)
'Create an effect and assign it an effect from the library
Local MyEffect:tlEffect = MyEffectsLib.GetEffect("simple explosion 1")
'Create the particle manager to manage the particles
Local MyParticleManager:tlParticleManager = CreateParticleManager()

Graphics (800, 600, 0)

'These commands are important to set the origin of the particle manager. For this example we're setting the origin so that
'effects will be placed at screen coordinates. If you leave out the setorigin command then an effect created at 0,0 would
'be placed at the center of the screen.
myparticlemanager.SetScreenSize(GraphicsWidth(), GraphicsHeight())
myparticlemanager.SetOrigin(GraphicsWidth() / 2, GraphicsHeight() / 2)
'You can use the following command to control the number of particles spawned globally by the particle manager.
'This is handy for slower PCs where you want to reduce the number of particles that are drawn overal. A setting of 0.5 would halve the
'number spawned for example. 1 is the default value.
MyParticleManager.SetGlobalAmountScale(1)

MyParticleManager.SetUpdateMode(tlUPDATE_MODE_INTERPOLATED)

'This will make one frame equal 33 millisecs long - or 30 updates per second.
SetUpdateFrequency(30)

'Create a tweener using the tweener mod. Make sure its frequency matches that above
Local Tweener:tTweener = New tTweener.Create(30)

'Our main loop
While Not KeyDown(KEY_ESCAPE) Or AppTerminate()
	
	Cls
	
	If MouseHit(1)
		'to create an effect you need to use the copyeffect command, and copy the MyEffect you created earlier. 
		'You shouldn't use MyEffect as it is the template
		'for which is used to create effects you draw on screen.
		Local tempeffect:tlEffect = CopyEffect(myeffect, MyParticleManager)
		'Set the temp effect to the mouse coords
		tempeffect.SetX(MouseX())
		tempeffect.SetY(MouseY())
		'give it a random zoom level which will affect the overal size of the effect
		tempeffect.SetZ(Rnd(0.5, 1.5))
		'add the effect to the particle manager. Important, otherwise the particle manager would have nothing to update
		MyParticleManager.addeffect(tempeffect)
	End If
	
	'here is the timing code, update the tweener to get the number of ticks for this loop
	Tweener.Update()
	
	For Local Ticks:Int = 1 To Tweener.FrameTicks
		'Update the execution time for the tweener
		Tweener.UpdateExecutionTime()
		'Update the particle manager
		MyParticleManager.Update()
	Next
	
	'and finally draw the particles.
	MyParticleManager.DrawParticles(Tweener.Tween)
	
	SetRotation 0
	SetScale 1, 1
	SetAlpha 1
	DrawText MyParticleManager.GetParticlesInUse(), 10, 10
	
	Flip 0
	
Wend
Methods Summary
addeffect Adds a new effect to the particle manager.
AddPreLoadedEffect Adds a New effect To the particle manager, and pre loads a given number of frames.
ClearAll Remove all effects and clear all particles in use.
ClearInUse Clear all particles in use.
ClearLayer Remove all effects and particles from a specific layer.
Create Create a new Particle Manager.
destroy Destroy the particle manager.
DrawParticles Draw all particles currently in use.
GetGlobalAmountScale Get the globalamountscale value of the particle manager.
GetOrigin_X Get the current x origin of the particle manager.
GetOrigin_Y Get the current y origin of the particle manager.
GetOrigin_Z Get the current z origin/zoom factor of the particle manager.
GetParticlesInUse Get the current number of particles in use.
GetParticlesUnUsed Get the current number of un used particles.
GetUpdateMode Get the current update mode for the particle manager.
ReleaseParticles Release single particles.
removeeffect Removes an effect from the particle manager.
SetAngle Set the angle of the particle manager.
SetGlobalAmountScale Set the globalamountscale value of the particle manager.
SetIdleTimeLimit Set the amount of time before idle effects are deleted from the particle manager.
SetOrigin Set the Origin of the particle Manager.
SetOrigin_X Set the x origin.
SetOrigin_Y Set the y origin.
SetOrigin_Z Set the level of zoom.
SetScreenPosition Set the current screen position.
SetScreenSize Set the current screen size.
SetUpdateMode Set the update mode for the particle manager.
Togglepause Pause and unpause the particle manager.
Update Update the Particle Manager.
Functions Summary
TweenValues Interpolate between 2 values.
Method addeffect(e:tlEffect, Layer:Int = 0)
DescriptionAdds a new effect to the particle manager.
InformationUse this method to add new effects to the particle manager which will be updated automatically. If the particle manager has more then one layer, then you can specify which layer the effect is added to. If the layer you pass does not exist then it will default to 0.
Method AddPreLoadedEffect(e:tlEffect, frames:Int, Layer:Int = 0)
DescriptionAdds a New effect To the particle manager, and pre loads a given number of frames.
InformationUse this method to add a new effect to the particle and start the effect running from whatever number of frames you pass to it. In most cases the overhead for this will be small, but for extremely heavy effects with many particles you may experience some performance hit. Use this instead of addeffect if you want to pre load an effect. If the particle manager has more then one layer, then you can specify which layer the effect is added to. If the layer you pass does not exist then it will default to 0.
Method ClearAll()
DescriptionRemove all effects and clear all particles in use.
InformationIf you want to remove all effects and particles from the manager then use this command. Every effect will instantly stop being rendered.
Method ClearInUse()
DescriptionClear all particles in use.
InformationCall this method to empty the list of in use particles and move them to the un used list.
Method ClearLayer(Layer:Int)
DescriptionRemove all effects and particles from a specific layer.
InformationIf you want to remove all effects and particles from a specific layer in the particle manager then use this command. Every effect will instantly stop being rendered.
Method Create:tlParticleManager(Particles:Int = tlPARTICLE_LIMIT, Layers:Int = 1)
DescriptionCreate a new Particle Manager.
InformationCreates a new particle manager and sets the maximum number of particles. Default maximum is 5000.
Method destroy()
DescriptionDestroy the particle manager.
InformationThis will destroy the particle, clearing all effects and particles. Use only when you are finished with the particle manager and want it removed to avoid any memory leaks.
Method DrawParticles(tween:Float = 1, Layer:Int = -1)
DescriptionDraw all particles currently in use.
InformationDraws all pariticles in use and uses the tween value you pass to use render tween in order to smooth out the movement of effects assuming you use some kind of tweening code in your app. You can also specify the effect layer that is drawn, otherwise by default, all layers will be drawn.
Method GetGlobalAmountScale:Float()
DescriptionGet the globalamountscale value of the particle manager.
Informationsee SetGlobalAmountScale for info about setting this value.
Method GetOrigin_X:Float()
DescriptionGet the current x origin of the particle manager.
Method GetOrigin_Y:Float()
DescriptionGet the current y origin of the particle manager.
Method GetOrigin_Z:Float()
DescriptionGet the current z origin/zoom factor of the particle manager.
Method GetParticlesInUse:Int()
DescriptionGet the current number of particles in use.
Method GetParticlesUnUsed:Int()
DescriptionGet the current number of un used particles.
Method GetUpdateMode:Int()
ReturnsThe current update mode of the particle manager. See SetUpdateMode.
DescriptionGet the current update mode for the particle manager.
Method ReleaseParticles()
DescriptionRelease single particles.
InformationIf there are any singleparticles (see SetSingleParticle) this will release all of them and allow them to age and die.
Method removeeffect(e:tlEffect)
DescriptionRemoves an effect from the particle manager.
InformationUse this method to remove effects from the particle manager. It's best to destroy the effect as well to avoid memory leaks.
Method SetAngle(v:Float)
DescriptionSet the angle of the particle manager.
InformationSetting the angle of the particle manager will rotate all of the particles around the origin.
Method SetGlobalAmountScale(Value:Float)
DescriptionSet the globalamountscale value of the particle manager.
InformationSetting this value will scale the amount of the particles spawned by all emitters contained within the particle manager, making it a handy way to control globally, the amount of particles that are spawned. This can help improve performance on lower end hardware that struggle to draw lots of particles. A value of 1 (the default value) will spawn the default amount for each effect. A value of 0.5 though for example, will spawn half the amount of particles of each effect.
Method SetIdleTimeLimit(v:Int)
DescriptionSet the amount of time before idle effects are deleted from the particle manager.
InformationAny effects that have no active particles being drawn on the screen will be automatically removed from the particle manager after a given time set by this function.
Method SetOrigin(x:Float, y:Float, z:Float = 1)
DescriptionSet the Origin of the particle Manager.
InformationAn origin at 0,0 represents the center of the screen assuming you have called SetScreenSize. Passing a z value will zoom in or out. Values above 1 will zoom out whilst values from 1 - 0 will zoom in. Values less then 0 will flip the particles being drawn.
Method SetOrigin_X(v:Float)
DescriptionSet the x origin.
InformationSee SetOrigin.
Method SetOrigin_Y(v:Float)
DescriptionSet the y origin.
InformationSee SetOrigin.
Method SetOrigin_Z(v:Float)
DescriptionSet the level of zoom.
InformationValues above 1 will zoom out whilst values from 1 - 0 will zoom in. Values less then 0 will flip the particles being drawn.
Method SetScreenPosition(x:Int, y:Int)
DescriptionSet the current screen position.
InformationIf you're rendering to a particular section of the screen then you can set the position of the viewport's top left coordinates using this command. Thanks to Imphy for the suggestion!
Method SetScreenSize(w:Int, h:Int)
DescriptionSet the current screen size.
InformationTells the particle manager the current size of the view port, whether its the screen size or canvas size if you're using a gui.
Method SetUpdateMode(mode:Int)
DescriptionSet the update mode for the particle manager.
InformationThere are 2 types of mode, compiled and interpolated. Compiled mode will force the particles to be updated using compiled lookup tables whereas interpolated mode will force the particles to use interpolation to update. Pass either either tlUPDATE_MODE_COMPILED or tlUPDATE_MODE_INTERPOLATED to set either mode. The default mode is compiled mode.
Method Togglepause()
DescriptionPause and unpause the particle manager.
InformationPauses the drawing and updating of all effects within the particle manager.
Method Update()
DescriptionUpdate the Particle Manager.
InformationRun this method in your main loop to update all particle effects.
Function TweenValues:Float(oldValue:Float, value:Float, tween:Float)
DescriptionInterpolate between 2 values.
InformationThis is the function used to achieve render tweening by taking the old and new values and interpolating between the 2.

Module Information

AuthorPeter J. Rigby
CopyrightPeter J. Rigby 2009-2010
PurposeTo add rich particle effects to games and applications, quickly and easily
History v1.1530 October 2010 - Fixed a bug with interpolated mode and loading effects with compile flag set to false
History v1.1407 October 2010 - Added new effect method, DoNotTimeout() which stops effects from timingout and destroying themselves
History v1.1405 October 2010 - Added effects layers to particle manager to help with z-ordering, see tlParticleManager Docs for more info.
History v1.1320 June 2010 - Fixed a bug with stretch causing recycled particles to stretch way out of shaped on spawning
History v1.1320 June 2010 - Added SetGlobalAmountScale to the particle manger, for controlling the amount of particles spawned.
History v1.1225 May 2010 - Parent effects should now properly play out their graphs right to the end.
History v1.1225 May 2010 - Particles that animate in reverse should now work properly
History v1.1103 May 2010 - You can now change the way particles are drawn by grouping them by the emitter that spawns them. Use
History v1.1103 May 2010 - Fixed a bug where emitters that use the splatter graph are not effected by global zoom properly.
History v1.1004 April 2010 - Fixed an error on loading effects files with empty folders
History v1.0929 March 2010 - Added a new attribute - Splatter
History v1.0929 March 2010 - Fixed a memory leak when effects files are loaded over and over again
History v1.0913th February 2010 - Particles will now only stretch along their relative velocities.
History v1.0926th Januray 2010 - Fixed a bug where the wrong frame would be drawn causing array out of bounds error
History v1.0823rd November 2009 - Improved the way DrawParticles decides whether a particle is on screen to be drawn.
History v1.0819th November 2009 - The particle radius and bounding box are now initialised initialised properly when spawning.
History v1.0708th November 2009 - Tidied up the behaviour of adjusting the Z value of effects and implented globalz as a graph attribute
History v1.0707th November 2009 - Particle manager now restores the GFX states (alpha, scale etc.) after drawing particles.
History v1.0729th October 2009 - Added Destroy method to tlParticleManager. Use to avoid memory leaks.
History v1.0620th September 2009 - Initial implementation of Z on effects (changes the overal scale of an effect)
History v1.064th August 2009 - Fixed a bug where clicking on the shape preview wouldn't set the handle to the correct place
History v1.064th August 2009 - Fixed a bug where locking the angle of a particle reversed the direction it was going in
History v1.0518th August 2009 - Fixed a bug causing large angle changes to tween incorrectly
History v1.0518th August 2009 - Added a Global Stretch attribute to tlEffects
History v1.0415th August 2009 - Emitters that spawn particles with a random frame, now have the correct range of frames to choose from
History v1.038th August 2009 - Particle manager now sets oktorender to false for the particles it renders, see SetOKToRender in entity.mod
History v1.038th August 2009 - Added new method SetEffectParticleSize, which rolls SetSizeX and Y into one method
History v1.0219th July 2009 - Single particles will now playout their graphs in a loop providing more oppertunities for animated sprites
History v1.0218th July 2009 - When lockedangle is used, particles will now take into account gravity when aligning themselves
History v1.0218th July 2009 - Fixed a bug where the speed of new particles being spawned was not the correct value
History v1.0218th July 2009 - Fixed a bug where life variation was being halved
History v1.0218th July 2009 - Added new attribute Stretch. Particles are stretched according to how fast they're travelling
History v1.0116th July 2009 - Added new command to pre load effects to tlParticleManager - AddPreLoadedEffect()
History v1.0114th July 2009 - Moved some globals from entity.mod to here because it made more sense. Created globals.bmx
History v1.0028th March 2009 - First Release