EMITTER COMMANDS
	These commands are related to emitters. It's a good practice to create your emitters before level start, re-use them during the game and remove them after the level or game finished. Emitters can be used like display objects, they can be positioned, moved and rotated. You can also set an emitter's alpha as with any other display object. All emitted particles of this emitter will inherit the emitter's current alpha then. Particles will be emitted into the direction where the emitter points, at a specified speed. A particle features several different rotation modes: by default, it inherits the emitter's rotation. You can also specify an automatic rotation speed or let a particle be automatically motion-aligned (particle will always point into its travel direction then). Beside system memory and performance, there is no limit on the number of emitters you use.

	CreateEmitter
	Creates an emitter. If set to visible, you will see an arrow symbol that represents the emitter's position and rotation. CreateEmitter("name", x,y, rotation, visible, loop, autoDestroy) name (String) A unique name for this emitter. x, y (Number) Emitter's initial x- and y-coordinate. rotation (Number) Emitter's initial rotation angle (0...360). visible (Boolean) True: Show emitter False: Hide Emitter loop (Boolean) True: Emitter will restart automatically when finished False: Run once when started autoDestroy (Boolean) True: Emitter will be removed automatically when finished emission (NOTE! You must set all your references to this emitter to "nil" before, otherwise the emitter will stay in memory!). False: Disable auto-destroy.

	ChangeEmissionRate
	Changes the emission rate (particles per second) of a particle type that has been attached to the specified emitter. ChangeEmissionRate("emitterName", "particleName", emissionRate) emitterName (String) Name of an existing emitter. particleName (String) Name of an existing particle type (must have been attached to the specified emitter). emissionRate (Number) Emission rate (particles per second).

	DeleteEmitter
	Deletes an emitter. Important note! If you stored any emitter handles using GetEmitter(), you must set these references to the emitters to "nil" before you delete the emitters. Otherwise, they cannot be garbage collected and will remain in memory! So be careful when storing emitter handles on your own! DeleteEmitter("name") name (String) An emitter's unique name.

	EmitterIsActive
	Checks if an emitter is still emitting any particles. EmitterIsActive("name") name (String) An emitter's unique name. Returns: (Boolean) True if the specified emitter is still firing, otherwise false.

	GetEmitter
	Returns a handle to the specified emitter (which is actually a display object). Using this handle, you can freely position, move, rotate the emitter or change it's alpha value (particles will inherit the emitter's current alpha value). Note that scaling has no effect on the emitter or its particles. Use SetEmitterScale() to scale all attached particles at once. Important note! If you stored any emitter handles using GetEmitter(), you must set these references to the emitters to "nil" before you delete the emitters. Otherwise, they cannot be garbage collected and will remain in memory! So be careful when storing emitter handles on your own! If you don't want to store an emitter reference, you can also write GetEmitter("MyEmitter").x = 50 -or with Gideros GetEmitter("MyEmitter"):setX(50), for example. GetEmitter("name") name (String) An emitter's unique name. Returns: (Display Object) Handle of the emitter.

	GetEmitterScale
	Returns the current emitter scale value. See SetEmitterScale() for more info. GetEmitterScale("name") name (String) An emitter's unique name. Returns: (Number) Current emitter scale value.

	ListEmitters
	Prints a list of all existing emitters and their attached particle types into the console window. ListEmitters()

	SetEmitterListener
	Emitters can call listener functions when any of their emitted particles have been killed (expired). The event that will be sent to your listener function contains various information about the particle that is about to die (see list below). When an emitter is deleted, it will automatically set its reference to your listener function to "nil", so you don't have to care about this. SetEmitterListener("name", Listener) name (String) An emitter's unique name. Listener (Function) Function that should be called on event. The event object you receive contains the following information: event.x (Number) X-position of the particle that is about to die. event.y (Number) Y-position of the particle that is about to die.. event.rotation (Number) The particle's current rotation. event.alpha (Number) The particle's current alpha value. event.scale (Number) The particle's current scale. event.xSpeed (Number) The particle's current x velocity. event.ySpeed (Number) The particle's current y velocity. event.typeName (String) Name of the particle's particle type. event.particleIndex (Number) The particle's index (ID). Use GetParticle(particleIndex) to access the particle directly. Note that this particle is about to die and therefore will be deleted in the next frame or the next time you call Update(). event.emitterName (String) Name of the particle's emitter. -- LISTENER FUNCTION CALLED WHEN PARTICLES HAVE BEEN DESTROYED function MyParticleDestroyListener( event ) print ("A PARTICLE DIED!") print ("EVENT NAME: "..event.name) print ("EVENT X-POSITION: "..event.x) print ("EVENT X-POSITION: "..event.y) print ("PARTICLE TYPE : "..event.typeName) print ("EMITTER NAME : "..event.emitterName) end Particles.SetEmitterListener("MyEmitter", MyParticleDestroyListener)

	SetEmitterScale
	Sets the current emitter scale value. The emitter scale value has nothing to do with the scale of the little emitter arrow symbol. By changing an emitter's scale value, you can easily scale all attached particle types bigger or smaller (which will scale the complete effect, including speed changes etc.) If you have an explosion in the foreground, for example, and would like to use the same explosion anywhere in the "distance", you can set the emitter's scale to 0.5, which will shrink the complete explosion to half of the original size. On the other hand, you can use a scale of 2.0 to double the explosion size. SetEmitterScale("name", scale) name (String) An emitter's unique name. scale (Number) An emitter's unique name.

	SetEmitterSound
	Attaches a sound effect (loaded via audio.loadSound / audio.loadStream) to an emitter. The sound effect will be started (and optionally stopped) automatically when the emitters starts or stops emission. Important note! If you attached any sounds to emitters, these emitters must be deleted BEFORE you use audio.dispose() on those sounds, otherwise the sounds won't be garbage collected. This is because emitters store a reference to your sound object unless it has been removed from the emitter again. To remove a sound from an emitter Use either SetEmitterSound(emitterName) (only the emitter name, no other parameters) Delete the emitter using DeleteEmitter() Remove all attached particle types using DetachParticleTypes() Or call CleanUp(). All these commands will remove the attached sound effect from the emitter (and all references to it). The loaded sound itself still remains in memory, so you can re-use or dispose it, whatever you prefer. SetEmitterSound("name", SoundHandle, delay, autoStop, SoundSettings) name (String) An emitter's unique name. SoundHandle (Userdata / Sound Class) Reference to a sound object or a sound class. With Corona, use audio.loadSound() or audio.loadStream() to load a sound file, with Gideros use Sound.new(). delay (Number) Playback delay in milliseconds (counted from the moment the emitter started emission). autoStop (Boolean) Default is false. When set to true, the attached sound will be stopped once the emitter finished emission or was stopped. Set this to true when attaching sounds with infinite loops, for exmaple -otherwise the sound would keep playing even if the emitter was stopped. SoundSettings (Table) Corona only. A table containing parameters that affect the playback of the sound effect (channel to use, number of loops, fade-in time etc.). For example: { channel = 0, loops = -1, fadeIn = 1000 }. Refer to Corona's Audio API for a detailed description of these parameters.

	SetEmitterTarget
	Use this command to let an emitter automatically follow another object (the target). Of course this could also be done by grouping the object and the emitter, but this would cause the emitter's particles to being drawn within that group. If the group rotates, all particles within would also rotate. If you don't want this behaviour, use SetEmitterTarget to let an emitter follow a target without the need to group both together. Note that the emitter will only follow the object while emitting particles. If the emitter is inactive, it will keep it's current position. This is a performance optimization. To untie both objects again, simply use this command again wihtout a target handle (or pass nil as the target handle): SetEmitterTarget("MyEmitter", nil) SetEmitterTarget("name", TargetHandle, autoRotate, rotationOffset, xOffset, yOffset) name (String) An emitter's unique name. TargetHandle (Display Object) Handle of a display object to follow (a space ship, for example). autoRotate (Boolean) If set to true, the emitter will also mimic the target's current rotation, otherwise the emitter will keep it's own current rotation. rotationOffset (Number) You can specify a rotation offset here (in degrees) that is automatically added to the target's rotation. This is useful if the emitter should follow a target but point into another direction while doing so. xOffset yOffset (Number) You can specify offsets for the emitter's x- and y-position. If you apply a y-offset of -50, for example, the emitter will always be placed 50 pixels above the target's current position.

	StartEmitter
	Triggers an emitter. The emitter will start emitting particles, taking into account all the specified delay values for each attached particle type. If the emitter has finished emitting all particles, it will either stop or restart, if it's loop parameter has been set to true (on CreateEmitter). Emitters emit particles steadily over time. However, this may not be accurate enough to simulate very short or fast effects like gunfire or effects with a single particle only. To simulate very short effects, set the optional oneShotEmission parameter to true. This will force the emitter to emit all particles within a single frame. If oneShotEmission is set to true, all particle types duration settings (see AttachParticleType) will be ignored. The specified emission rate will be the number of particles fired at once then. StartEmitter( "name", [oneShotEmission] ) name (String) An emitter's unique name. oneShotEmission (Boolean) Optional, default false. If true, the emitter will not emit the particles over time (as usual), it will fire them all at once within a single frame.

	DefineEmissionShape
	By default, emitters spray particles from a single point -the point where the emitter is located (indicated by a little white arrow). You can vary this by using a circle shaped, ring shaped, disc shaped or line shaped emission (these basic shapes can be defined when creating particle types, see "CreateParticleType", emissionShape property there). But you can do much more -you can define a custom polygon shape (an emission path, so to say) for each emitter. This shape is constructed of one or more lines that are connected to each other and define any shape you want. The emitter's particles are then emitted along this path. Example 1: Imagine you have an image that displays the letter "A" and you want to emit particles along the edges of this letter. No problem -simply create an emission path that roughly forms the outline of this letter and the particles will be drawn all along its edges. Example 2: You want to display a burning house. Just place an image of a house on the screen, add an emitter and create an emission path that looks like the outline of that building (or its roof). The result will look way more realistic. DefineEmissionShape( "name", Array, [useEmitterRotation], [useCornersOnly], [showLines] ) name (String) An emitter's unique name. Array (Array) An array to define the shape. The array you pass must be of this format: length of line1, angle of line 1, length of line 2, angle of line 2, ... and so on. The first line will be placed where the emitter is and will be rotated to the angle you define. The second line will be attached at the end of the first line (again, rotated to the angle you specify) and so on... Example array: {100,30, 50,60} -this will draw two lines. The first line will be placed directly at the emitter's position, with a length of 100 pixels and a rotation of 30 degrees (0 degress points to the right, 90 downwards and so on). The second line will be drawn at the end of line 1, with a length of 50 pixels and it will be rotated to 60 degrees. Rotation of the lines is always absolute, so 0 degrees always points to the right, 90 downwards, 180 to the left and 270 upwards. You can also specify negative angles to turn a line counter-clockwise. useEmitterRotation (Boolean) Optional. When true, the particles will be emitted from anywhere along the defined path, but from there they will move into the same direction where the emitter arrow points. When set to false (default), the particles will move into the direction where the shape's edges are facing. useCornersOnly (Boolean) Optional. Default is false. When true, the particles will be emitted only at the corners of the shapes (this is where two lines are connected to another). This is useful to simulate many different emission points using one emitter only. showLines (Boolean) Optional. Default is true. When set to true, the shape will be visible (which allows you to edit the shape easily). Set this parameter to false to hide the shape in your final build.

	DeleteEmissionShape
	Removes an emission shape from the specified emitter. DeleteEmissionShape( "name" ) name (String) An emitter's unique name.

	StopEmitter
	Stops and resets an emitter. StopEmitter("name") name (String) An emitter's unique name.

	PARTICLE TYPES
	Particle types define how a certain kind of particle should look and behave. You can create one or as many particle types as you like and attach them to the same or different emitters. For a fire effect, for example, you would create one particle type for the smoke, another one for the flames and maybe a third one to show some sparks flying around. Attach them to an emitter then and you are ready to go. You can also change particle type properties "on the fly" after they have been attached to emitters, even if the emitter already started emitting them. The changes will then be reflected in realtime. You can either create 'normal' particle types (Particle Candy will handle movement, rotation, scaling etc., depending on your particle type settings) or physics driven particles. Those particles are driven by the SDK' physics engine, which enables particle-particle or particle-background collisions! Normal particle types can be used for clouds, dust, fire, explosions, for example. Physics driven particles can be used for 'solid' objects like falling things, debris etc.

	AttachParticleType
	Attaches a created particle type to an emitter. Once the emitter has been triggered, it will start to emit particles of this kind, using the specified emission rate, emission duration and delay time. AttachParticleType("emitter", "particleName", emissionRate, duration, delay) emitter (String) An emitter's unique name. particleName (String) A particle type's unique name. emissionRate (Number) The amount of particles to emit per second. duration (Number) Duration (in milliseconds) of the emission. delay (Number) Start delay (in milliseconds).

	CreateParticleType
	Creates a particle type. You pass a table that contains all properties you wish to set (these properties will be copied over, so you can delete or re-use the property table after creating the particle type). You can either create 'normal' particle types (Particle Candy will handle movement, rotation, scaling etc., depending on your particle type settings) or physics driven particles. Those particles are driven by the SDK's physics engine, which enables particle-particle or particle-background collisions! Normal particle types can be used for clouds, dust, fire, explosions, for example. Physics driven particles can be used for 'solid' objects like falling things, debris etc. CreateParticleType("particleName", PropertyTable) particleName (String) A particle type's unique name. PropertyTable (Table) A table containing all properties you want to set. -- CREATE A PARTICLE TYPE: local Properties = {} Properties.imagePath = "arrow.png" Properties.imageWidth = 32 Properties.imageHeight = 32 Properties.velocityStart = 150 Properties.lifeTime = 3000 Particles.CreateParticleType ("MyParticleType1", Properties) -- OR JUST THIS WAY: Particles.CreateParticleType ("MyParticleType1", { imagePath = "arrow.png", imageWidth = 32, imageHeight = 32, velocityStart = 150, lifeTime = 3000, } ) Here is a list of all valid particle type properties you can use when defining a particle type: CREATE PARTICLES FROM A SINGLE IMAGE FILE: .imagePath (String or Table) Image file name string (if a single image should be used) or a table (array) that contains multiple image names to use. When a table is used, images are used randomly. Example: imagePath = {"image1.png", "image2.png"} .imageWidth (Number) Display width of the image (required for Corona only, will be ignored with Gideros). .imageHeight (Number) Display height of the image (required for Corona only, will be ignored with Gideros). TO CREATE PARTICLES USING TEXTURE PACKS (GIDEROS): .texturePack (String) Path and file name of a texture pack to use (f.e. "gfx/myTexturepack"). Do not use any extension like .png or .txt here, Particle Candy will automatically look for a .png and a .txt file of the specified name and parse the texture pack data. .frames (Array of numbers) An array of numbers to specify the frames of the texture pack to be displayed (f.e. {1,2,3}). If .frames is not specified, ALL frames on the texture pack are used. .frameDuration (Number) If specified, the frames of the texure pack are played as an animation sequence where .frameDuration is the duration of each frame to be displayed in millisecs. If not specified, each particle will display a random frame. TO CREATE PARTICLES USING IMAGE SHEETS (CORONA): - Requires Corona version 2012.759 or above. - See here for more info about Corona image sheets. .ImageSheet (ImageSheet) Reference to an image sheet loaded with graphics.newImageSheet(). .SheetInfo (Table) Reference to a table that contains the image sheet options (width and height of each image sheet frame). .frames (Array of numbers) If you'd like the particles to randomly display any frames from the image sheet (non-animated), pass an array here that contains all frame numbers that should be used ( Example: frames = {1,2,3} ). .AnimationInfo (Table) If you'd like the particles to display an animation sequence (using the frames on the image sheet), pass a table here that defines an animation sequence, play order, play speed etc. TO CREATE CHARACTER PARTICLES USING A VECTOR FONT: .text (String) If defined, the emitter will emit text particles instead of using an image. Please note, that this could be performance intensive, so it should be used wisely. .font (String) Defines a font to be used with text particles. Use native.systemFont, for example, or any available font. .fontSize (Integer) Defines the font size of the text particles. OTHER PROPERTIES (TO DEFINE A PARTICLE'S BEHAVIOUR): .weight (Number) Weight of the particle. If positive, the particle will tend to fall downwards, if negative, the particle will rise (smoke etc.). If set to 0, the particle will not be affected by gravity. Note: this property will be ignored by physics driven particles. .lifeTime (Number) Lifetime (in milliseconds). Particle will be deleted if lifetime expired or alpha/scale reached a value below 0.001 .xReference (Number) Can be used to alter a particle's rotation x-center. Value may range from 0.0 (left) to 1.0 (right). .yReference (Number) Can be used to alter a particle's rotation y-center. Value may range from 0.0 (top) to 1.0 (bottom). .directionVariation (Number) Emission direction variation (in degrees). A particle will be emitted into the direction where the emitter points. Use this value to randomly alter the emission angle at a certain amount. .velocityStart (Number) The initial velocity of the particle (in pixels per second). .velocityVariation (Number) Range of randomly added speed variation per particle. .velocityChange (Number) Velocity change over time. Use positive numbers to speed-up the particle, negative to dampen the particle. A value of 0 will keep the initial speed. Note: this property will be ignored by physics driven particles. .rotationStart (Number) The initial rotation of the particle (in degrees). .rotationVariation (Number) Range of randomly added rotation variation per particle (in degrees). .rotationChange (Number) Rotation change over time. Use positive numbers to rotate clockwise, negative to rotate counter-clockwise. A value of 0 will disable automatic rotation. Note: this property will be ignored by physics driven particles. .autoOrientation (Boolean) If true, the particle will be automatically aligned to its travel direction. Useful for sparks or water fountains. Note: this property will be ignored by physics driven particles. .useEmitterRotation (Boolean) If true, the particle will inherit the emitter's rotation (emitter's rotation will be added then). .alphaStart (Number) The initial alpha value of the particle (particles do also inherit the current emitter's alpha). .alphaMax (Number) The maximum alpha value of the particle. .alphaVariation (Number) Randomly added variation to the initial alpha value. .fadeInSpeed (Number) The fade-in speed (within one second). .fadeOutSpeed (Number) The fade-out speed (within one second). Must be negative. .fadeOutDelay (Number) Delay (in milliseconds) when fade-out starts. Leave to 0 to disable fade-out. .fadeLoop (Boolean) Default is false. Set this property to true to let a particle constantly fade between the .alphaStart and .alphaMax values. If set to false or not specified, a particle will be removed automatically when fade out is complete (when alpha goes below 0). .scaleStart (Number) The initial scale of the particle. .scaleVariation (Number) Randomly added variation to the initial scale value. .scaleInSpeed (Number) The scale-in speed (within one second). Note: this property will be ignored by physics driven particles. .scaleMax (Number) Sets a maximum scale for the particle. If set to 2.0, for example, the particle stops growing once it reached a scale of 2.0 (the double of its normal size). Note: this property will be ignored by physics driven particles. .scaleOutDelay (Number) Delay (in milliseconds) when scale-out starts. Leave to 0 to disable scale-out. Note: this property will be ignored by physics driven particles. .scaleOutSpeed (Number) The scale-out speed (within one second). Must be negative. Note: this property will be ignored by physics driven particles. .scaleLoop (Boolean) Default is false. Set this property to true to let a particle constantly scale between the .scaleStart and .scaleMax values. If set to false or not specified, a particle will be removed automatically when scale out is complete (when scale goes below 0). .bounceX (Boolean) If true, particles bounce off from left and right screen border. Works only if emitter has none or only one parent group which is not rotated. Note: this property will be ignored by physics driven particles. .bounceY (Boolean) If true, particles bounce off from top and bottom screen border. Works only if emitter has none or only one parent group which is not rotated. Note: this property will be ignored by physics driven particles. .bounciness (Number) Bounce-off force. A value of 0.5, for example, absorbs half of the particles movement energy when it bounces off something. .emissionShape 0 = Point - Particles are be emitted from a single point (emitter position). 1 = Line - Particles are emitteded from a line (emissionRadius defines the length of this line) 2 = Ring - Particles are emitted ringwise around the emitter (emissionRadius defines the circle's radius). 3 = Disc - Particles are emitted within a circle area (emissionRadius defines the radius of this area). .emissionRadius (Number) See emissionShape. Defines the size of the emission shape. .emissionStep When using line- or ring type emission shapes, you can set the .emissionStep property to a certain value to achieve an evenly particle distribution. .killOutsideScreen (Boolean) If true, particles are removed as soon as they leave the screen area. .faceEmitter (Boolean) If true, particles are automatically orientated to face and move towards the emitter's current position. If false, particles will turn and travel away from the emitter. If NOT specified or set to nil, this parameter has no effect. .fxID (Number) You can assign a FX ID to a particle type (which is 0 by default). The particle type will then only be affected by FX Fields with the same ID number. .TapListener (Function) Reference to a custom listener function that should be called when a particle of this type was tapped by the user. Tap event is only enabled if a listener has been specified here. .TouchListener (Function) Corona only. Reference to a custom listener function that should be called when a particle of this type was touched by the user. Touch event is only enabled if a listener has been specified here. .randomMotionMode 0 = Random motion disabled (default). 1 = Linear random direction change. 2 = Smooth random direction change (requires more performance, not available for physics particles). Note: Particle weight should be set to 0 when enabling random motion to avoid unwanted effects. .randomMotionInterval (Number) If randomMotionMode is enabled, particle will change it's direction randomly in frequent intervals. This parameter specifies the delay between direction changes in MilliSecs. .randomMotionAmount (Number) Maximum number of degrees to randomly vary by at each direction change interval. .blendMode (String) Can "add", "multiply" or "screen". If not specified, normal blend mode is used. Use the "add" blendMode setting (which sets the particle to additive blend) for bright or lighting effects like fire, flames, sparks, lasers etc. .colorStart (Array) Array of three values from 0 to 1 that define the red, green and blue color to tint the particle image with. .colorChange (Array) Array of three values from 0 to 1 that specify the color change of a particle per second. Example: -.25,25,0 decreases the red color by -.25 and increases the green color by +.25 per second. Blue remains unchanged here. .sounds (Sound Handle or Array) Handle of a single sound effect or array containing two or more sound effect handles to be played whenever a particle of this type is created. .soundProps (Table) Corona only. Table that defines the playback behaviour (channel, number of loops etc.) for the particle spawn sound specified by the 'sounds' property. .DrawParent (Group|Sprite) By default, particles are drawn into their emitter's parent group or sprite. You can override this by specifying a group or sprite handle where you want the particles to be drawn to. If a DrawParent is specified, particles inherit the position of the emitter, but not the emitter's rotation. Use the .rotationStart property to specify a certain particle rotation then. .drawArea {x1,y1,x2,y2} Defines an area in global (stage) coordinates. If particles leave this area, they will be removed (or bounce back if bounceX / bounceY are set to true). If no area is specified, the screen's dimension are used (default). Note that .killOutsideScreen must be set to true to enable the draw area check.

	Physics Particles
	The above settings (CreateParticleType) create a 'normal' particle type (Particle Candy will handle the rotation, movement, scaling etc. of each particle, depending on your particle type settings). If you want to create physics driven particles (particles that are handled by the SDK's physics engine), you can additionally provide a physics material in your particle type settings (see following table). Once you provide physics properties within a particle type's settings list, the particles of this type are treated as physics driven objects. This means that Particle Candy will not handle movement, rotation and gravity for these particles, this will be managed by the SDK's physics engine instead (while Particle Candy still removes them automatically for you when their lifetime has exceeded or if they faded to zero alpha, for example). Note, that physics driven particles will ignore some of the particle type settings (see colored notes in the list above) since these properties are handled by the physics engine then. Also note, that physics bodies cannot be scaled after creation, so you should not use dynamic scaling with physics driven particles. Corona users note: Physics particles are set to 'dynamic' bodies by default, but you can override this in the PhysicsProperties table (all values you put in this table will be passed to the particle): Gideros users note: Before creating any physics driven particles, you must create a box2D world and call world:step() frequently to update physics. Best practice is to update the physics world right before calling Particle Candy's Update() function. See the included physics sample to see how this is done. CORONA .PhysicsMaterial (Table) A table containing properties that describe a physics material as used in Corona. When you specify a PhysicsMaterial table in your particle type settings, the particles will be physics driven. Example: PhysicsMaterial = { density = 0.75, friction = 0.3, bounce = 0.2 } .PhysicsProperties (Table) A table containing body (and other) properties that should be applied to each physics particle. Example: PhysicsProperties = { isFixedRotation = false, isSleepingAllowed = true, name = "AnyName", ... } Hint: beside common properties used for physics bodies, you can also add custom properties to this table (like a name string etc.). Each property of this table will be passed to each particle of this type. If you specify a name here, you will be able to detect particles by name in your onCollision listener. Each property you specify here can be accessed by your onCollision listener (that is called if a physics particle collides with another physics particle or a static background body). GIDEROS .PhysicsWorld (box2D World) A reference to a box2D world created with b2.World.new(). .PhysicsProperties (Table) A table containing the shape definition and other properties that should be applied to each physics particle. Example: PhysicsProperties = { shape = box2DShapeObject, density = 1.0, friction = 0.1, restitution = 0.2 }

	DetachParticleTypes
	Counterpart to AttachParticleType (note: DetachParticleTypes). Can be used to remove specified (or all) particle types from an emitter. This is useful, for example, if you attached some particle types to an emitter and would like to attach other particle types to create a completely different effect without creating a new emitter. DetachParticleTypes("emitterName", ["particleTypeName"]) emitterName (String) An emitter's unique name. particleTypeName (String) Name of attached particle type you want to be removed from the emitter. If you do not specify a particle type name, all particle types will be removed from the emitter, leaving an empty emitter. keepSound (Boolean) Default is false. When set to true, the attached sound effect (if any) will not be deleted and still plays when the emitter starts emission. If set to false, any attached sound effect will be removed from the emitter.

	SetParticleProperty
	Use this command to change any particle type property on the fly. SetParticleProperty("particleName", "property", value) particleName (String) A particle type's unique name. property (String) The property name (in quotes) to change. value (Any) Any appropriate value (see particle type properties above).

	FX FIELDS
	FX Fields are areas that influence particles according to the fields' settings. FX Fields can be used as particle attractors (like magnets), for example. They can also reject particles (which allows you to simulate particle/stage collisions) or kill particles once they entered a FX Field.

	CreateFXField
	Creates a FX Field to influence particles once they enter the field's area. Hint: when using redirecting fields (mode 3 or 4), the direction will be determined by the field's current rotation which can be set using GetFXField("MyField").rotation = 0...360 -- Corona GetFXField("MyField"):setRotation(0...360) -- Gideros CreateFXField("name", mode, x,y, strength, radius, visible, [fxID]) name (String) A unique name for this FX Field. mode 0 = Attract particles 1 = Reject particles 2 = Kill particles 3 = Soft redirecting field (wind) 4 = Hard redirecting field x, y (Number) Fields's initial x- and y-coordinate. strength (Number) Strength of the field (attraction / rejection strength etc.). radius (Number) Defines the field's influence radius. visible (Boolean) True: field will be visible (displayed as a circle). fxID (Number) You can assign an ID number to each FX Field (which is 0 by default). The FX Field influences particle types with the same FX ID only (see CreateParticleType). Other particle types won't be affected by this field. This is useful to affect certain particle types only, but also to keep performance as good as possible. Therefore, you should always assign ID's to FX Fields and particle type's to restrict the neccessary calculations to as few particle types as possible.

	DeleteFXField
	Deletes a FX Field. DeleteFXField("name") name (String) A unique name for this FX Field.

	EnableFXField
	Enables or disables a FX Field. FX Fields are enabled by default. EnableFXField("name", state) name (String) A unique name for this FX Field. state (Boolean) true (enabled) or false (disabled).

	GetFXField
	Returns the handle to a FX Field which can then be used like a common display object to position or move the field. Important note! If you stored any handles using GetFXField(), you must set these references to "nil" before you delete the field. Otherwise, they cannot be garbage collected and will remain in memory! So be careful when storing handles! GetFXField("name") name (String) A unique name for this FX Field. Returns: (Display Object) Handle to the FX Field's display object which can be used like a common display object (move, position it etc.). Don't forget to set your reference to this field to "nil" before deleting the field, otherwise it cannot be garbage-collected.

	FX Field Events
	FX Fields can send events once a particle enters or leaves a field. To receive this events, just define your listener function and add it to a field like this: function MyFXFieldListener(event) local Particle = event.Particle local FXField = event.FXField if event.phase == "enter" then print("PARTICLE ENTERED FIELD '"..FXField.name.."'") elseif event.phase == "leave" then print("PARTICLE LEFT FIELD '"..FXField.name.."'") end end Particles.AddFXListener("MyField", MyFXFieldListener) To add a listener to a FX Field: AddFXListener("name", Listener) name (String) A FX Field's unique name. Listener (Function) Function that should be called on event. To remove a listener from a FX Field: RemoveFXListener("name") name (String) A FX Field's unique name. The event object you receive contains the following information: event.phase (String) Will be "enter" if a particle just entered the field or "leave" if a particle just left the field. event.FXField (Display Object) Handle to the FX Field that generated this event. Read event.FXField.name to get the unique name of the field or event.FXField.fxID to get it's fxID, for example. event.Particle (Display Object) Handle of the particle. Read event.Particle.x or with Gideros event.Particle:getX() to get the particle's current x-position, for example. event.x (Number) The x-position of the particle that entered or left the field. event.y (Number) The y-position of the particle that entered or left the field. event.particleType (String) Name of the particle's type.

	OTHER COMMANDS
	Particle Candy also features various useful commands to clean up, freeze or resume particle rendering, clear all current particles or get particle render statistics, for example.

	CleanUp
	Removes all emitters, particles and particle types. Important note! If you stored any emitter handles using GetEmitter(), you must set these references to the emitters to "nil" before you delete the emitters. Otherwise, they cannot be garbage collected and will remain in memory! So be careful when storing emitter handles on your own! CleanUp()

	ClearParticles
	Removes particles from screen. ClearParticles(emitterName) emitterName: (String) Name of a certain emitter. If specified, only particles from that emitter are removed, otherwise ALL particles are removed from screen.

	CountParticles
	Returns the number of particles rendered in the last frame (which may differ from the total amount of existing particles -use GetMaxParticles to retrieve the total amount of particles). CountParticles()

	EnableDebug
	Enables or disables console debugging messages. You should enable it during development and disable it in the final version of your game. Note that printing into the console window lowers the application's performance. EnableDebug(true|false)

	GetMaxParticles
	Returns the maximum number of existing particles. Similar to CountParticles(). The difference is that CountParticles() only returns the number of particles that actually have been rendered during the last loop. GetMaxParticles() returns the total amount of particles, regardless of being rendered in the last frame or not. Use GetMaxParticles() together with GetParticle() to loop through all existing particles, for example. GetMaxParticles() Returns: (Number) Total amount of existing particles.

	GetParticle
	Returns the handle to a particle. Use this command to directly accessing particles (to keep track of their individual positions, for example). Important notes: You should not create persistent references to a particle. Doing so will prevent proper garbage collection. Use temporary references only (if at all). This command should be used to read particle properties only. Changing any properties of a particle on your own could cause unwanted side effects. Keep in mind that particles are volatile objects and therefore can be gone from one frame to the next one (if their lifetime exceeded or if they are outside the screen, for example). GetParticle(index) index: (Number) Index number of the particle to retrieve. Ranges from 1 to GetMaxParticles(). Returns: (Display Object) Handle to the particle. Sample: -- LOOP THROUGH ALL PARTICLES AND DRAW A -- RECT AT EACH PARTICLES CURRENT POSITION: local numParticles = Particles.GetMaxParticles() local Particle for i = 1, numParticles do Particle = Particles.GetParticle(i) if Particle ~= nil then local x = Particle.x -- CORONA local x = Particle:getX() -- GIDEROS end end Below is a list of particle properties that can be retrieved -note: in Gideros, use methods like :getX() instead of .x CORONA GIDEROS (Number) Particle's current x position. .x :getX() (Number) Particle's current x position. .y :getY() (Number) Particle's current y position. .xScale :getScaleX() (Number) Particle's current x scale. .yScale :getScaleY() (Number) Particle's current y scale. .rotation :getRotation() (Number) Particle's current rotation. .alpha :getAlpha() (Number) Particle's current alpha value. .xSpeed .xSpeed (Number) Particle's current x velocity. .ySpeed .ySpeed (Number) Particle's current y velocity. .killTime .killTime (Number) Holds the expiration time of a particle. To kill (remove) a particle, simply set this property to a value in the past ( for example: Particle.killTime = 0 ). This also ensures that particle events are fired. You should not manually delete particles. .emitterName .emitterName (String) Name of this particle's emitter. .isPhysicsParticle .isPhysicsParticle (Boolean) True if the particle is a physics driven particle (see CreatParticleType) or false. .PType.name .PType.name (String) Name of this particle's particle type.

	Freeze
	Use this command to freeze the particle engine at any time. Will also be called automatically when the user presses the "Home" button on the iPhone. This command may also be useful for pause screens within your game. Use WakeUp() to resume the engine. Freeze()

	StartAutoUpdate
	Can be used instead repeatedly calling Particle Candy's Update() function from within your main loop (or if you don't have a main loop at all). When StartAutoUpdate() is called once, Particle Candy keeps updating itself automatically on enterFrame until you call StopAutoUpdate() or CleanUp(). StartAutoUpdate()

	StopAutoUpdate
	Stops auto-updating the particle system (see StartAutoUpdate). StopAutoUpdate()

	Update
	This command renders all particles and is therefore the most important command of the libary. Call it once every frame (from within your main loop, for example). Update()

	WakeUp
	Use this command to resume the particle engine after calling Freeze(). Will also be called automatically when the user pressed the "Home" button on the iPhone and returned to the game. WakeUp()