Class cc.ParticleSystem

Class Summary
Constructor Attributes Constructor Name and Description
 
cc.ParticleSystem()

Particle System base class.

Method Summary

Class Detail

cc.ParticleSystem()

Particle System base class.
Attributes of a Particle System:
- emmision rate of the particles
- Gravity Mode (Mode A):
- gravity
- direction
- speed +- variance
- tangential acceleration +- variance
- radial acceleration +- variance
- Radius Mode (Mode B):
- startRadius +- variance
- endRadius +- variance
- rotate +- variance
- Properties common to all modes:
- life +- life variance
- start spin +- variance
- end spin +- variance
- start size +- variance
- end size +- variance
- start color +- variance
- end color +- variance
- life +- variance
- blending function
- texture

cocos2d also supports particles generated by Particle Designer (http://particledesigner.71squared.com/).
'Radius Mode' in Particle Designer uses a fixed emit rate of 30 hz. Since that can't be guarateed in cocos2d,
cocos2d uses a another approach, but the results are almost identical.
cocos2d supports all the variables used by Particle Designer plus a bit more:
- spinning particles (supported when using ParticleSystem)
- tangential acceleration (Gravity mode)
- radial acceleration (Gravity mode)
- radius direction (Radius mode) (Particle Designer supports outwards to inwards direction only)
It is possible to customize any of the above mentioned properties in runtime. Example: 

 emitter.radialAccel = 15;
 emitter.startSpin = 0;

Field Detail

{Boolean} active
- <@readonly> Indicate whether the particle system is activated.
{Number} angle
- Angle of each particle setter.
{Number} angleVar
- Variation of angle of each particle setter.
{Number} atlasIndex
- Index of system in batch node array.
{Boolean} autoRemoveOnFinish
- Indicate whether the node will be auto-removed when it has no particles left.
<static> <constant> {Number} cc.ParticleSystem.BALL_SHAPE
Ball Shape for ShapeMode of Particle
{cc.SpriteBatchNode} batchNode
- Weak reference to the sprite batch node.
{Number} duration
- How many seconds the emitter wil run. -1 means 'forever'
<static> <constant> {Number} cc.ParticleSystem.DURATION_INFINITY
The Particle emitter lives forever
{Number} emissionRate
- Emission rate of the particles.
{Number} emitterMode
- Emitter modes: CCParticleSystem.MODE_GRAVITY: uses gravity, speed, radial and tangential acceleration; CCParticleSystem.MODE_RADIUS: uses radius movement + rotation.
{cc.Color} endColor
- Ending color of each particle.
{cc.Color} endColorVar
- Variation of the end color.
{Number} endRadius
- Ending radius of the particles. Only available in 'Radius' mode.
{Number} endRadiusVar
- Variation of the ending radius.
{Number} endSize
- End size in pixels of each particle.
{Number} endSizeVar
- Variation of end size in pixels.
{Number} endSpin
- End angle of each particle.
{Number} endSpinVar
- Variation of end angle.
{cc.Point} gravity
- Gravity of the emitter.
{Number} life
- Life of each particle setter.
{Number} lifeVar
- Variation of life.
<static> <constant> {Number} cc.ParticleSystem.MODE_GRAVITY
Gravity mode (A mode)
<static> <constant> {Number} cc.ParticleSystem.MODE_RADIUS
Radius mode (B mode)
{Boolean} opacityModifyRGB
- Indicate whether the alpha value modify color.
{Number} particleCount
- Current quantity of particles that are being simulated.
{Number} positionType
- Particles movement type: cc.ParticleSystem.TYPE_FREE | cc.ParticleSystem.TYPE_GROUPED.
{cc.Point} posVar
- Variation of source position.
{Number} rotatePerS
- Number of degress to rotate a particle around the source pos per second. Only available in 'Radius' mode.
{Number} rotatePerSVar
- Variation of the degress to rotate a particle around the source pos per second.
{Boolean} rotationIsDir
- Indicate whether the rotation of each particle equals to its direction. Only available in 'Gravity' mode.
<static> <constant> {Number} cc.ParticleSystem.SHAPE_MODE
Shape Mode of Particle Draw
{Number} shapeType
- ShapeType of ParticleSystem : cc.ParticleSystem.BALL_SHAPE | cc.ParticleSystem.STAR_SHAPE.
{cc.Point} sourcePos
- Source position of the emitter.
{cc.Point} speed
- Speed of the emitter.
{cc.Point} speedVar
- Variation of the speed.
<static> <constant> {Number} cc.ParticleSystem.STAR_SHAPE
Star Shape for ShapeMode of Particle
<static> <constant> {Number} cc.ParticleSystem.START_RADIUS_EQUAL_TO_END_RADIUS
The starting radius of the particle is equal to the ending radius
<static> <constant> {Number} cc.ParticleSystem.START_SIZE_EQUAL_TO_END_SIZE
The starting size of the particle is equal to the ending size
{cc.Color} startColor
- Start color of each particle.
{cc.Color} startColorVar
- Variation of the start color.
{Number} startRadius
- Starting radius of the particles. Only available in 'Radius' mode.
{Number} startRadiusVar
- Variation of the starting radius.
{Number} startSize
- Start size in pixels of each particle.
{Number} startSizeVar
- Variation of start size in pixels.
{Number} startSpin
- Start angle of each particle.
{Number} startSpinVar
- Variation of start angle.
{Number} tangentialAccel
- Tangential acceleration of each particle. Only available in 'Gravity' mode.
{Number} tangentialAccelVar
- Variation of the tangential acceleration.
{cc.Texture2D} texture
- Texture of Particle System.
<static> <constant> {Number} cc.ParticleSystem.TEXTURE_MODE
Texture Mode of Particle Draw
{Number} totalParticles
- Maximum particles of the system.
<static> <constant> {Number} cc.ParticleSystem.TYPE_FREE
Living particles are attached to the world and are unaffected by emitter repositioning.
<static> <constant> {Number} cc.ParticleSystem.TYPE_GROUPED
Living particles are attached to the emitter and are translated along with it.
<static> <constant> {Number} cc.ParticleSystem.TYPE_RELATIVE
Living particles are attached to the world but will follow the emitter repositioning.
Use case: Attach an emitter to an sprite, and you want that the emitter follows the sprite.

Method Detail

  • {Boolean} addParticle()
    Add a particle to the emitter
    Returns:
    {Boolean}
  • {cc.ParticleSystem} clone()
    to copy object with deep copy. returns a clone of action.
    Returns:
    {cc.ParticleSystem}
  • <static> {cc.ParticleSystem} cc.ParticleSystem.create(plistFile)

    return the string found by key in dict.
    This plist files can be create manually or with Particle Designer:
    http://particledesigner.71squared.com/

    Parameters:
    {String|Number} plistFile
    Deprecated:
    since v3.0 please use new cc.ParticleSysytem(plistFile) instead.
    Returns:
    {cc.ParticleSystem}
  • <static> {cc.ParticleSystem} cc.ParticleSystem.createWithTotalParticles(plistFile)

    return the string found by key in dict.
    This plist files can be create manually or with Particle Designer:
    http://particledesigner.71squared.com/

    Parameters:
    {String|Number} plistFile
    Deprecated:
    since v3.0 please use new cc.ParticleSysytem(plistFile) instead.
    Returns:
    {cc.ParticleSystem}
  • ctor(plistFile)

    return the string found by key in dict.
    This plist files can be create manually or with Particle Designer:
    http://particledesigner.71squared.com/

    Constructor of cc.ParticleSystem
    Parameters:
    {String|Number} plistFile
  • destroyParticleSystem()
    Unschedules the "update" method.
    See:
    scheduleUpdate();
  • {Number} getAngle()
    Return angle of each particle
    Returns:
    {Number}
  • {Number} getAngleVar()
    Return angle variance of each particle
    Returns:
    {Number}
  • {Number} getAtlasIndex()
    return index of system in batch node array
    Returns:
    {Number}
  • {cc.ParticleBatchNode} getBatchNode()
    return weak reference to the cc.SpriteBatchNode that renders the cc.Sprite
    Returns:
    {cc.ParticleBatchNode}
  • {cc.BlendFunc} getBlendFunc()
    get BlendFunc of Particle System
    Returns:
    {cc.BlendFunc}
  • {cc.Rect} getBoundingBoxToWorld()
    return bounding box of particle system in world space
    Returns:
    {cc.Rect}
  • {Number} getDrawMode()
    Return DrawMode of ParticleSystem (Canvas Mode only)
    Returns:
    {Number}
  • {Number} getDuration()
    How many seconds the emitter wil run. -1 means 'forever'
    Returns:
    {Number}
  • {Number} getEmissionRate()
    get emission rate of the particles
    Returns:
    {Number}
  • {Number} getEmitterMode()
    return kind of emitter modes
    Returns:
    {Number}
  • {cc.Color} getEndColor()
    get end color and end color variation of each particle
    Returns:
    {cc.Color}
  • {cc.Color} getEndColorVar()
    get end color variance of each particle
    Returns:
    {cc.Color}
  • {Number} getEndRadius()
    Return ending radius of the particles. Only available in 'Radius' mode.
    Returns:
    {Number}
  • {Number} getEndRadiusVar()
    Return ending radius variance of the particles. Only available in 'Radius' mode.
    Returns:
    {Number}
  • {Number} getEndSize()
    get end size in pixels of each particle
    Returns:
    {Number}
  • {Number} getEndSizeVar()
    get end size variance in pixels of each particle
    Returns:
    {Number}
  • {Number} getEndSpin()
    get end angle of each particle
    Returns:
    {Number}
  • {Number} getEndSpinVar()
    get end angle variance of each particle
    Returns:
    {Number}
  • {cc.Point} getGravity()
    Return Gravity of emitter
    Returns:
    {cc.Point}
  • {Number} getLife()
    Return life of each particle
    Returns:
    {Number}
  • {Number} getLifeVar()
    Return life variance of each particle
    Returns:
    {Number}
  • {Number} getParticleCount()
    Quantity of particles that are being simulated at the moment
    Returns:
    {Number}
  • {Number} getPositionType()
    get particles movement type: Free or Grouped
    Returns:
    {Number}
  • {cc.Point | Object} getPosVar()
    Return Position variance of the emitter
    Returns:
    {cc.Point | Object}
  • {Number} getRadialAccel()
    Return radial acceleration of each particle. Only available in 'Gravity' mode.
    Returns:
    {Number}
  • {Number} getRadialAccelVar()
    Return radial acceleration variance of each particle. Only available in 'Gravity' mode.
    Returns:
    {Number}
  • {Number} getRotatePerSecond()
    get Number of degress to rotate a particle around the source pos per second. Only available in 'Radius' mode.
    Returns:
    {Number}
  • {Number} getRotatePerSecondVar()
    Return Variance in degrees for rotatePerSecond. Only available in 'Radius' mode.
    Returns:
    {Number}
  • {boolean} getRotationIsDir()
    get the rotation of each particle to its direction Only available in 'Gravity' mode.
    Returns:
    {boolean}
  • {Number} getShapeType()
    Return ShapeType of ParticleSystem (Canvas Mode only)
    Returns:
    {Number}
  • {cc.Point | Object} getSourcePosition()
    Return sourcePosition of the emitter
    Returns:
    {cc.Point | Object}
  • {Number} getSpeed()
    Return Speed of each particle
    Returns:
    {Number}
  • {Number} getSpeedVar()
    return speed variance of each particle. Only available in 'Gravity' mode.
    Returns:
    {Number}
  • {cc.Color} getStartColor()
    set start color of each particle
    Returns:
    {cc.Color}
  • {cc.Color} getStartColorVar()
    get start color variance of each particle
    Returns:
    {cc.Color}
  • {Number} getStartRadius()
    Return starting radius of the particles. Only available in 'Radius' mode.
    Returns:
    {Number}
  • {Number} getStartRadiusVar()
    Return starting radius variance of the particles. Only available in 'Radius' mode.
    Returns:
    {Number}
  • {Number} getStartSize()
    get start size in pixels of each particle
    Returns:
    {Number}
  • {Number} getStartSizeVar()
    get size variance in pixels of each particle
    Returns:
    {Number}
  • {Number} getStartSpin()
    get initial angle of each particle
    Returns:
    {Number}
  • {Number} getStartSpinVar()
    get initial angle variance of each particle
    Returns:
    {Number}
  • {Number} getTangentialAccel()
    Return tangential acceleration of each particle. Only available in 'Gravity' mode.
    Returns:
    {Number}
  • {Number} getTangentialAccelVar()
    Return tangential acceleration variance of each particle. Only available in 'Gravity' mode.
    Returns:
    {Number}
  • {cc.Texture2D} getTexture()
    get Texture of Particle System
    Returns:
    {cc.Texture2D}
  • {Number} getTotalParticles()
    get maximum particles of the system
    Returns:
    {Number}
  • ignoreColor(ignore)
    This is a hack function for performance, it's only available on Canvas mode.
    It's very expensive to change color on Canvas mode, so if set it to true, particle system will ignore the changing color operation.
    Parameters:
    {boolean} ignore
  • init()
    initializes a cc.ParticleSystem
  • initParticle(particle)
    Initializes a particle
    Parameters:
    {cc.Particle} particle
  • initTexCoordsWithRect(pointRect)

    initializes the texture with a rectangle measured Points
    pointRect should be in Texture coordinates, not pixel coordinates

    Parameters:
    {cc.Rect} pointRect
  • {Boolean} initWithDictionary(dictionary, dirname)
    initializes a particle system from a NSDictionary and the path from where to load the png
    Parameters:
    {object} dictionary
    {String} dirname
    Returns:
    {Boolean}
  • {boolean} initWithFile(plistFile)

    initializes a CCParticleSystem from a plist file.
    This plist files can be creted manually or with Particle Designer:
    http://particledesigner.71squared.com/

    Parameters:
    {String} plistFile
    Returns:
    {boolean}
  • {Boolean} initWithTotalParticles(numberOfParticles)
    Initializes a system with a fixed number of particles
    Parameters:
    {Number} numberOfParticles
    Returns:
    {Boolean}
  • {Boolean} isActive()
    Return ParticleSystem is active
    Returns:
    {Boolean}
  • {Boolean} isAutoRemoveOnFinish()

    return whether or not the node will be auto-removed when it has no particles left.
    By default it is false.

    Returns:
    {Boolean}
  • {Boolean} isBlendAdditive()

    whether or not the particles are using blend additive.
    If enabled, the following blending function will be used.

       source blend function = GL_SRC_ALPHA;
   dest blend function = GL_ONE;
    Returns:
    {Boolean}
  • {Boolean} isFull()
    whether or not the system is full
    Returns:
    {Boolean}
  • {Boolean} isOpacityModifyRGB()
    does the alpha value modify color getter
    Returns:
    {Boolean}
  • listenBackToForeground(obj)
    listen the event that coming to foreground on Android (An empty function for native)
    Parameters:
    {cc.Class} obj
  • postStep()
    should be overridden by subclasses
  • resetSystem()
    Kill all living particles.
  • setAngle(angle)
    angle of each particle setter
    Parameters:
    {Number} angle
  • setAngleVar(angleVar)
    angle variance of each particle setter
    Parameters:
    angleVar
  • setAtlasIndex(atlasIndex)
    set index of system in batch node array
    Parameters:
    {Number} atlasIndex
  • setAutoRemoveOnFinish(isAutoRemoveOnFinish)

    set whether or not the node will be auto-removed when it has no particles left.
    By default it is false.

    Parameters:
    {Boolean} isAutoRemoveOnFinish
  • setBatchNode(batchNode)
    set weak reference to the cc.SpriteBatchNode that renders the cc.Sprite
    Parameters:
    {cc.ParticleBatchNode} batchNode
  • setBlendAdditive(isBlendAdditive)

    whether or not the particles are using blend additive.
    If enabled, the following blending function will be used.

    Parameters:
    {Boolean} isBlendAdditive
  • setBlendFunc(src, dst)
    set BlendFunc of Particle System
    Parameters:
    {Number} src
    {Number} dst
  • setDisplayFrame(spriteFrame)

    Sets a new CCSpriteFrame as particle.
    WARNING: this method is experimental. Use setTextureWithRect instead.

    Parameters:
    {cc.SpriteFrame} spriteFrame
  • setDrawMode(drawMode)
    DrawMode of ParticleSystem setter (Canvas Mode only)
    Parameters:
    {Number} drawMode
  • setDuration(duration)
    set run seconds of the emitter
    Parameters:
    {Number} duration
  • setEmissionRate(emissionRate)
    set emission rate of the particles
    Parameters:
    {Number} emissionRate
  • setEmitterMode(emitterMode)

    Switch between different kind of emitter modes:
    - CCParticleSystem.MODE_GRAVITY: uses gravity, speed, radial and tangential acceleration
    - CCParticleSystem.MODE_RADIUS: uses radius movement + rotation

    Parameters:
    {Number} emitterMode
  • setEndColor(endColor)
    set end color and end color variation of each particle
    Parameters:
    {cc.Color} endColor
  • setEndColorVar(endColorVar)
    set end color variance of each particle
    Parameters:
    {cc.Color} endColorVar
  • setEndRadius(endRadius)
    ending radius of the particles setter. Only available in 'Radius' mode.
    Parameters:
    {Number} endRadius
  • setEndRadiusVar(endRadiusVar)
    ending radius variance of the particles setter. Only available in 'Radius' mode.
    Parameters:
    endRadiusVar
  • setEndSize(endSize)
    set end size in pixels of each particle
    Parameters:
    endSize
  • setEndSizeVar(endSizeVar)
    set end size variance in pixels of each particle
    Parameters:
    {Number} endSizeVar
  • setEndSpin(endSpin)
    set end angle of each particle
    Parameters:
    {Number} endSpin
  • setEndSpinVar(endSpinVar)
    set end angle variance of each particle
    Parameters:
    {Number} endSpinVar
  • setGravity(gravity)
    Gravity of emitter setter
    Parameters:
    {cc.Point} gravity
  • setLife(life)
    life of each particle setter
    Parameters:
    {Number} life
  • setLifeVar(lifeVar)
    life variance of each particle setter
    Parameters:
    {Number} lifeVar
  • setOpacityModifyRGB(newValue)
    does the alpha value modify color setter
    Parameters:
    newValue
  • setParticleCount(particleCount)
    Quantity of particles setter
    Parameters:
    {Number} particleCount
  • setPositionType(positionType)
    set particles movement type: Free or Grouped
    Parameters:
    {Number} positionType
  • setPosVar(posVar)
    Position variance of the emitter setter
    Parameters:
    {cc.Point} posVar
  • setRadialAccel(radialAccel)
    radial acceleration of each particle setter. Only available in 'Gravity' mode.
    Parameters:
    {Number} radialAccel
  • setRadialAccelVar(radialAccelVar)
    radial acceleration variance of each particle setter. Only available in 'Gravity' mode.
    Parameters:
    {Number} radialAccelVar
  • setRotatePerSecond(degrees)
    set Number of degress to rotate a particle around the source pos per second. Only available in 'Radius' mode.
    Parameters:
    {Number} degrees
  • setRotatePerSecondVar(degrees)
    Variance in degrees for rotatePerSecond setter. Only available in 'Radius' mode.
    Parameters:
    degrees
  • setRotationIsDir(t)
    set the rotation of each particle to its direction Only available in 'Gravity' mode.
    Parameters:
    {boolean} t
  • setShapeType(shapeType)
    ShapeType of ParticleSystem setter (Canvas Mode only)
    Parameters:
    {Number} shapeType
  • setSourcePosition(sourcePosition)
    sourcePosition of the emitter setter
    Parameters:
    sourcePosition
  • setSpeed(speed)
    Speed of each particle setter
    Parameters:
    {Number} speed
  • setSpeedVar(speedVar)
    speed variance of each particle setter. Only available in 'Gravity' mode.
    Parameters:
    {Number} speedVar
  • setStartColor(startColor)
    get start color of each particle
    Parameters:
    {cc.Color} startColor
  • setStartColorVar(startColorVar)
    set start color variance of each particle
    Parameters:
    {cc.Color} startColorVar
  • setStartRadius(startRadius)
    starting radius of the particles setter. Only available in 'Radius' mode.
    Parameters:
    {Number} startRadius
  • setStartRadiusVar(startRadiusVar)
    starting radius variance of the particles setter. Only available in 'Radius' mode.
    Parameters:
    {Number} startRadiusVar
  • setStartSize(startSize)
    set start size in pixels of each particle
    Parameters:
    {Number} startSize
  • setStartSizeVar(startSizeVar)
    set size variance in pixels of each particle
    Parameters:
    {Number} startSizeVar
  • setStartSpin(startSpin)
    set initial angle of each particle
    Parameters:
    {Number} startSpin
  • setStartSpinVar(startSpinVar)
    set initial angle variance of each particle
    Parameters:
    {Number} startSpinVar
  • setTangentialAccel(tangentialAccel)
    Tangential acceleration of each particle setter. Only available in 'Gravity' mode.
    Parameters:
    {Number} tangentialAccel
  • setTangentialAccelVar(tangentialAccelVar)
    tangential acceleration variance of each particle setter. Only available in 'Gravity' mode.
    Parameters:
    {Number} tangentialAccelVar
  • setTexture(texture)
    set Texture of Particle System
    Parameters:
    {cc.Texture2D} texture
  • setTextureWithRect(texture, rect)
    Sets a new texture with a rect. The rect is in Points.
    Parameters:
    {cc.Texture2D} texture
    {cc.Rect} rect
  • setTotalParticles(tp)
    set maximum particles of the system
    Parameters:
    {Number} tp
    totalParticles
  • stopSystem()
    stop emitting particles. Running particles will continue to run until they die
  • update(dt)
    update emitter's status
    Parameters:
    {Number} dt
    delta time
  • updateQuadWithParticle(particle, newPosition)
    should be overridden by subclasses
    Parameters:
    {cc.Particle} particle
    {cc.Point} newPosition
  • updateWithNoTime()
    update emitter's status (dt = 0)