diff --git a/CHANGELOG.md b/CHANGELOG.md index 048109fd0..62241c394 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -157,7 +157,7 @@ My thanks to the following for helping with the Phaser 3 Examples, Docs and TypeScript definitions, either by reporting errors, fixing them or helping author the docs: -@fselcukcan Bambosh @louisth @hexus @javigaralva @samme @BeLi4L @jcyuan +@fselcukcan Bambosh @louisth @hexus @javigaralva @samme @BeLi4L @jcyuan @javigaralva ## Version 3.21.0 - Senku - 22nd November 2019 diff --git a/src/curves/Curve.js b/src/curves/Curve.js index 45697c14c..c343bb131 100644 --- a/src/curves/Curve.js +++ b/src/curves/Curve.js @@ -20,7 +20,7 @@ var Vector2 = require('../math/Vector2'); * @constructor * @since 3.0.0 * - * @param {string} type - [description] + * @param {string} type - The curve type. */ var Curve = new Class({ @@ -78,7 +78,7 @@ var Curve = new Class({ this.needsUpdate = true; /** - * [description] + * For a curve on a Path, `false` means the Path will ignore this curve. * * @name Phaser.Curves.Curve#active * @type {boolean} @@ -131,7 +131,7 @@ var Curve = new Class({ // So you can chain graphics calls return graphics.strokePoints(this.getPoints(pointsTotal)); }, - + /** * Returns a Rectangle where the position and dimensions match the bounds of this Curve. * @@ -187,7 +187,7 @@ var Curve = new Class({ }, /** - * [description] + * Get a point at the end of the curve. * * @method Phaser.Curves.Curve#getEndPoint * @since 3.0.0 @@ -209,7 +209,7 @@ var Curve = new Class({ * @method Phaser.Curves.Curve#getLength * @since 3.0.0 * - * @return {number} [description] + * @return {number} The total length of the curve. */ getLength: function () { @@ -220,14 +220,22 @@ var Curve = new Class({ /** - * Get list of cumulative segment lengths + * Get a list of cumulative segment lengths. + * + * These lengths are + * + * - [0] 0 + * - [1] The first segment + * - [2] The first and second segment + * - ... + * - [divisions] All segments * * @method Phaser.Curves.Curve#getLengths * @since 3.0.0 * - * @param {integer} [divisions] - [description] + * @param {integer} [divisions] - The number of divisions or segments. * - * @return {number[]} [description] + * @return {number[]} An array of cumulative lengths. */ getLengths: function (divisions) { @@ -268,17 +276,17 @@ var Curve = new Class({ // - u [0 .. 1] /** - * [description] + * Get a point at a relative position on the curve, by arc length. * * @method Phaser.Curves.Curve#getPointAt * @since 3.0.0 * * @generic {Phaser.Math.Vector2} O - [out,$return] * - * @param {number} u - [description] - * @param {Phaser.Math.Vector2} [out] - [description] + * @param {number} u - The relative position, [0..1]. + * @param {Phaser.Math.Vector2} [out] - A point to store the result in. * - * @return {Phaser.Math.Vector2} [description] + * @return {Phaser.Math.Vector2} The point. */ getPointAt: function (u, out) { @@ -290,15 +298,25 @@ var Curve = new Class({ // Get sequence of points using getPoint( t ) /** - * [description] + * Get a sequence of evenly spaced points from the curve. + * + * You can pass `divisions`, `stepRate`, or neither. + * + * The number of divisions will be + * + * 1. `divisions`, if `divisions` > 0; or + * 2. `this.getLength / stepRate`, if `stepRate` > 0; or + * 3. `this.defaultDivisions` + * + * `1 + divisions` points will be returned. * * @method Phaser.Curves.Curve#getPoints * @since 3.0.0 * * @generic {Phaser.Math.Vector2[]} O - [out,$return] * - * @param {integer} divisions - The number of evenly spaced points from the curve to return. If falsy, step param will be used to calculate the number of points. - * @param {number} step - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive. + * @param {integer} [divisions] - The number of divisions to make. + * @param {number} [stepRate] - The curve distance between points, implying `divisions`. * @param {(array|Phaser.Math.Vector2[])} [out] - An optional array to store the points in. * * @return {(array|Phaser.Math.Vector2[])} An array of Points from the curve. @@ -329,16 +347,16 @@ var Curve = new Class({ }, /** - * [description] + * Get a random point from the curve. * * @method Phaser.Curves.Curve#getRandomPoint * @since 3.0.0 * * @generic {Phaser.Math.Vector2} O - [out,$return] * - * @param {Phaser.Math.Vector2} [out] - [description] + * @param {Phaser.Math.Vector2} [out] - A point object to store the result in. * - * @return {Phaser.Math.Vector2} [description] + * @return {Phaser.Math.Vector2} The point. */ getRandomPoint: function (out) { @@ -350,16 +368,18 @@ var Curve = new Class({ // Get sequence of points using getPointAt( u ) /** - * [description] + * Get a sequence of equally spaced points (by arc distance) from the curve. + * + * `1 + divisions` points will be returned. * * @method Phaser.Curves.Curve#getSpacedPoints * @since 3.0.0 * - * @param {integer} [divisions] - The number of evenly spaced points from the curve to return. If falsy, step param will be used to calculate the number of points. - * @param {number} [step] - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive. + * @param {integer} [divisions=this.defaultDivisions] - The number of divisions to make. + * @param {number} [stepRate] - Step between points. Used to calculate the number of points to return when divisions is falsy. Ignored if divisions is positive. * @param {(array|Phaser.Math.Vector2[])} [out] - An optional array to store the points in. * - * @return {Phaser.Math.Vector2[]} [description] + * @return {Phaser.Math.Vector2[]} An array of points. */ getSpacedPoints: function (divisions, stepRate, out) { @@ -389,16 +409,16 @@ var Curve = new Class({ }, /** - * [description] + * Get a point at the start of the curve. * * @method Phaser.Curves.Curve#getStartPoint * @since 3.0.0 * * @generic {Phaser.Math.Vector2} O - [out,$return] * - * @param {Phaser.Math.Vector2} [out] - [description] + * @param {Phaser.Math.Vector2} [out] - A point to store the result in. * - * @return {Phaser.Math.Vector2} [description] + * @return {Phaser.Math.Vector2} The point. */ getStartPoint: function (out) { @@ -408,7 +428,7 @@ var Curve = new Class({ }, /** - * Returns a unit vector tangent at t + * Get a unit vector tangent at a relative position on the curve. * In case any sub curve does not implement its tangent derivation, * 2 points a small delta apart will be used to find its gradient * which seems to give a reasonable approximation @@ -418,8 +438,8 @@ var Curve = new Class({ * * @generic {Phaser.Math.Vector2} O - [out,$return] * - * @param {number} t - [description] - * @param {Phaser.Math.Vector2} [out] - [description] + * @param {number} t - The relative position on the curve, [0..1]. + * @param {Phaser.Math.Vector2} [out] - A vector to store the result in. * * @return {Phaser.Math.Vector2} Vector approximating the tangent line at the point t (delta +/- 0.0001) */ @@ -450,17 +470,17 @@ var Curve = new Class({ }, /** - * [description] + * Get a unit vector tangent at a relative position on the curve, by arc length. * * @method Phaser.Curves.Curve#getTangentAt * @since 3.0.0 * * @generic {Phaser.Math.Vector2} O - [out,$return] * - * @param {number} u - [description] - * @param {Phaser.Math.Vector2} [out] - [description] + * @param {number} u - The relative position on the curve, [0..1]. + * @param {Phaser.Math.Vector2} [out] - A vector to store the result in. * - * @return {Phaser.Math.Vector2} [description] + * @return {Phaser.Math.Vector2} The tangent vector. */ getTangentAt: function (u, out) { @@ -575,10 +595,12 @@ var Curve = new Class({ }, /** - * [description] + * Calculate and cache the arc lengths. * * @method Phaser.Curves.Curve#updateArcLengths * @since 3.0.0 + * + * @see Phaser.Curves.Curve#getLengths() */ updateArcLengths: function () { diff --git a/src/curves/SplineCurve.js b/src/curves/SplineCurve.js index d1db43c57..8c813b7f8 100644 --- a/src/curves/SplineCurve.js +++ b/src/curves/SplineCurve.js @@ -13,7 +13,7 @@ var Vector2 = require('../math/Vector2'); /** * @classdesc - * [description] + * Create a smooth 2d spline curve from a series of points. * * @class Spline * @extends Phaser.Curves.Curve @@ -21,7 +21,7 @@ var Vector2 = require('../math/Vector2'); * @constructor * @since 3.0.0 * - * @param {Phaser.Math.Vector2[]} [points] - [description] + * @param {(Phaser.Math.Vector2[]|number[]|number[][])} [points] - The points that configure the curve. */ var SplineCurve = new Class({ @@ -36,7 +36,7 @@ var SplineCurve = new Class({ Curve.call(this, 'SplineCurve'); /** - * [description] + * The Vector2 points that configure the curve. * * @name Phaser.Curves.Spline#points * @type {Phaser.Math.Vector2[]} @@ -49,12 +49,12 @@ var SplineCurve = new Class({ }, /** - * [description] + * Add a list of points to the current list of Vector2 points of the curve. * * @method Phaser.Curves.Spline#addPoints * @since 3.0.0 * - * @param {(Phaser.Math.Vector2[]|number[]|number[][])} points - [description] + * @param {(Phaser.Math.Vector2[]|number[]|number[][])} points - The points that configure the curve. * * @return {Phaser.Curves.Spline} This curve object. */ @@ -89,15 +89,15 @@ var SplineCurve = new Class({ }, /** - * [description] + * Add a point to the current list of Vector2 points of the curve. * * @method Phaser.Curves.Spline#addPoint * @since 3.0.0 * - * @param {number} x - [description] - * @param {number} y - [description] + * @param {number} x - The x coordinate of this curve + * @param {number} y - The y coordinate of this curve * - * @return {Phaser.Math.Vector2} [description] + * @return {Phaser.Math.Vector2} The new Vector2 added to the curve */ addPoint: function (x, y) { @@ -176,7 +176,7 @@ var SplineCurve = new Class({ }, /** - * [description] + * Exports a JSON object containing this curve data. * * @method Phaser.Curves.Spline#toJSON * @since 3.0.0 @@ -202,14 +202,14 @@ var SplineCurve = new Class({ }); /** - * [description] + * Imports a JSON object containing this curve data. * * @function Phaser.Curves.Spline.fromJSON * @since 3.0.0 * * @param {Phaser.Types.Curves.JSONCurve} data - The JSON object containing this curve data. * - * @return {Phaser.Curves.Spline} [description] + * @return {Phaser.Curves.Spline} The spline curve created. */ SplineCurve.fromJSON = function (data) { diff --git a/src/curves/path/Path.js b/src/curves/path/Path.js index eec47c28c..6cdc5e668 100644 --- a/src/curves/path/Path.js +++ b/src/curves/path/Path.js @@ -569,14 +569,12 @@ var Path = new Class({ }, /** - * Returns the defined starting point of the Path. - * - * This is not necessarily equal to the starting point of the first Curve if it differs from {@link startPoint}. + * Get a sequence of points on the path. * * @method Phaser.Curves.Path#getPoints * @since 3.0.0 * - * @param {integer} [divisions=12] - The number of points to divide the path in to. + * @param {integer} [divisions=12] - The number of divisions per resolution per curve. * * @return {Phaser.Math.Vector2[]} An array of Vector2 objects that containing the points along the Path. */ @@ -626,7 +624,7 @@ var Path = new Class({ /** * Returns a randomly chosen point anywhere on the path. This follows the same rules as `getPoint` in that it may return a point on any Curve inside this path. - * + * * When calling this method multiple times, the points are not guaranteed to be equally spaced spatially. * * @method Phaser.Curves.Path#getRandomPoint @@ -647,7 +645,7 @@ var Path = new Class({ /** * Divides this Path into a set of equally spaced points, - * + * * The resulting points are equally spaced with respect to the points' position on the path, but not necessarily equally spaced spatially. * * @method Phaser.Curves.Path#getSpacedPoints @@ -741,7 +739,7 @@ var Path = new Class({ /** * Creates a "gap" in this path from the path's current end point to the given coordinates. - * + * * After calling this function, this Path's end point will be equal to the given coordinates * * @method Phaser.Curves.Path#moveTo diff --git a/src/scene/ScenePlugin.js b/src/scene/ScenePlugin.js index 39678408e..61a30a5d0 100644 --- a/src/scene/ScenePlugin.js +++ b/src/scene/ScenePlugin.js @@ -188,6 +188,8 @@ var ScenePlugin = new Class({ /** * Shutdown this Scene and run the given one. * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#start * @since 3.0.0 * @@ -209,6 +211,8 @@ var ScenePlugin = new Class({ /** * Restarts this Scene. * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#restart * @since 3.4.0 * @@ -444,6 +448,8 @@ var ScenePlugin = new Class({ /** * Launch the given Scene and run it in parallel with this one. * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#launch * @since 3.0.0 * @@ -465,6 +471,8 @@ var ScenePlugin = new Class({ /** * Runs the given Scene, but does not change the state of this Scene. * + * This will happen at the next Scene Manager update, not immediately. + * * If the given Scene is paused, it will resume it. If sleeping, it will wake it. * If not running at all, it will be started. * @@ -492,6 +500,8 @@ var ScenePlugin = new Class({ /** * Pause the Scene - this stops the update step from happening but it still renders. * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#pause * @since 3.0.0 * @@ -512,6 +522,8 @@ var ScenePlugin = new Class({ /** * Resume the Scene - starts the update loop again. * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#resume * @since 3.0.0 * @@ -532,6 +544,8 @@ var ScenePlugin = new Class({ /** * Makes the Scene sleep (no update, no render) but doesn't shutdown. * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#sleep * @since 3.0.0 * @@ -552,6 +566,8 @@ var ScenePlugin = new Class({ /** * Makes the Scene wake-up (starts update and render) * + * This will happen at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#wake * @since 3.0.0 * @@ -571,11 +587,8 @@ var ScenePlugin = new Class({ /** * Makes this Scene sleep then starts the Scene given. - * - * No checks are made to see if an instance of the given Scene is already running. - * Because Scenes in Phaser are non-exclusive, you are allowed to run multiple - * instances of them _at the same time_. This means, calling this function - * may launch another instance of the requested Scene if it's already running. + * + * This will happen at the next Scene Manager update, not immediately. * * @method Phaser.Scenes.ScenePlugin#switch * @since 3.0.0 @@ -597,6 +610,8 @@ var ScenePlugin = new Class({ /** * Shutdown the Scene, clearing display list, timers, etc. * + * This happens at the next Scene Manager update, not immediately. + * * @method Phaser.Scenes.ScenePlugin#stop * @since 3.0.0 * @@ -814,7 +829,7 @@ var ScenePlugin = new Class({ * The Scene is removed from the local scenes array, it's key is cleared from the keys * cache and Scene.Systems.destroy is then called on it. * - * If the SceneManager is processing the Scenes when this method is called it wil + * If the SceneManager is processing the Scenes when this method is called it will * queue the operation for the next update sequence. * * @method Phaser.Scenes.ScenePlugin#remove diff --git a/src/sound/BaseSoundManager.js b/src/sound/BaseSoundManager.js index 29c84c9d6..e582833ec 100644 --- a/src/sound/BaseSoundManager.js +++ b/src/sound/BaseSoundManager.js @@ -227,8 +227,9 @@ var BaseSoundManager = new Class({ }, /** - * Enables playing sound on the fly without the need to keep a reference to it. - * Sound will auto destroy once its playback ends. + * Adds a new sound to the sound manager and plays it. + * The sound will be automatically removed (destroyed) once playback ends. + * This lets you play a new sound on the fly without the need to keep a reference to it. * * @method Phaser.Sound.BaseSoundManager#play * @listens Phaser.Sound.Events#COMPLETE