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¶
- Create a particle manager
var particles = scene.add.particles(key);
- Create particle manager and emitters
or
var particles = scene.add.particles(key, [ emitterConfig0, emitterConfig1, // ... ]);
var particles = scene.make.particles({ key: key, // origin: {x: 0.5, y: 0.5}, add: true, emitters: [ emitterConfig0, emitterConfig1, // ... ] });
- Create particle manager and emitters
- 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, // reserve: 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, ease, easeParams}
{start, end, steps}
: Pick values incremented by steps across a range.{start, end, random}
random
:true
orfalse
{random:[start, end]}
: Pick a random number between start and and.{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
:deathZone
{ type: 'onEnter', source: geom }
lifespan
: The lifespan of emitted particles, in ms.Infinity
: Immortal particle.
reserve
: Creates specified number of inactive particles and adds them to this emitter's pool.name
: The name of this Particle Emitter.- Get emitter by name
var emitter = particles.emitters.getByName(name);
- Get emitter by name
- Format of value
Emit zone¶
emitter.setEmitZone({
type: 'random',
source: geom,
});
source
: Geom like Circle, Ellipse, Rectangle,Triangle, Polygon, BitmapZone, or Path or Curve, which hasgetRandomPoint(point)
method- Custom zone
{ getRandomPoint: function(point) { // point.x = ... // point.y = ... return point; } }
- Custom zone
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 hasgetPoints(quantity, stepRate)
method- Custom edge
{ getPoints: function(quantity, stepRate) { // output = [point0, point1, ...]; // point: Phaser.Math.Vector2, or {x, y} return output; } }
- Custom edge
quantity
: The number of particles to place on the source edge. Set to 0 to usestepRate
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 isfalse
.seamless
: Whether one endpoint will be removed if it's identical to the other. Default istrue
.
quantity or stepRate
Curve source¶
- 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
});
type
: 'onEnter' or 'onLeave'source
: Geom like Circle, Ellipse, Rectangle,Triangle, Polygon- Custom
source
:{ contains: function (x, y) { // ... return bool; } }
- Custom
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
or
emitter.emitParticleAt(x, y, count);
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();
- Start
- Position
- All emitters
or
particles.setPosition(x, y);
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
or
particles.setAngle(angle); // angle in degrees // particles.setRotation(angle); // angle in radians
particles.angle = angle; // particles.rotation = angle;
Scale¶
- Emitter
or
emitter.setScale(value);
emitter.setScaleX(value); emitter.setScaleY(value);
- All emitters
or
particles.setScale(value); // particles.setScale(x, y);
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 fromframes
.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);
Physics¶
- Speed
or
emitter.setSpeed(value);
emitter.setSpeedX(value); emitter.setSpeedY(value);
- Gravity
or
emitter.setGravity(x, y);
emitter.setGravityX(value); emitter.setGravityY(value);
- Bounds
or
emitter.setBounds(x, y, width, height);
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();
- Whether this emitter is at its limit
- 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();
- Clear callback
- For each alive particle
var callback = function(particle, emitter) { /* ... */ } emitter.forEachAlive(callback, context);
- Amount of alive particles
- 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();
- Clear callback
- For each dead particle
var callback = function(particle, emitter) { /* ... */ } emitter.forEachDead(callback, context);
- Add dead particles into pool
emitter.reserve(count);
- Amount of dead particles
- 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
or
var well = particles.createGravityWell(x, y); //var well = particles.createGravityWell(x, y, power, epsilon, gravity);
var well = particles.createGravityWell({ // x: 0, // y: 0, // power: 0, // epsilon: 100, // gravity: 50 });
- Enable
- Active
well.active = true;
- Inactive
well.active = false;
- Active
- 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.
- Return
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);