Particles

Introduction

Particle uses its own lightweight physics system, and can interact only with its Emitter's bounds and zones. Built-in game object of phaser.

  • Author: Richard Davey

Usage

Load texture

scene.load.image(key, url);

Reference: load image

Add particle

  1. Create a particle manager
    var particles = scene.add.particles(key);
    
    • Create particle manager and emitters
      var particles = scene.add.particles(key, [
          emitterConfig0,
          emitterConfig1,
          // ...
      ]);
      
      or
      var particles = scene.make.particles({
          key: key,
          add: true,
          emitters: [
              emitterConfig0,
              emitterConfig1,
              // ...
          ]
      });
      
  2. Create a particle emitter
    var emitter = particles.createEmitter({
        // **basic properties of particles**
        // **initial position**
        // x: 0,             // { min, max }, or { min, max, steps }
        // y: 0,             // { min, max }, or { min, max, steps }
        // follow: null,
        // followOffset: {
        //    x: 0,
        //    y: 0
        // },
        // **emit zone**
        // emitZone: {
        //     type: 'random',    // 'random', or 'edge'
        //     source: geom,      // Geom like Circle, or a Path or Curve
        //     **type = edge**
        //     quantity: 1,
        //     stepRate: 0,
        //     yoyo: false,
        //     seamless: true
        // },
    
        // **target position**
        // moveToX:          // { min, max }, or { min, max, steps }
        // moveToY:          // { min, max }, or { min, max, steps }
        // **death zone**
        // deathZone: {
        //      type: 'onEnter',  // 'onEnter', or 'onLeave'
        //      source: geom      // Geom like Circle or Rect that supports a 'contains' function
        // }
    
        // **angle**
        // radial: true,
        // angle: { min: 0, max: 360 },  // { start, end, steps }
    
        // **scale**
        // scale: 1,             // { start, end },
        // scaleX: 1,
        // scaleY: 1,
    
        // **render**
        // frame:                // one or more texture frames, or a configuration object.
        // alpha: 1,             // { min, max }
        // visible: true,
        // tint: 0xffffffff,     // a number 0xfffffff, or an array [ 0xffff00, 0xff0000, 0x00ff00, 0x0000ff ]
        // blendMode: 'NORMAL',  // Phaser.BlendModes
    
        // delay: 0,
        // lifespan: 1000,       // { min, max }, or { min, max, steps }
    
    
        // **physics**
        // speed:                // { min, max }, or { min, max, steps }
        // speedX:               // { min, max }, or { min, max, steps }
        // speedY:               // { min, max }, or { min, max, steps }
        // gravityX:
        // gravityY:
        // accelerationX:
        // accelerationY:
        // maxVelocityX: 10000,
        // maxVelocityY: 10000,
    
        // **bounce**
        // bounce: 0,
        // bounds: nul,           // Phaser.Geom.Rectangle, or { x, y, width, height }
        // collideBottom: true,
        // collideTop: true,
        // collideLeft: true,
        // collideRight : true,
    
        // **callback**
        // emitCallback: null,
        // emitCallbackScope: null,
        // deathCallback: null,
        // deathCallbackScope: null,
    
        // **custom particle**
        // particleClass: Phaser.GameObjects.Particles.Particle
    
        // **emitter**
        // name: '',
        // on: true,          // set false to stop emitter
        // active: true,      // set false to pause emitter and particles
        // frequency: 0,      // -1 for exploding emitter
        // quantity: 1,       // { min, max }
        // maxParticles: 0,
        // rotate: 0,         // { start, end }, or { start, end, ease },
        // timeScale: 1,
    
    });
    
    • Format of value
      • {min, max} : Pick a random value between min and max
      • {start, end} : Pick values incremented continuously across a range. (ease='Linear')
        • {start, end, ease}
      • {start, end, steps} : Pick values incremented by steps across a range.
      • {start, end, random}
        • random: true or false
      • {min, max, steps} : Pick values between min to max, with steps.
      • {onEmit: function(particle, key, t, value) {return value}} : Get return value from a function invoking.
    • on : Controls if the emitter is currently emitting a particle flow (when frequency >= 0). Already alive particles will continue to update until they expire.
    • active : Whether this emitter updates itself and its particles.
    • frequency
      • 0 : One particle flow cycle for each logic update (the maximum flow frequency).
      • > 0 : The time interval between particle flow cycles in ms.
      • -1 : Exploding emitter.
    • maxParticles
      • 0 : Unlimited.
      • > 0 : Hard limit the amount of particle objects.
    • frames : One or more texture frames, or a configuration object.
      • String or number value
      • Array of string or number value
      • Configuration object :
        {
            frames: [],
            cycle: false,
            quantity: 1
        }
        
    • emitZone :
      • Emit zone
        {
            type: 'random',
            source: geom,
        }            
        
      • Emit edge
        {
            type: 'edge',
            source: curve,
        
            quantity: 1,
            stepRate: 0,
            yoyo: false,
            seamless: true
        }            
        
    • deathZone
      {
          type: 'onEnter',
          source: geom
      }
      
    • lifespan : The lifespan of emitted particles, in ms.
      • Infinity : Immortal particle.
    • name : The name of this Particle Emitter.
      • Get emitter by name
        var emitter = particles.emitters.getByName(name);
        

