Merge pull request #3600 from samme/docs/particles

Add docs for gameobjects/particles

src/gameobjects/particles/EmitterOp.js

@@ -11,26 +11,81 @@ var GetFastValue = require('../../utils/object/GetFastValue');
 var Wrap = require('../../math/Wrap');
 
 /**
- * The returned value sets what the property will be at the START of the particles life, on emit.
+ * The returned value sets what the property will be at the START of the particle's life, on emit.
  * @callback EmitterOpOnEmitCallback
  *
- * @param {Phaser.GameObjects.Particles.Particle} particle - [description]
- * @param {string} key - [description]
- * @param {number} value - [description]
+ * @param {Phaser.GameObjects.Particles.Particle} particle - The particle.
+ * @param {string} key - The name of the property.
+ * @param {number} value - The current value of the property.
  *
- * @return {number} [description]
+ * @return {number} The new value of the property.
  */
 
 /**
- * The returned value updates the property for the duration of the particles life.
+ * The returned value updates the property for the duration of the particle's life.
  * @callback EmitterOpOnUpdateCallback
  *
- * @param {Phaser.GameObjects.Particles.Particle} particle - [description]
- * @param {string} key - [description]
- * @param {float} t - The T value (between 0 and 1)
- * @param {number} value - [description]
+ * @param {Phaser.GameObjects.Particles.Particle} particle - The particle.
+ * @param {string} key - The name of the property.
+ * @param {float} t - The normalized lifetime of the particle, between 0 (start) and 1 (end).
+ * @param {number} value - The current value of the property.
  *
- * @return {number} [description]
+ * @return {number} The new value of the property.
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomConfig
+ *
+ * @property {float[]} random - The minimum and maximum values, as [min, max].
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomMinMaxConfig
+ *
+ * @property {float} min - The minimum value.
+ * @property {float} max - The maximum value.
+ */
+
+/**
+ * Defines an operation yielding a random value within a range.
+ * @typedef {object} EmitterOpRandomStartEndConfig
+ *
+ * @property {float} start - The starting value.
+ * @property {float} end - The ending value.
+ * @property {boolean} random - If false, this becomes {@link EmitterOpEaseConfig}.
+ */
+
+/**
+ * Defines an operation yielding a value incremented continuously across a range.
+ * @typedef {object} EmitterOpEaseConfig
+ *
+ * @property {float} start - The starting value.
+ * @property {float} end - The ending value.
+ * @property {string} [ease='Linear'] - The name of the easing function.
+ */
+
+/**
+ * Defines an operation yielding a value incremented by steps across a range.
+ * @typedef {object} EmitterOpSteppedConfig
+ *
+ * @property {number} start - The starting value.
+ * @property {number} end - The ending value.
+ * @property {number} steps - The number of steps between start and end.
+ */
+
+/**
+ * @typedef {object} EmitterOpCustomEmitConfig
+ *
+ * @property {EmitterOpOnEmitCallback} onEmit - [description]
+ */
+
+/**
+ * @typedef {object} EmitterOpCustomUpdateConfig
+ *
+ * @property {EmitterOpOnEmitCallback} [onEmit] - [description]
+ * @property {EmitterOpOnUpdateCallback} onUpdate - [description]
  */
 
 /**
@@ -247,7 +302,7 @@ var EmitterOp = new Class({
             //  x: 400
 
             this.onEmit = this.staticValueEmit;
-            this.onUpdate = this.staticValueUpdate;
+            this.onUpdate = this.staticValueUpdate; // How?
         }
         else if (Array.isArray(value))
         {
@@ -327,6 +382,7 @@ var EmitterOp = new Class({
 
                 //  x: { start: 100, end: 400, [ ease: 'Linear' ] }
 
+
                 var easeType = this.has(value, 'ease') ? value.ease : 'Linear';
 
                 this.ease = GetEaseFunction(easeType);
@@ -336,6 +392,9 @@ var EmitterOp = new Class({
                     this.onEmit = this.easedValueEmit;
                 }
 
+                //  BUG: alpha, rotate, scaleX, scaleY, or tint are eased here if {min, max} is given.
+                //  Probably this branch should exclude isRandom entirely.
+
                 this.onUpdate = this.easeValueUpdate;
             }
         }

src/gameobjects/particles/Particle.js

@@ -10,7 +10,8 @@ var DistanceBetween = require('../../math/distance/DistanceBetween');
 
 /**
  * @classdesc
- * [description]
+ * A Particle is a simple Game Object controlled by a Particle Emitter and Manager, and rendered by the Manager.
+ * It uses its own lightweight physics system, and can interact only with its Emitter's bounds and zones.
  *
  * @class Particle
  * @memberOf Phaser.GameObjects.Particles
@@ -37,7 +38,7 @@ var Particle = new Class({
         this.emitter = emitter;
 
         /**
-         * [description]
+         * The texture frame used to render this Particle.
          *
          * @name Phaser.GameObjects.Particles.Particle#frame
          * @type {Phaser.Textures.Frame}
@@ -47,7 +48,7 @@ var Particle = new Class({
         this.frame = null;
 
         /**
-         * [description]
+         * The position of this Particle within its Emitter's particle pool.
          *
          * @name Phaser.GameObjects.Particles.Particle#index
          * @type {number}
@@ -207,7 +208,7 @@ var Particle = new Class({
         this.tint = 0xffffffff;
 
         /**
-         * [description]
+         * The full color of this Particle, computed from its alpha and tint.
          *
          * @name Phaser.GameObjects.Particles.Particle#color
          * @type {number}
@@ -246,7 +247,7 @@ var Particle = new Class({
         this.delayCurrent = 0;
 
         /**
-         * The normalized lifespan T value.
+         * The normalized lifespan T value, where 0 is the start and 1 is the end.
          *
          * @name Phaser.GameObjects.Particles.Particle#lifeT
          * @type {float}
@@ -405,7 +406,7 @@ var Particle = new Class({
      * @param {Phaser.GameObjects.Particles.ParticleEmitter} emitter - The Emitter that is updating this Particle.
      * @param {number} delta - The delta time in ms.
      * @param {float} step - The delta value divided by 1000.
-     * @param {array} processors - [description]
+     * @param {array} processors - Particle processors (gravity wells).
      */
     computeVelocity: function (emitter, delta, step, processors)
     {

src/gameobjects/particles/ParticleEmitterManager.js

@@ -14,7 +14,7 @@ var Render = require('./ParticleManagerRender');
 
 /**
  * @classdesc
- * [description]
+ * A Particle Emitter Manager creates and controls {@link Phaser.GameObjects.Particles.ParticleEmitter Particle Emitters} and {@link Phaser.GameObjects.Particles.GravityWell Gravity Wells}.
  *
  * @class ParticleEmitterManager
  * @extends Phaser.GameObjects.GameObject
@@ -26,10 +26,10 @@ var Render = require('./ParticleManagerRender');
  * @extends Phaser.GameObjects.Particles.Components.Visible
  * @extends Phaser.GameObjects.Particles.Components.Pipeline
  *
- * @param {Phaser.Scene} scene - [description]
- * @param {string} texture - [description]
- * @param {(string|integer)} frame - [description]
- * @param {Phaser.GameObjects.Particles.ParticleEmitter[]} emitters - [description]
+ * @param {Phaser.Scene} scene - The Scene to which this Emitter Manager belongs.
+ * @param {string} texture - The key of the Texture this Emitter Manager will use to render particles, as stored in the Texture Manager.
+ * @param {(string|integer)} frame - An optional frame from the Texture this Emitter Manager will use to render particles.
+ * @param {ParticleEmitterConfig|ParticleEmitterConfig[]} emitters - Configuration settings for one or more emitters to create.
  */
 var ParticleEmitterManager = new Class({
 
@@ -53,7 +53,7 @@ var ParticleEmitterManager = new Class({
          * [description]
          *
          * @name Phaser.GameObjects.Particles.ParticleEmitterManager#blendMode
-         * @type {number}
+         * @type {integer}
          * @default -1
          * @private
          * @since 3.0.0
@@ -61,7 +61,9 @@ var ParticleEmitterManager = new Class({
         this.blendMode = -1;
 
         /**
-         * [description]
+         * The time scale applied to all emitters and particles, affecting flow rate, lifespan, and movement.
+         * Values larger than 1 are faster than normal.
+         * This is multiplied with any timeScale set on each individual emitter.
          *
          * @name Phaser.GameObjects.Particles.ParticleEmitterManager#timeScale
          * @type {float}
@@ -71,7 +73,7 @@ var ParticleEmitterManager = new Class({
         this.timeScale = 1;
 
         /**
-         * [description]
+         * The texture used to render this Emitter Manager's particles.
          *
          * @name Phaser.GameObjects.Particles.ParticleEmitterManager#texture
          * @type {Phaser.Textures.Texture}
@@ -81,7 +83,7 @@ var ParticleEmitterManager = new Class({
         this.texture = null;
 
         /**
-         * [description]
+         * The texture frame used to render this Emitter Manager's particles.
          *
          * @name Phaser.GameObjects.Particles.ParticleEmitterManager#frame
          * @type {Phaser.Textures.Frame}
@@ -91,7 +93,7 @@ var ParticleEmitterManager = new Class({
         this.frame = null;
 
         /**
-         * [description]
+         * Names of this Emitter Manager's texture frames.
          *
          * @name Phaser.GameObjects.Particles.ParticleEmitterManager#frameNames
          * @type {Phaser.Textures.Frame[]}
@@ -144,7 +146,7 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * Sets the texture and frame this Game Object will use to render with.
+     * Sets the texture and frame this Emitter Manager will use to render with.
      *
      * Textures are referenced by their string-based keys, as stored in the Texture Manager.
      *
@@ -154,7 +156,7 @@ var ParticleEmitterManager = new Class({
      * @param {string} key - The key of the texture to be used, as stored in the Texture Manager.
      * @param {(string|integer)} [frame] - The name or index of the frame within the Texture.
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     setTexture: function (key, frame)
     {
@@ -164,7 +166,7 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * Sets the frame this Game Object will use to render with.
+     * Sets the frame this Emitter Manager will use to render with.
      *
      * The Frame has to belong to the current Texture being used.
      *
@@ -175,7 +177,7 @@ var ParticleEmitterManager = new Class({
      *
      * @param {(string|integer)} [frame] - The name or index of the frame within the Texture.
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     setFrame: function (frame)
     {
@@ -189,15 +191,15 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * [description]
+     * Assigns texture frames to an emitter.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#setEmitterFrames
      * @since 3.0.0
      *
-     * @param {(Phaser.Textures.Frame|Phaser.Textures.Frame[])} frames - [description]
-     * @param {Phaser.GameObjects.Particles.ParticleEmitter} emitter - [description]
+     * @param {(Phaser.Textures.Frame|Phaser.Textures.Frame[])} frames - The texture frames.
+     * @param {Phaser.GameObjects.Particles.ParticleEmitter} emitter - The particle emitter to modify.
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     setEmitterFrames: function (frames, emitter)
     {
@@ -233,7 +235,7 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * Adds an existing Particle Emitter to this Manager.
+     * Adds an existing Particle Emitter to this Emitter Manager.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#addEmitter
      * @since 3.0.0
@@ -248,7 +250,7 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * Creates a new Particle Emitter object, adds it to this Manager and returns a reference to it.
+     * Creates a new Particle Emitter object, adds it to this Emitter Manager and returns a reference to it.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#createEmitter
      * @since 3.0.0
@@ -263,7 +265,7 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * Adds an existing Gravity Well object to this Manager.
+     * Adds an existing Gravity Well object to this Emitter Manager.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#addGravityWell
      * @since 3.0.0
@@ -278,7 +280,7 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * Creates a new Gravity Well, adds it to this Manager and returns a reference to it.
+     * Creates a new Gravity Well, adds it to this Emitter Manager and returns a reference to it.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#createGravityWell
      * @since 3.0.0
@@ -293,16 +295,16 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * [description]
+     * Emits particles from each active emitter.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#emitParticle
      * @since 3.0.0
      *
-     * @param {integer} count - [description]
-     * @param {number} x - [description]
-     * @param {number} y - [description]
+     * @param {integer} [count] - The number of particles to release from each emitter. The default is the emitter's own {@link Phaser.GameObjects.Particles.ParticleEmitter#quantity}.
+     * @param {float} [x] - The x-coordinate to to emit particles from. The default is the x-coordinate of the emitter's current location.
+     * @param {float} [y] - The y-coordinate to to emit particles from. The default is the y-coordinate of the emitter's current location.
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     emitParticle: function (count, x, y)
     {
@@ -322,16 +324,16 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * [description]
+     * Emits particles from each active emitter.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#emitParticleAt
      * @since 3.0.0
      *
-     * @param {number} x - [description]
-     * @param {number} y - [description]
-     * @param {integer} count - [description]
+     * @param {float} [x] - The x-coordinate to to emit particles from. The default is the x-coordinate of the emitter's current location.
+     * @param {float} [y] - The y-coordinate to to emit particles from. The default is the y-coordinate of the emitter's current location.
+     * @param {integer} [count] - The number of particles to release from each emitter. The default is the emitter's own {@link Phaser.GameObjects.Particles.ParticleEmitter#quantity}.
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     emitParticleAt: function (x, y, count)
     {
@@ -348,7 +350,7 @@ var ParticleEmitterManager = new Class({
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#pause
      * @since 3.0.0
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     pause: function ()
     {
@@ -363,7 +365,7 @@ var ParticleEmitterManager = new Class({
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#resume
      * @since 3.0.0
      *
-     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Game Object.
+     * @return {Phaser.GameObjects.Particles.ParticleEmitterManager} This Emitter Manager.
      */
     resume: function ()
     {
@@ -373,12 +375,12 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * [description]
+     * Gets all active particle processors (gravity wells).
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#getProcessors
      * @since 3.0.0
      *
-     * @return {Phaser.GameObjects.Particles.GravityWell[]} [description]
+     * @return {Phaser.GameObjects.Particles.GravityWell[]} - The active gravity wells.
      */
     getProcessors: function ()
     {
@@ -386,13 +388,13 @@ var ParticleEmitterManager = new Class({
     },
 
     /**
-     * [description]
+     * Updates all active emitters.
      *
      * @method Phaser.GameObjects.Particles.ParticleEmitterManager#preUpdate
      * @since 3.0.0
      *
      * @param {integer} time - The current timestamp as generated by the Request Animation Frame or SetTimeout.
-     * @param {number} delta - The delta time, in ms, elapsed since the last frame.
+     * @param {float} delta - The delta time, in ms, elapsed since the last frame.
      */
     preUpdate: function (time, delta)
     {

src/gameobjects/particles/zones/DeathZone.js

@@ -6,6 +6,27 @@
 
 var Class = require('../../../utils/Class');
 
+/**
+ * @callback DeathZoneSourceCallback
+ *
+ * @param {float} x - [description]
+ * @param {float} y - [description]
+ *
+ * @return {boolean} - True if the coordinates are within the source area.
+ */
+
+/**
+ * @typedef {object} DeathZoneSource
+ *
+ * @property {DeathZoneSourceCallback} contains
+ *
+ * @see Phaser.Geom.Circle
+ * @see Phaser.Geom.Ellipse
+ * @see Phaser.Geom.Polygon
+ * @see Phaser.Geom.Rectangle
+ * @see Phaser.Geom.Triangle
+ */
+
 /**
  * @classdesc
  * A Death Zone.
@@ -20,7 +41,7 @@ var Class = require('../../../utils/Class');
  * @constructor
  * @since 3.0.0
  *
- * @param {object} source - An object instance that has a `contains` method that returns a boolean when given `x` and `y` arguments.
+ * @param {DeathZoneSource} source - An object instance that has a `contains` method that returns a boolean when given `x` and `y` arguments.
  * @param {boolean} killOnEnter - Should the Particle be killed when it enters the zone? `true` or leaves it? `false`
  */
 var DeathZone = new Class({
@@ -34,7 +55,7 @@ var DeathZone = new Class({
          * This could be a Geometry shape, such as `Phaser.Geom.Circle`, or your own custom object.
          *
          * @name Phaser.GameObjects.Particles.Zones.DeathZone#source
-         * @type {object}
+         * @type {DeathZoneSource}
          * @since 3.0.0
          */
         this.source = source;

src/gameobjects/particles/zones/EdgeZone.js

@@ -6,16 +6,40 @@
 
 var Class = require('../../../utils/Class');
 
+/**
+ * @callback EdgeZoneSourceCallback
+ *
+ * @param {integer} quantity - [description]
+ * @param {integer} [stepRate] - [description]
+ *
+ * @return {Phaser.Geom.Point[]} - [description]
+ */
+
+/**
+ * @typedef {object} EdgeZoneSource
+ *
+ * @property {EdgeZoneSourceCallback} getPoints - A function placing points on the source's edge or edges.
+ *
+ * @see Phaser.Curves.Curve
+ * @see Phaser.Curves.Path
+ * @see Phaser.Geom.Circle
+ * @see Phaser.Geom.Ellipse
+ * @see Phaser.Geom.Line
+ * @see Phaser.Geom.Polygon
+ * @see Phaser.Geom.Rectangle
+ * @see Phaser.Geom.Triangle
+ */
+
 /**
  * @classdesc
- * [description]
+ * A zone that places particles on a shape's edges.
  *
  * @class EdgeZone
  * @memberOf Phaser.GameObjects.Particles.Zones
  * @constructor
  * @since 3.0.0
  *
- * @param {object} source - [description]
+ * @param {EdgeZoneSource} source - An object instance with a `getPoints(quantity, stepRate)` method returning an array of points.
  * @param {number} quantity - [description]
  * @param {number} stepRate - [description]
  * @param {boolean} [yoyo=false] - [description]
@@ -34,7 +58,7 @@ var EdgeZone = new Class({
          * [description]
          *
          * @name Phaser.GameObjects.Particles.Zones.EdgeZone#source
-         * @type {object}
+         * @type {EdgeZoneSource|RandomZoneSource}
          * @since 3.0.0
          */
         this.source = source;

src/gameobjects/particles/zones/RandomZone.js

@@ -7,16 +7,35 @@
 var Class = require('../../../utils/Class');
 var Vector2 = require('../../../math/Vector2');
 
+/**
+ * @callback RandomZoneSourceCallback
+ *
+ * @param {Phaser.Math.Vector2} point - A point to modify.
+ */
+
+/**
+ * @typedef {object} RandomZoneSource
+ *
+ * @property {RandomZoneSourceCallback} getRandomPoint - A function modifying its point argument.
+ *
+ * @see Phaser.Geom.Circle
+ * @see Phaser.Geom.Ellipse
+ * @see Phaser.Geom.Line
+ * @see Phaser.Geom.Polygon
+ * @see Phaser.Geom.Rectangle
+ * @see Phaser.Geom.Triangle
+ */
+
 /**
  * @classdesc
- * [description]
+ * A zone that places particles randomly within a shape's area.
  *
  * @class RandomZone
  * @memberOf Phaser.GameObjects.Particles.Zones
  * @constructor
  * @since 3.0.0
  *
- * @param {object} source - [description]
+ * @param {RandomZoneSource} source - An object instance with a `getRandomPoint(point)` method.
  */
 var RandomZone = new Class({
 
@@ -28,7 +47,7 @@ var RandomZone = new Class({
          * [description]
          *
          * @name Phaser.GameObjects.Particles.Zones.RandomZone#source
-         * @type {object}
+         * @type {RandomZoneSource}
          * @since 3.0.0
          */
         this.source = source;