Merge pull request #6 from photonstorm/master

fuse with master + cleanup

CHANGELOG.md

@@ -54,7 +54,7 @@ The following features are now deprecated and will be removed in a future versio
 
 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:
 
-@JasonHK @supertommy
+@JasonHK @supertommy @majalon @samme
 
 ## Version 3.22 - Kohaku - January 15th 2020
 

README.md

@@ -29,7 +29,7 @@ Grab the source and join the fun!
 
 > 15th January 2020
 
-We're excited to announce the release of Phaser 3.22, the first of many in the year 2020. The main focus of 3.22 is all the work we've done on Matter Physics integration. Matter has been supported in Phaser since the first release, yet there were lots of things we wanted to do with it to make development life easier. 3.22 brings all of these to the front, including powerful new visual debugging options such as rendering contacts, velocity, the broadphase grid, sensors, joints and more. Matter also now has 100% JSDoc and TypeScripy coverage and I spent a long time rebuilding the TypeScript defs by hand, in order to make them as accurate as possible.
+We're excited to announce the release of Phaser 3.22, the first of many in the year 2020. The main focus of 3.22 is all the work we've done on Matter Physics integration. Matter has been supported in Phaser since the first release, yet there were lots of things we wanted to do with it to make development life easier. 3.22 brings all of these to the front, including powerful new visual debugging options such as rendering contacts, velocity, the broadphase grid, sensors, joints and more. Matter also now has 100% JSDoc and TypeScript coverage and I spent a long time rebuilding the TypeScript defs by hand, in order to make them as accurate as possible.
 
 As well as docs and defs there are stacks of handy new methods, including intersection tests such as `intersectPoint`, `intersectRay`, `overlap` and more. New Body level collision callbacks allow you to filter collided pairs a lot more quickly now, combined with new collision events and data type defs to give you all the information you need when resolving. There are now functions to create bodies from SVG data, JSON data or Physics Editor data directly, new Body alignment features and of course bug fixes.
 

src/gameobjects/components/Transform.js

