|
| 1 | +/** |
| 2 | + * @author Richard Davey <rich@photonstorm.com> |
| 3 | + * @copyright 2018 Photon Storm Ltd. |
| 4 | + * @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License} |
| 5 | + */ |
| 6 | + |
| 7 | +var Class = require('../../utils/Class'); |
| 8 | +var CONST = require('../const'); |
| 9 | +var File = require('../File'); |
| 10 | +var FileTypesManager = require('../FileTypesManager'); |
| 11 | +var GetFastValue = require('../../utils/object/GetFastValue'); |
| 12 | +var IsPlainObject = require('../../utils/object/IsPlainObject'); |
| 13 | +var PluginManager = require('../../plugins/PluginManager'); |
| 14 | + |
| 15 | +/** |
| 16 | + * @typedef {object} Phaser.Loader.FileTypes.ScenePluginFileConfig |
| 17 | + * |
| 18 | + * @property {string} key - The key of the file. Must be unique within the Loader. |
| 19 | + * @property {(string|function)} [url] - The absolute or relative URL to load the file from. Or, a Scene Plugin. |
| 20 | + * @property {string} [extension='js'] - The default file extension to use if no url is provided. |
| 21 | + * @property {string} [systemKey] - If this plugin is to be added to Scene.Systems, this is the property key for it. |
| 22 | + * @property {string} [sceneKey] - If this plugin is to be added to the Scene, this is the property key for it. |
| 23 | + * @property {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. |
| 24 | + */ |
| 25 | + |
| 26 | +/** |
| 27 | + * @classdesc |
| 28 | + * A single Scene Plugin Script File suitable for loading by the Loader. |
| 29 | + * |
| 30 | + * These are created when you use the Phaser.Loader.LoaderPlugin#scenePlugin method and are not typically created directly. |
| 31 | + * |
| 32 | + * For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#scenePlugin. |
| 33 | + * |
| 34 | + * @class ScenePluginFile |
| 35 | + * @extends Phaser.Loader.File |
| 36 | + * @memberOf Phaser.Loader.FileTypes |
| 37 | + * @constructor |
| 38 | + * @since 3.8.0 |
| 39 | + * |
| 40 | + * @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file. |
| 41 | + * @param {(string|Phaser.Loader.FileTypes.ScenePluginFileConfig)} key - The key to use for this file, or a file configuration object. |
| 42 | + * @param {string} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `<key>.js`, i.e. if `key` was "alien" then the URL will be "alien.js". |
| 43 | + * @param {string} [systemKey] - If this plugin is to be added to Scene.Systems, this is the property key for it. |
| 44 | + * @param {string} [sceneKey] - If this plugin is to be added to the Scene, this is the property key for it. |
| 45 | + * @param {XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for this file. |
| 46 | + */ |
| 47 | +var ScenePluginFile = new Class({ |
| 48 | + |
| 49 | + Extends: File, |
| 50 | + |
| 51 | + initialize: |
| 52 | + |
| 53 | + function ScenePluginFile (loader, key, url, systemKey, sceneKey, xhrSettings) |
| 54 | + { |
| 55 | + var extension = 'js'; |
| 56 | + |
| 57 | + if (IsPlainObject(key)) |
| 58 | + { |
| 59 | + var config = key; |
| 60 | + |
| 61 | + key = GetFastValue(config, 'key'); |
| 62 | + url = GetFastValue(config, 'url'); |
| 63 | + xhrSettings = GetFastValue(config, 'xhrSettings'); |
| 64 | + extension = GetFastValue(config, 'extension', extension); |
| 65 | + systemKey = GetFastValue(config, 'systemKey'); |
| 66 | + sceneKey = GetFastValue(config, 'sceneKey'); |
| 67 | + } |
| 68 | + |
| 69 | + var fileConfig = { |
| 70 | + type: 'scenePlugin', |
| 71 | + cache: false, |
| 72 | + extension: extension, |
| 73 | + responseType: 'text', |
| 74 | + key: key, |
| 75 | + url: url, |
| 76 | + xhrSettings: xhrSettings, |
| 77 | + config: { |
| 78 | + systemKey: systemKey, |
| 79 | + sceneKey: sceneKey |
| 80 | + } |
| 81 | + }; |
| 82 | + |
| 83 | + File.call(this, loader, fileConfig); |
| 84 | + |
| 85 | + // If the url variable refers to a class, add the plugin directly |
| 86 | + if (typeof url === 'function') |
| 87 | + { |
| 88 | + this.data = url; |
| 89 | + |
| 90 | + this.state = CONST.FILE_POPULATED; |
| 91 | + } |
| 92 | + }, |
| 93 | + |
| 94 | + /** |
| 95 | + * Called automatically by Loader.nextFile. |
| 96 | + * This method controls what extra work this File does with its loaded data. |
| 97 | + * |
| 98 | + * @method Phaser.Loader.FileTypes.ScenePluginFile#onProcess |
| 99 | + * @since 3.8.0 |
| 100 | + */ |
| 101 | + onProcess: function () |
| 102 | + { |
| 103 | + var pluginManager = this.loader.systems.plugins; |
| 104 | + var config = this.config; |
| 105 | + |
| 106 | + var key = this.key; |
| 107 | + var systemKey = GetFastValue(config, 'systemKey', key); |
| 108 | + var sceneKey = GetFastValue(config, 'sceneKey', key); |
| 109 | + |
| 110 | + if (this.state === CONST.FILE_POPULATED) |
| 111 | + { |
| 112 | + pluginManager.installScenePlugin(systemKey, this.data, sceneKey, this.loader.scene); |
| 113 | + } |
| 114 | + else |
| 115 | + { |
| 116 | + // Plugin added via a js file |
| 117 | + this.state = CONST.FILE_PROCESSING; |
| 118 | + |
| 119 | + this.data = document.createElement('script'); |
| 120 | + this.data.language = 'javascript'; |
| 121 | + this.data.type = 'text/javascript'; |
| 122 | + this.data.defer = false; |
| 123 | + this.data.text = this.xhrLoader.responseText; |
| 124 | + |
| 125 | + document.head.appendChild(this.data); |
| 126 | + |
| 127 | + pluginManager.installScenePlugin(systemKey, window[this.key], sceneKey, this.loader.scene); |
| 128 | + } |
| 129 | + |
| 130 | + this.onProcessComplete(); |
| 131 | + } |
| 132 | + |
| 133 | +}); |
| 134 | + |
| 135 | +/** |
| 136 | + * Adds a Scene Plugin Script file, or array of plugin files, to the current load queue. |
| 137 | + * |
| 138 | + * You can call this method from within your Scene's `preload`, along with any other files you wish to load: |
| 139 | + * |
| 140 | + * ```javascript |
| 141 | + * function preload () |
| 142 | + * { |
| 143 | + * this.load.scenePlugin('ModPlayer', 'plugins/ModPlayer.js', 'modPlayer', 'mods'); |
| 144 | + * } |
| 145 | + * ``` |
| 146 | + * |
| 147 | + * The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts, |
| 148 | + * or if it's already running, when the next free load slot becomes available. This happens automatically if you |
| 149 | + * are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued |
| 150 | + * it means you cannot use the file immediately after calling this method, but must wait for the file to complete. |
| 151 | + * The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the |
| 152 | + * Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been |
| 153 | + * loaded. |
| 154 | + * |
| 155 | + * The key must be a unique String and not already in-use by another file in the Loader. |
| 156 | + * |
| 157 | + * Instead of passing arguments you can pass a configuration object, such as: |
| 158 | + * |
| 159 | + * ```javascript |
| 160 | + * this.load.scenePlugin({ |
| 161 | + * key: 'modplayer', |
| 162 | + * url: 'plugins/ModPlayer.js' |
| 163 | + * }); |
| 164 | + * ``` |
| 165 | + * |
| 166 | + * See the documentation for `Phaser.Loader.FileTypes.ScenePluginFileConfig` for more details. |
| 167 | + * |
| 168 | + * Once the file has finished loading it will automatically be converted into a script element |
| 169 | + * via `document.createElement('script')`. It will have its language set to JavaScript, `defer` set to |
| 170 | + * false and then the resulting element will be appended to `document.head`. Any code then in the |
| 171 | + * script will be executed. It will then be passed to the Phaser PluginManager.register method. |
| 172 | + * |
| 173 | + * The URL can be relative or absolute. If the URL is relative the `Loader.baseURL` and `Loader.path` values will be prepended to it. |
| 174 | + * |
| 175 | + * If the URL isn't specified the Loader will take the key and create a filename from that. For example if the key is "alien" |
| 176 | + * and no URL is given then the Loader will set the URL to be "alien.js". It will always add `.js` as the extension, although |
| 177 | + * this can be overridden if using an object instead of method arguments. If you do not desire this action then provide a URL. |
| 178 | + * |
| 179 | + * Note: The ability to load this type of file will only be available if the Script File type has been built into Phaser. |
| 180 | + * It is available in the default build but can be excluded from custom builds. |
| 181 | + * |
| 182 | + * @method Phaser.Loader.LoaderPlugin#scenePlugin |
| 183 | + * @fires Phaser.Loader.LoaderPlugin#addFileEvent |
| 184 | + * @since 3.8.0 |
| 185 | + * |
| 186 | + * @param {(string|Phaser.Loader.FileTypes.ScenePluginFileConfig|Phaser.Loader.FileTypes.ScenePluginFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them. |
| 187 | + * @param {(string|function)} [url] - The absolute or relative URL to load this file from. If undefined or `null` it will be set to `<key>.js`, i.e. if `key` was "alien" then the URL will be "alien.js". Or, set to a plugin function. |
| 188 | + * @param {string} [systemKey] - If this plugin is to be added to Scene.Systems, this is the property key for it. |
| 189 | + * @param {string} [sceneKey] - If this plugin is to be added to the Scene, this is the property key for it. |
| 190 | + * @param {XHRSettingsObject} [xhrSettings] - An XHR Settings configuration object. Used in replacement of the Loaders default XHR Settings. |
| 191 | + * |
| 192 | + * @return {Phaser.Loader.LoaderPlugin} The Loader instance. |
| 193 | + */ |
| 194 | +FileTypesManager.register('scenePlugin', function (key, url, systemKey, sceneKey, xhrSettings) |
| 195 | +{ |
| 196 | + if (Array.isArray(key)) |
| 197 | + { |
| 198 | + for (var i = 0; i < key.length; i++) |
| 199 | + { |
| 200 | + // If it's an array it has to be an array of Objects, so we get everything out of the 'key' object |
| 201 | + this.addFile(new ScenePluginFile(this, key[i])); |
| 202 | + } |
| 203 | + } |
| 204 | + else |
| 205 | + { |
| 206 | + this.addFile(new ScenePluginFile(this, key, url, systemKey, sceneKey, xhrSettings)); |
| 207 | + } |
| 208 | + |
| 209 | + return this; |
| 210 | +}); |
| 211 | + |
| 212 | +module.exports = ScenePluginFile; |
0 commit comments