Added Texture Manager Events and moved 'ready' responsibility to it

Author: photonstorm

CHANGELOG.md

@@ -297,6 +297,7 @@ one set of bindings ever created, which makes things a lot cleaner.
 * The keyed Data Manager change data event string has changed from `changedata_` to `changedata-` to keep it consistent with other keyed events.
 * The Keyboard Plugin `keydown` dynamic event string has changed from `keydown_` to `keydown-` to keep it consistent with other keyed events. Note the change from `_` to `-`.
 * The Keyboard Plugin `keyup` dynamic event string has changed from `keyup_` to `keyup-` to keep it consistent with other keyed events. Note the change from `_` to `-`.
+* The `texturesready` event emitted by the Texture Manager has changed to be just `ready`.
 
 ### Examples and TypeScript
 

src/core/Game.js

@@ -23,6 +23,7 @@ var PluginManager = require('../plugins/PluginManager');
 var ScaleManager = require('../dom/ScaleManager');
 var SceneManager = require('../scene/SceneManager');
 var SoundManagerCreator = require('../sound/SoundManagerCreator');
+var TextureEvents = require('../textures/events');
 var TextureManager = require('../textures/TextureManager');
 var TimeStep = require('./TimeStep');
 var VisibilityHandler = require('./VisibilityHandler');