Emit zone

emitter.setEmitZone({
    type: 'random',
    source: geom,
});

Zone source

  • Get
    var source = emitter.emitZone.source;
    

Clear zone

emitter.setEmitZone();

Emit edge

emitter.setEmitZone({
    type: 'edge',
    source: curve,

    quantity: 1,
    stepRate: 0,
    yoyo: false,
    seamless: true
});
  • source : Geom like Circle, Ellipse, Rectangle,Triangle, Polygon, or Path or Curve, which has getPoints(quantity, stepRate) method
    • Custom edge
      {
          getPoints: function(quantity, stepRate) {
              // output = [point0, point1, ...];  // point: Phaser.Math.Vector2, or {x, y}
              return output;
          }
      }
      
  • quantity : The number of particles to place on the source edge. Set to 0 to use stepRate instead.
  • stepRate : The distance between each particle. When set, quantity is implied and should be set to 0.
  • yoyo : Whether particles are placed from start to end and then end to start. Default is false.
  • seamless : Whether one endpoint will be removed if it's identical to the other. Default is true.

quantity or stepRate

Curve surce

  • Get curve source
    var source = emitter.emitZone.source;
    
  • Update points of curve source
    emitter.emitZone.updateSource();
    
  • Set source to another curve, also update points
    emitter.emitZone.changeSource(curve);
    

Clear edge zone

emitter.setEmitZone();

Death zone

emitter.setDeathZone({
     type: 'onEnter',
     source: geom
});

Zone source

  • Get
    var source = emitter.deathZone.source;
    

Clear zone

emitter.setDeathZone();

Control

  • Start
    emitter.start();  // set `on` to true
    
  • Stop
    emitter.stop();   // set `on` to false
    
  • Pause
    emitter.pause();  // set `active` to false
    
  • Resume
    emitter.resume();  // set `active` to true
    
  • Explode
    emitter.explode(count, x, y);
    
  • Emit
    emitter.emitParticleAt(x, y, count);
    
    or
    emitter.emitParticle(count, x, y);
    
  • Kill all alive particles
    emitter.killAll()
    

Properties

emitter.fromJSON(config);

Position

  • Emitter
    • Position
      emitter.setPosition(x, y);
      
    • Follow
      • Start
        emitter.startFollow(target);
        // emitter.startFollow(target, offsetX, offsetY, trackVisible);
        
        • trackVisible : Whether the emitter's visible state will track the target's visible state.
      • Stop
        emitter.stopFollow();
        
  • All emitters
    particles.setPosition(x, y);
    
    or
    particles.x = x;
    particles.y = y;
    

Rotation

  • Emitter
    emitter.setRadial(bool);   // set true to emit particles in all directions between angle min and max
    emitter.setAngle(value);
    
  • All emitters
    particles.setAngle(angle); // angle in degrees
    // particles.setRotation(angle); // angle in radians
    
    or
    particles.angle = angle;
    // particles.rotation = angle;
    

Scale

  • Emitter
    emitter.setScale(value);
    
    or
    emitter.setScaleX(value);
    emitter.setScaleY(value);
    
  • All emitters
    particles.setScale(value);
    // particles.setScale(x, y);
    
    or
    particles.scaleX = scaleX;
    particles.scaleY = scaleY;
    

Render

  • Frame
    emitter.setFrame(frames);  // pickRandom = true, quantity = 1
    emitter.setFrame(frames, pickRandom, quantity);
    
    • frames : One or more texture frames, or a configuration object.
      • String or number value
      • Array of string or number value
      • Configuration object :
        {
            frames: [],
            cycle: false,
            quantity: 1
        }
        
    • pickRandom : Whether frames should be assigned at random from frames.
    • quantity : The number of consecutive particles that will receive each frame.
  • Alpha
    emitter.setAlpha(value);   // value: 0 ~ 1 
    
  • Visible
    emitter.setVisible(visible);  // visible: true/false
    
  • Blend mode
    emitter.setBlendMode(mode);  // Phaser.BlendModes
    