@@ -225,8 +225,8 @@ var Transform = {
     /**
      * The angle of this Game Object in radians.
      *
-     * Phaser uses a right-hand clockwise rotation system, where 0 is right, 90 is down, 180/-180 is left
-     * and -90 is up.
+     * Phaser uses a right-hand clockwise rotation system, where 0 is right, PI/2 is down, +-PI is left
+     * and -PI/2 is up.
      *
      * If you prefer to work in degrees, see the `angle` property instead.
      *

src/gameobjects/text/static/Text.js

@@ -27,20 +27,17 @@ var TextStyle = require('../TextStyle');
  * Because it uses the Canvas API you can take advantage of all the features this offers, such as
  * applying gradient fills to the text, or strokes, shadows and more. You can also use custom fonts
  * loaded externally, such as Google or TypeKit Web fonts.
- * 
- * **Important:** If the font you wish to use has a space or digit in its name, such as
- * 'Press Start 2P' or 'Roboto Condensed', then you _must_ put the font name in quotes, either
- * when creating the Text object, or when setting the font via `setFont` or `setFontFamily`. I.e.:
- * 
+ *
+ * **Important:** The font name must be quoted if it contains certain combinations of digits or
+ * special characters, either when creating the Text object, or when setting the font via `setFont`
+ * or `setFontFamily`, e.g.:
+ *
  * ```javascript
- * this.add.text(0, 0, 'Hello World', { fontFamily: '"Roboto Condensed"' });
+ * this.add.text(0, 0, 'Hello World', { fontFamily: 'Georgia, "Goudy Bookletter 1911", Times, serif' });
  * ```
- * 
- * Equally, if you wish to provide a list of fallback fonts, then you should ensure they are all
- * quoted properly, too:
- * 
+ *
  * ```javascript
- * this.add.text(0, 0, 'Hello World', { fontFamily: 'Verdana, "Times New Roman", Tahoma, serif' });
+ * this.add.text(0, 0, 'Hello World', { font: '"Press Start 2P"' });
  * ```
  *
  * You can only display fonts that are currently loaded and available to the browser: therefore fonts must
@@ -82,6 +79,8 @@ var TextStyle = require('../TextStyle');
  * @param {number} y - The vertical position of this Game Object in the world.
  * @param {(string|string[])} text - The text this Text object will display.
  * @param {Phaser.Types.GameObjects.Text.TextStyle} style - The text style configuration object.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#Valid_family_names
  */
 var Text = new Class({
 
@@ -643,19 +642,19 @@ var Text = new Class({
      *
      * If an object is given, the `fontFamily`, `fontSize` and `fontStyle`
      * properties of that object are set.
-     * 
-     * **Important:** If the font you wish to use has a space or digit in its name, such as
-     * 'Press Start 2P' or 'Roboto Condensed', then you _must_ put the font name in quotes:
-     * 
+     *
+     * **Important:** The font name must be quoted if it contains certain combinations of digits or
+     * special characters:
+     *
      * ```javascript
-     * Text.setFont('"Roboto Condensed"');
+     * Text.setFont('"Press Start 2P"');
      * ```
-     * 
+     *
      * Equally, if you wish to provide a list of fallback fonts, then you should ensure they are all
      * quoted properly, too:
-     * 
+     *
      * ```javascript
-     * Text.setFont('Verdana, "Times New Roman", Tahoma, serif');
+     * Text.setFont('Georgia, "Goudy Bookletter 1911", Times, serif');
      * ```
      *
      * @method Phaser.GameObjects.Text#setFont
@@ -664,6 +663,8 @@ var Text = new Class({
      * @param {string} font - The font family or font settings to set.
      *
      * @return {this} This Text object.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#Valid_family_names
      */
     setFont: function (font)
     {
@@ -672,19 +673,19 @@ var Text = new Class({
 
     /**
      * Set the font family.
-     * 
-     * **Important:** If the font you wish to use has a space or digit in its name, such as
-     * 'Press Start 2P' or 'Roboto Condensed', then you _must_ put the font name in quotes:
-     * 
+     *
+     * **Important:** The font name must be quoted if it contains certain combinations of digits or
+     * special characters:
+     *
      * ```javascript
-     * Text.setFont('"Roboto Condensed"');
+     * Text.setFont('"Press Start 2P"');
      * ```
      * 
      * Equally, if you wish to provide a list of fallback fonts, then you should ensure they are all
      * quoted properly, too:
      * 
      * ```javascript
-     * Text.setFont('Verdana, "Times New Roman", Tahoma, serif');
+     * Text.setFont('Georgia, "Goudy Bookletter 1911", Times, serif');
      * ```
      *
      * @method Phaser.GameObjects.Text#setFontFamily
@@ -693,6 +694,8 @@ var Text = new Class({
      * @param {string} family - The font family.
      *
      * @return {this} This Text object.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#Valid_family_names
      */
     setFontFamily: function (family)
     {

src/gameobjects/video/VideoFactory.js

@@ -8,19 +8,18 @@ var Video = require('./Video');
 var GameObjectFactory = require('../GameObjectFactory');
 
 /**
- * Creates a new Image Game Object and adds it to the Scene.
+ * Creates a new Video Game Object and adds it to the Scene.
  *
- * Note: This method will only be available if the Image Game Object has been built into Phaser.
+ * Note: This method will only be available if the Video Game Object has been built into Phaser.
  *
  * @method Phaser.GameObjects.GameObjectFactory#video
  * @since 3.20.0
  *
  * @param {number} x - The horizontal position of this Game Object in the world.
  * @param {number} y - The vertical position of this Game Object in the world.
- * @param {string} texture - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager.
- * @param {(string|integer)} [frame] - An optional frame from the Texture this Game Object is rendering with.
+ * @param {string} [key] - Optional key of the Video this Game Object will play, as stored in the Video Cache.
  *
- * @return {Phaser.GameObjects.Image} The Game Object that was created.
+ * @return {Phaser.GameObjects.Video} The Game Object that was created.
  */
 GameObjectFactory.register('video', function (x, y, key)
 {

src/math/Vector2.js

@@ -423,7 +423,7 @@ var Vector2 = new Class({
     },
 
     /**
-     * Right-hand normalize (make unit length) this Vector.
+     * Rotate this Vector to its perpendicular, in the positive direction.
      *
      * @method Phaser.Math.Vector2#normalizeRightHand
      * @since 3.0.0
@@ -560,7 +560,7 @@ var Vector2 = new Class({
 
 /**
  * A static zero Vector2 for use by reference.
- * 
+ *
  * This constant is meant for comparison operations and should not be modified directly.
  *
  * @constant
@@ -572,7 +572,7 @@ Vector2.ZERO = new Vector2();
 
 /**
  * A static right Vector2 for use by reference.
- * 
+ *
  * This constant is meant for comparison operations and should not be modified directly.
  *
  * @constant
@@ -584,7 +584,7 @@ Vector2.RIGHT = new Vector2(1, 0);
 
 /**
  * A static left Vector2 for use by reference.
- * 
+ *
  * This constant is meant for comparison operations and should not be modified directly.
  *
  * @constant
@@ -596,7 +596,7 @@ Vector2.LEFT = new Vector2(-1, 0);
 
 /**
  * A static up Vector2 for use by reference.
- * 
+ *
  * This constant is meant for comparison operations and should not be modified directly.
  *
  * @constant
@@ -608,7 +608,7 @@ Vector2.UP = new Vector2(0, -1);
 
 /**
  * A static down Vector2 for use by reference.
- * 
+ *
  * This constant is meant for comparison operations and should not be modified directly.
  *
  * @constant
@@ -620,7 +620,7 @@ Vector2.DOWN = new Vector2(0, 1);
 
 /**
  * A static one Vector2 for use by reference.
- * 
+ *
  * This constant is meant for comparison operations and should not be modified directly.
  *
  * @constant

src/math/easing/linear/Linear.js

@@ -7,7 +7,7 @@
 /**
  * Linear easing (no variation).
  *
- * @function Phaser.Math.Easing.Linear.Linear
+ * @function Phaser.Math.Easing.Linear
  * @since 3.0.0
  *
  * @param {number} v - The value to be tweened.

src/math/easing/stepped/Stepped.js

@@ -7,7 +7,7 @@
 /**
  * Stepped easing.
  *
- * @function Phaser.Math.Easing.Stepped.Stepped
+ * @function Phaser.Math.Easing.Stepped
  * @since 3.0.0
  *
  * @param {number} v - The value to be tweened.

src/physics/arcade/PhysicsGroup.js

@@ -15,7 +15,7 @@ var IsPlainObject = require('../../utils/object/IsPlainObject');
  * @classdesc
  * An Arcade Physics Group object.
  *
- * All Game Objects created by this Group will automatically be given dynamic Arcade Physics bodies.
+ * All Game Objects created by or added to this Group will automatically be given dynamic Arcade Physics bodies, if they have no body.
  *
  * Its static counterpart is {@link Phaser.Physics.Arcade.StaticGroup}.
  *

src/physics/arcade/StaticPhysicsGroup.js

@@ -15,7 +15,7 @@ var IsPlainObject = require('../../utils/object/IsPlainObject');
  * @classdesc
  * An Arcade Physics Static Group object.
  *
- * All Game Objects created by this Group will automatically be given static Arcade Physics bodies.
+ * All Game Objects created by or added to this Group will automatically be given static Arcade Physics bodies, if they have no body.
  *
  * Its dynamic counterpart is {@link Phaser.Physics.Arcade.Group}.
  *

src/sound/BaseSoundManager.js

@@ -14,12 +14,7 @@ var NOOP = require('../utils/NOOP');
 
 /**
  * @classdesc
- * The sound manager is responsible for playing back audio via Web Audio API or HTML Audio tag as fallback.
- * The audio file type and the encoding of those files are extremely important.
- *
- * Not all browsers can play all audio formats.
- *
- * There is a good guide to what's supported [here](https://developer.mozilla.org/en-US/Apps/Fundamentals/Audio_and_video_delivery/Cross-browser_audio_basics#Audio_Codec_Support).
+ * Base class for other Sound Manager classes.
  *
  * @class BaseSoundManager
  * @extends Phaser.Events.EventEmitter
@@ -28,6 +23,10 @@ var NOOP = require('../utils/NOOP');
  * @since 3.0.0
  *
  * @param {Phaser.Game} game - Reference to the current game instance.
+ *
+ * @see Phaser.Sound.HTML5AudioSoundManager
+ * @see Phaser.Sound.NoAudioSoundManager
+ * @see Phaser.Sound.WebAudioSoundManager
  */
 var BaseSoundManager = new Class({
 
@@ -266,8 +265,9 @@ var BaseSoundManager = new Class({
     },
 
     /**
-     * Enables playing audio sprite sound on the fly without the need to keep a reference to it.
-     * Sound will auto destroy once its playback ends.
+     * Adds a new audio sprite sound to the sound manager and plays it.
+     * The sprite 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#playAudioSprite
      * @listens Phaser.Sound.Events#COMPLETE

src/sound/html5/HTML5AudioSoundManager.js

@@ -12,16 +12,20 @@ var HTML5AudioSound = require('./HTML5AudioSound');
 
 /**
  * HTML5 Audio implementation of the Sound Manager.
- * 
- * Note: To play multiple instances of the same HTML5 Audio sound, you need to provide an `instances` value when
+ *
+ * To play multiple instances of the same HTML5 Audio sound, you need to provide an `instances` value when
  * loading the sound with the Loader:
- * 
+ *
  * ```javascript
  * this.load.audio('explosion', 'explosion.mp3', {
  *     instances: 2
  * });
  * ```
  *
+ * Not all browsers can play all audio formats.
+ *
+ * There is a good guide to what's supported: [Cross-browser audio basics: Audio codec support](https://developer.mozilla.org/en-US/Apps/Fundamentals/Audio_and_video_delivery/Cross-browser_audio_basics#Audio_Codec_Support).
+ *
  * @class HTML5AudioSoundManager
  * @extends Phaser.Sound.BaseSoundManager
  * @memberof Phaser.Sound

src/sound/noaudio/NoAudioSoundManager.js

@@ -13,10 +13,10 @@ var NOOP = require('../../utils/NOOP');
 
 /**
  * @classdesc
- * No audio implementation of the sound manager. It is used if audio has been
+ * No-audio implementation of the Sound Manager. It is used if audio has been
  * disabled in the game config or the device doesn't support any audio.
  *
- * It represents a graceful degradation of sound manager logic that provides
+ * It represents a graceful degradation of Sound Manager logic that provides
  * minimal functionality and prevents Phaser projects that use audio from
  * breaking on devices that don't support any audio playback technologies.
  *

src/sound/webaudio/WebAudioSoundManager.js

@@ -13,7 +13,11 @@ var WebAudioSound = require('./WebAudioSound');
 
 /**
  * @classdesc
- * Web Audio API implementation of the sound manager.
+ * Web Audio API implementation of the Sound Manager.
+ *
+ * Not all browsers can play all audio formats.
+ *
+ * There is a good guide to what's supported: [Cross-browser audio basics: Audio codec support](https://developer.mozilla.org/en-US/Apps/Fundamentals/Audio_and_video_delivery/Cross-browser_audio_basics#Audio_Codec_Support).
  *
  * @class WebAudioSoundManager
  * @extends Phaser.Sound.BaseSoundManager
@@ -117,7 +121,7 @@ var WebAudioSoundManager = new Class({
     /**
      * This method takes a new AudioContext reference and then sets
      * this Sound Manager to use that context for all playback.
-     * 
+     *
      * As part of this call it also disconnects the master mute and volume
      * nodes and then re-creates them on the new given context.
      *
@@ -180,16 +184,16 @@ var WebAudioSoundManager = new Class({
 
     /**
      * Decode audio data into a format ready for playback via Web Audio.
-     * 
+     *
      * The audio data can be a base64 encoded string, an audio media-type data uri, or an ArrayBuffer instance.
-     * 
+     *
      * The `audioKey` is the key that will be used to save the decoded audio to the audio cache.
-     * 
+     *
      * Instead of passing a single entry you can instead pass an array of `Phaser.Types.Sound.DecodeAudioConfig`
      * objects as the first and only argument.
-     * 
+     *
      * Decoding is an async process, so be sure to listen for the events to know when decoding has completed.
-     * 
+     *
      * Once the audio has decoded it can be added to the Sound Manager or played via its key.
      *
      * @method Phaser.Sound.WebAudioSoundManager#decodeAudio
@@ -231,7 +235,7 @@ var WebAudioSoundManager = new Class({
             var success = function (key, audioBuffer)
             {
                 cache.add(key, audioBuffer);
-    
+
                 this.emit(Events.DECODED, key);
 
                 remaining--;
@@ -241,7 +245,7 @@ var WebAudioSoundManager = new Class({
                     this.emit(Events.DECODED_ALL);
                 }
             }.bind(this, key);
-    
+
             var failure = function (key, error)
             {
                 //  eslint-disable-next-line no-console
@@ -283,7 +287,7 @@ var WebAudioSoundManager = new Class({
                     body.removeEventListener('touchend', unlockHandler);
                     body.removeEventListener('click', unlockHandler);
                     body.removeEventListener('keydown', unlockHandler);
-    
+
                     _this.unlocked = true;
                 }, function ()
                 {