display.newEmitter()

Type Function
Library display.*
Return value EmitterObject
Revision 2016.2924
Keywords newEmitter
See also EmitterObject:start()
EmitterObject:stop()
EmitterObject:pause()

Overview

This function creates an EmitterObject, used to display particle effects.

Syntax

display.newEmitter( emitterParams [, baseDir] )
emitterParams (required)

Table. A table of parameters for the emitter. See the EmitterObject documentation for a list of valid properties.

baseDir (optional)

Constant. Specifies the base directory where the particle emitter image file is located. Options include system.ResourceDirectory, system.DocumentsDirectory, system.TemporaryDirectory and system.CachesDirectory. Default is system.ResourceDirectory.

Note

On macOS, Particle Designer can be used to design and output emitters as JSON-encoded files. Otherwise, emitter properties can simply be passed to this function as key-value pairs in a Lua table. See the examples below for usage details.

Examples

Key-Value Parameters
-- Table of emitter parameters
local emitterParams = {
    startColorAlpha = 1,
    startParticleSizeVariance = 53.47,
    startColorGreen = 0.3031555,
    yCoordFlipped = -1,
    blendFuncSource = 770,
    rotatePerSecondVariance = 153.95,
    particleLifespan = 0.7237,
    tangentialAcceleration = -144.74,
    finishColorBlue = 0.3699196,
    finishColorGreen = 0.5443883,
    blendFuncDestination = 1,
    startParticleSize = 50.95,
    startColorRed = 0.8373094,
    textureFileName = "fire.png",
    startColorVarianceAlpha = 1,
    maxParticles = 256,
    finishParticleSize = 64,
    duration = -1,
    finishColorRed = 1,
    maxRadiusVariance = 72.63,
    finishParticleSizeVariance = 64,
    gravityy = -671.05,
    speedVariance = 90.79,
    tangentialAccelVariance = -92.11,
    angleVariance = -142.62,
    angle = -244.11
}

-- Create the emitter
local emitter = display.newEmitter( emitterParams )

-- Center the emitter within the content area
emitter.x = display.contentCenterX
emitter.y = display.contentCenterY
Particle Designer
-- Require the JSON library for decoding purposes
local json = require( "json" )

-- Read the exported Particle Designer file (JSON) into a string
local filePath = system.pathForFile( "fire.json" )
local f = io.open( filePath, "r" )
local emitterData = f:read( "*a" )
f:close()

-- Decode the string
local emitterParams = json.decode( emitterData )

-- Create the emitter with the decoded parameters
local emitter = display.newEmitter( emitterParams )

-- Center the emitter within the content area
emitter.x = display.contentCenterX
emitter.y = display.contentCenterY