Physics

  • Speed
    emitter.setSpeed(value);
    
    or
    emitter.setSpeedX(value);
    emitter.setSpeedY(value);
    
  • Gravity
    emitter.setGravity(x, y);
    
    or
    emitter.setGravityX(value);
    emitter.setGravityY(value);
    
  • Bounds
    emitter.setBounds(x, y, width, height);
    
    or
    emitter.setBounds(rect);
    
    • rect : Phaser.Geom.Rectangle, or { x, y, width, height }

Time

  • Lifespan
    emitter.setLifespan(value);  // time in ms
    
  • Frequency
    emitter.setFrequency(frequency, quantity);
    
    • frequency : The time interval (>= 0) of each flow cycle, in ms; or -1 to put the emitter in explosion mode.
    • quantity : The number of particles to release at each flow cycle or explosion.

Quantity

emitter.setQuantity(quantity);

Particles

  • Hard limit the amount of particle objects
    var count = emitter.maxParticles;
    
    • Whether this emitter is at its limit
      var atLimit = emitter.atLimit();
      
  • Alive (active) particles
    • Amount of alive particles
      var count = emitter.getAliveParticleCount();
      
    • Add callback for newly emitted particle
      var callback = function(particle, emitter) { /* ... */ }
      emitter.onParticleEmit(callback, context);
      
      • Clear callback
        emitter.onParticleEmit();
        
    • For each alive particle
      var callback = function(particle, emitter) { /* ... */ }
      emitter.forEachAlive(callback, context);
      
  • Dead (inactive) particles
    • Amount of dead particles
      var count = emitter.getDeadParticleCount();
      
    • Add callback for each particle death
      var callback = function(particle, emitter) { /* ... */ }
      emitter.onParticleDeath(callback, context);
      
      • Clear callback
        emitter.onParticleDeath();
        
    • For each dead particle
      var callback = function(particle, emitter) { /* ... */ }
      emitter.forEachDead(callback, context);
      
    • Add dead particles into pool
      emitter.reserve(count);
      
  • Total (alive + dead) number of particles
    var count = emitter.getParticleCount();
    
  • Custom particle class
    class MyParticle extends Phaser.GameObjects.Particles.Particle {
        constructor (emitter) {
            super(emitter);
            /* ... */
        }
    
        update (delta, step, processors) {
            super.update(delta, step, processors);
            /* ... */
        }
    }
    

Properties

  • emitter
  • frame
  • x, y
  • angle (degree), rotation (radians)
  • alpha, tint, color
  • velocityX, velocityY
  • accelerationX, accelerationY
  • maxVelocityX, maxVelocityY
  • bounce
  • scaleX, scaleY
  • life, lifeCurrent, lifeT

Gravity well

  • Create a gravity well
    var well = particles.createGravityWell(x, y);
    //var well = particles.createGravityWell(x, y, power, epsilon, gravity);
    
    or
    var well = particles.createGravityWell({
        // x: 0,
        // y: 0,
        // power: 0,
        // epsilon: 100,
        // gravity: 50
    });
    
  • Enable
    • Active
      well.active = true;
      
    • Inactive
      well.active = false;
      
  • Position
    well.x = x;
    well.y = y;
    
  • Gravity
    well.gravity = value;
    
  • Power
    well.power = value;
    
  • Custom gravity well
    var well = {
        active: true,
        update: function(particle, delta) {
            // particle.velocityX = 
            // particle.velocityY =       
            // return dead;      
        }
    }
    particles.addGravityWell(well);
    
    • Return true to kill particle.

Particles manager

Fire all emitters

particles.emitParticleAt(x, y);
// particles.emitParticleAt(x, y, count);

Z index of emitters

Z index of emitters is the same as particles.emitters (an array).

  • Bring an emitter to top
    particles.emitters.bringToTop(emitter);
    
  • Send an emitter to bottom
    particles.emitters.sendToBack(emitter);
    
  • Move an emitter up
    particles.emitters.moveUp(emitter);
    
  • Move an emitter down
    particles.emitters.moveDown(emitter);
    
  • Move an emitter to index
    particles.emitters.moveTo(emitter, index);
    
  • Reverse order
    particles.emitters.reverse();
    
  • Shuffle order
    particles.emitters.shuffle();
    
  • Swap 2 emitters
    particles.emitters.swap(emitter0, emitter1);