@@ -346,7 +347,7 @@ var Game = new Class({
      * @method Phaser.Game#boot
      * @protected
      * @fires Phaser.Core.Events#BOOT
-     * @fires Phaser.Core.Events#TEXTURES_READY
+     * @listens Phaser.Textures.Events#READY
      * @since 3.0.0
      */
     boot: function ()
@@ -378,7 +379,7 @@ var Game = new Class({
 
         //  The Texture Manager has to wait on a couple of non-blocking events before it's fully ready.
         //  So it will emit this internal event when done:
-        this.events.once(Events.TEXTURES_READY, this.texturesReady, this);
+        this.events.once(TextureEvents.READY, this.texturesReady, this);
     },
 
     /**

src/core/events/index.js

@@ -23,7 +23,6 @@ module.exports = {
     READY: require('./READY_EVENT'),
     RESUME: require('./RESUME_EVENT'),
     STEP: require('./STEP_EVENT'),
-    TEXTURES_READY: require('./TEXTURES_READY_EVENT'),
     VISIBLE: require('./VISIBLE_EVENT')
 
 };

src/textures/TextureManager.js

@@ -10,6 +10,8 @@ var Class = require('../utils/Class');
 var Color = require('../display/color/Color');
 var CONST = require('../const');
 var EventEmitter = require('eventemitter3');
+var Events = require('./events');
+var GameEvents = require('../core/events');
 var GenerateTexture = require('../create/GenerateTexture');
 var GetValue = require('../utils/object/GetValue');
 var Parser = require('./parsers');
@@ -109,7 +111,7 @@ var TextureManager = new Class({
          */
         this._pending = 0;
 
-        game.events.once('boot', this.boot, this);
+        game.events.once(GameEvents.BOOT, this.boot, this);
     },
 
     /**
@@ -129,7 +131,7 @@ var TextureManager = new Class({
         this.addBase64('__DEFAULT', this.game.config.defaultImage);
         this.addBase64('__MISSING', this.game.config.missingImage);
 
-        this.game.events.once('destroy', this.destroy, this);
+        this.game.events.once(GameEvents.DESTROY, this.destroy, this);
     },
 
     /**
@@ -148,7 +150,7 @@ var TextureManager = new Class({
             this.off('onload');
             this.off('onerror');
 
-            this.game.events.emit('texturesready');
+            this.game.events.emit(GameEvents.TEXTURES_READY);
         }
     },
 
@@ -186,6 +188,7 @@ var TextureManager = new Class({
      * step when clearing down to avoid this.
      *
      * @method Phaser.Textures.TextureManager#remove
+     * @fires Phaser.Textures.Events#REMOVE
      * @since 3.7.0
      *
      * @param {(string|Phaser.Textures.Texture)} key - The key of the Texture to remove, or a reference to it.
@@ -214,7 +217,7 @@ var TextureManager = new Class({
 
             key.destroy();
 
-            this.emit('removetexture', key.key);
+            this.emit(Events.REMOVE, key.key);
         }
 
         return this;
@@ -224,6 +227,9 @@ var TextureManager = new Class({
      * Adds a new Texture to the Texture Manager created from the given Base64 encoded data.
      *
      * @method Phaser.Textures.TextureManager#addBase64
+     * @fires Phaser.Textures.Events#ADD
+     * @fires Phaser.Textures.Events#ERROR
+     * @fires Phaser.Textures.Events#LOAD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -241,7 +247,7 @@ var TextureManager = new Class({
 
             image.onerror = function ()
             {
-                _this.emit('onerror', key);
+                _this.emit(Events.ERROR, key);
             };
 
             image.onload = function ()
@@ -250,9 +256,9 @@ var TextureManager = new Class({
 
                 Parser.Image(texture, 0);
 
-                _this.emit('addtexture', key, texture);
+                _this.emit(Events.ADD, key, texture);
 
-                _this.emit('onload', key, texture);
+                _this.emit(Events.LOAD, key, texture);
             };
 
             image.src = data;
@@ -316,6 +322,7 @@ var TextureManager = new Class({
      * Adds a new Texture to the Texture Manager created from the given Image element.
      *
      * @method Phaser.Textures.TextureManager#addImage
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -339,7 +346,7 @@ var TextureManager = new Class({
                 texture.setDataSource(dataSource);
             }
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -350,6 +357,7 @@ var TextureManager = new Class({
      * This allows you to then use the Render Texture as a normal texture for texture based Game Objects like Sprites.
      *
      * @method Phaser.Textures.TextureManager#addRenderTexture
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.12.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -367,7 +375,7 @@ var TextureManager = new Class({
 
             texture.add('__BASE', 0, 0, 0, renderTexture.width, renderTexture.height);
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -439,6 +447,7 @@ var TextureManager = new Class({
      * and adds it to this Texture Manager, unless `skipCache` is true.
      *
      * @method Phaser.Textures.TextureManager#addCanvas
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -463,7 +472,7 @@ var TextureManager = new Class({
 
             this.list[key] = texture;
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -502,6 +511,7 @@ var TextureManager = new Class({
      * This is known as a JSON Array in software such as Texture Packer.
      *
      * @method Phaser.Textures.TextureManager#addAtlasJSONArray
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -542,7 +552,7 @@ var TextureManager = new Class({
                 texture.setDataSource(dataSource);
             }
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -554,6 +564,7 @@ var TextureManager = new Class({
      * This is known as a JSON Hash in software such as Texture Packer.
      *
      * @method Phaser.Textures.TextureManager#addAtlasJSONHash
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -588,7 +599,7 @@ var TextureManager = new Class({
                 texture.setDataSource(dataSource);
             }
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -599,6 +610,7 @@ var TextureManager = new Class({
      * in the XML format.
      *
      * @method Phaser.Textures.TextureManager#addAtlasXML
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.7.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -623,7 +635,7 @@ var TextureManager = new Class({
                 texture.setDataSource(dataSource);
             }
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -634,6 +646,7 @@ var TextureManager = new Class({
      * The data must be in the form of a Unity YAML file.
      *
      * @method Phaser.Textures.TextureManager#addUnityAtlas
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -658,7 +671,7 @@ var TextureManager = new Class({
                 texture.setDataSource(dataSource);
             }
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -682,6 +695,7 @@ var TextureManager = new Class({
      * same size and cannot be trimmed or rotated.
      *
      * @method Phaser.Textures.TextureManager#addSpriteSheet
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -703,7 +717,7 @@ var TextureManager = new Class({
 
             Parser.SpriteSheet(texture, 0, 0, 0, width, height, config);
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
         }
 
         return texture;
@@ -729,6 +743,7 @@ var TextureManager = new Class({
      * same size and cannot be trimmed or rotated.
      *
      * @method Phaser.Textures.TextureManager#addSpriteSheetFromAtlas
+     * @fires Phaser.Textures.Events#ADD
      * @since 3.0.0
      *
      * @param {string} key - The unique string-based key of the Texture.
@@ -768,7 +783,7 @@ var TextureManager = new Class({
                 Parser.SpriteSheet(texture, 0, sheet.cutX, sheet.cutY, sheet.cutWidth, sheet.cutHeight, config);
             }
 
-            this.emit('addtexture', key, texture);
+            this.emit(Events.ADD, key, texture);
 
             return texture;
         }

src/textures/events/ADD_EVENT.js

@@ -0,0 +1,19 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Texture Add Event.
+ * 
+ * This event is dispatched by the Texture Manager when a texture is added to it.
+ * 
+ * Listen to this event from within a Scene using: `this.textures.on('addtexture', listener)`.
+ *
+ * @event Phaser.Textures.Events#ADD
+ * 
+ * @param {string} key - The key of the Texture that was added to the Texture Manager.
+ * @param {Phaser.Textures.Texture} texture - A reference to the Texture that was added to the Texture Manager.
+ */
+module.exports = 'addtexture';

src/textures/events/ERROR_EVENT.js

@@ -0,0 +1,19 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Texture Load Error Event.
+ * 
+ * This event is dispatched by the Texture Manager when a texture it requested to load failed.
+ * This only happens when base64 encoded textures fail. All other texture types are loaded via the Loader Plugin.
+ * 
+ * Listen to this event from within a Scene using: `this.textures.on('onerror', listener)`.
+ *
+ * @event Phaser.Textures.Events#ERROR
+ * 
+ * @param {string} key - The key of the Texture that failed to load into the Texture Manager.
+ */
+module.exports = 'onerror';

src/textures/events/LOAD_EVENT.js

@@ -0,0 +1,22 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Texture Load Event.
+ * 
+ * This event is dispatched by the Texture Manager when a texture has finished loading on it.
+ * This only happens for base64 encoded textures. All other texture types are loaded via the Loader Plugin.
+ * 
+ * Listen to this event from within a Scene using: `this.textures.on('onload', listener)`.
+ * 
+ * This event is dispatched after the [ADD event]{Phaser.Textures.Events#ADD}.
+ *
+ * @event Phaser.Textures.Events#LOAD
+ * 
+ * @param {string} key - The key of the Texture that was loaded by the Texture Manager.
+ * @param {Phaser.Textures.Texture} texture - A reference to the Texture that was loaded by the Texture Manager.
+ */
+module.exports = 'onload';

src/core/events/TEXTURES_READY_EVENT.js src/textures/events/READY_EVENT.jssrc/core/events/TEXTURES_READY_EVENT.js renamed to src/textures/events/READY_EVENT.js

@@ -5,12 +5,12 @@
  */
 
 /**
- * The Game Boot Texture Manager is Ready Event.
+ * This internal event signifies that the Texture Manager is now ready and the Game can continue booting.
  * 
  * When a Phaser Game instance is booting for the first time, the Texture Manager has to wait on a couple of non-blocking
  * async events before it's fully ready to carry on. When those complete the Texture Manager emits this event via the Game
  * instance, which tells the Game to carry on booting.
  *
- * @event Phaser.Core.Events#TEXTURES_READY
+ * @event Phaser.Textures.Events#READY
  */
-module.exports = 'texturesready';
+module.exports = 'ready';

src/textures/events/REMOVE_EVENT.js

@@ -0,0 +1,21 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * The Texture Remove Event.
+ * 
+ * This event is dispatched by the Texture Manager when a texture is removed from it.
+ * 
+ * Listen to this event from within a Scene using: `this.textures.on('removetexture', listener)`.
+ * 
+ * If you have any Game Objects still using the removed texture, they will start throwing
+ * errors the next time they try to render. Be sure to clear all use of the texture in this event handler.
+ *
+ * @event Phaser.Textures.Events#REMOVE
+ * 
+ * @param {string} key - The key of the Texture that was removed from the Texture Manager.
+ */
+module.exports = 'removetexture';

src/textures/events/index.js

@@ -0,0 +1,19 @@
+/**
+ * @author       Richard Davey <rich@photonstorm.com>
+ * @copyright    2019 Photon Storm Ltd.
+ * @license      {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
+ */
+
+/**
+ * @namespace Phaser.Textures.Events
+ */
+
+module.exports = {
+
+    ADD: require('./ADD_EVENT'),
+    ERROR: require('./ERROR_EVENT'),
+    LOAD: require('./LOAD_EVENT'),
+    READY: require('./READY_EVENT'),
+    REMOVE: require('./REMOVE_EVENT')
+
+};