TimelineFX for BlitzMax

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

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.

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)

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.

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:

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

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.

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.

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.

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

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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.

Set to true to make the size of particles scale uniformly

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

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.

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

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.

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.

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.

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.

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

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

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

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

This is the main type for storing entity information such as coordinates, colour and other information. tleffect, tlemitter and tlparticle are all extensions of tlEntity. Generally you shouldn't have to use this type directly but it may be useful in some cases. Some tutorials may be available at some point showing how to use this type to create objects for your own app instead of having to create your own entity type from scratch.

Entities can be parented to other entities and maintain and update a list of children.

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.

SuperStrict

Import rigz.timelinefx
Import rigz.tweener

SetGraphicsDriver GLMax2DDriver()

'Load the effects library
Local MyEffectsLib:tlEffectsLibrary = LoadEffects("effects/examples.eff")
'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)

'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())
		'add the effect the 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