particlemanager.monkey

Table of contents:

Classes:
Functions:
Function CreateParticleManager:tlParticleManager(particles:Int = tlPARTICLE_LIMIT)
Description:Create a new particle manager
Returns:tlParticleManager
Details: Creates a new particle manager that you can use to create and update new effects. Pass the maximum number of particles that you wish to update at any one time.
Class tlParticleManager
Description:The particle manager class for TimelinFX. This class manages all effects you create and is used to update and render all particles.
Details: 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 process of using the particle manager class is to, create it, add an effect to it and then update and draw in the OnCreate, OnUpdate and OnRender methods in a monkey App class:

	Import mojo
Import timelinefx

Class FXexample Extends App

Field MyEffects:tlEffectsLibrary
Field MyEffect:tlEffect
Field MyParticleManager:tlParticleManager

Method OnCreate()

MyEffects = LoadEffects("explosions")
MyEffect = MyEffects.GetEffect("a big explosion")
MyParticleManager = CreateParticleManager(5000)

MyParticleManager.SetScreenSize(DeviceWidth(), DeviceHeight())
MyParticleManager.SetOrigin(DeviceWidth() / 2, DeviceHeight() / 2)

SetUpdateFrequency(30)
SetUpdateRate 30
End

Method OnUpdate()
If MouseHit
Local tempeffect:tlEffect = CopyEffect(MyEffect, MyParticleManager)
tempeffect.SetPosition(MouseX, MouseY)
MyParticleManager.AddEffect(tempeffect)
EndIf
MyParticleManager.Update()
End

Method OnRender()
Cls

MyParticleManager.DrawParticles()
End
End

Function Main()

New FXexample

End


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 your 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.
Table of contents:Methods:
Method AddEffect(e:tlEffect)
Description:Adds a new effect to the particle manager
Returns:Int
Details: Use this method to add new effects to the particle manager which will be updated automatically
Method CurrentTime:Float() Property
Description:The current time in millisecs since the particle manager has been updated.
Returns:Float
Method CurrentTime(v:Float) Property
Description:Do not set this value as it's managed internally by the particle manager!
Returns:Int
Method DisableSetColor()
Description:Disable the particles from rendering using set colour. Useful if you running in HTML5which is very slow when using this command.
Returns:Int
Method DrawParticles(tween:Float = 1)
Description:Draw all particles currently in use
Returns:Int
Details: Draws 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.
Method EnableSetColor()
Description:Enable the use of set colour for rendering particles.
Returns:Int
Method GetGlobalAmountScale:Float()
Description:Get the globalamountscale value of the particle manager
Returns:Float
Details: see SetGlobalAmountScale for info about setting this value
Method GlobalAmountScale:Float() Property
Description:The Global amount scale is used to control the overal number of particles that will be spawned.
Returns:Float
Method GlobalAmountScale(v:Float) Property
Description:The Global amount scale is used to control the overal number of particles that will be spawned.
Returns:Int
Details: The default value is 1, meaning that the particle manage will spawn the same number of particles as designed in the editor. To spawn half the amount of particles, set to 0.5.
This feature is useful for giving users the option to tone down the number of particles if their device is running slowly.

		MyParticleManager.GlobalAmountScale(0.5)

Method IdleTimeLimit:Int() Property
Description:The amount of time before an effect is removed from the particle manager.
Returns:Int
Method IdleTimeLimit(v:Int) Property
Description:Set the idle time limit to control how long before an idle effect is removed from the particle manager's list of effects
Returns:Int
Details: An effect is considered idle if it currently has no particles active within it. You may have effects that have moments where they do not spawn any particles, so you can tweak this
property to stop effects being prematurely removed from the particle manager.

The default value is 100 (measured in game updates)

If you want an effect to never be removed from the particle manager then you can use

		effect.DoNotTimeOut(True)

Method New(particles:Int = tlPARTICLE_LIMIT)
Description:Create a new instance of tlParticleManager
Details: See also CreateParticleManager
Method ParticlesInUse:Int() Property
Description:Returns the number of particles currently in use by the particle manager.
Returns:Int
Method RemoveEffect(e:tlEffect)
Description:Removes an effect from the particle manager
Returns:Int
Details: Use this method to #Remove effects from the particle manager. It's best to destroy the effect as well to avoid memory leaks
Method SetGlobalAmountScale(Value:Float)
Description:Set the globalamountscale value of the particle manager
Returns:Int
Details: Setting 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)
Description:Set the amount of time before idle effects are deleted from the particle manager
Returns:Int
Details: Any 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)
Description:Set the Origin of the particle Manager.
Returns:Int
Details: An 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)
Description:Set the x origin
Returns:Int
Details: See SetOrigin
Method SetOrigin_Y(v:Float)
Description:Set the y origin
Returns:Int
Details: See SetOrigin
Method SetScreenPosition(x:Int, y:Int)
Description:Set the current screen position
Returns:Int
Details: If you're rendering to a particular section of the screen then you can set the position of the viewport's coordinates using
this command. Thanks to Imphy for the suggestion!
Method SetScreenSize(w:Int, h:Int)
Description:Set the current screen size
Returns:Int
Details: Tells the particle manager the current size of the view port
Method SetZoom(v:Float)
Description:Set the level of zoom
Returns:Int
Details: 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 Togglepause()
Description:Pause and unpause the particle manager
Returns:Int
Details: Pauses the drawing and updating of all effects within the particle manager.
Method Update()
Description:Update the Particle Manager
Returns:Int
Details: Run this method in the OnUpdate method to update all particle effects.

This document was generated using the Jungle IDE document generator version 13.03.24-B