Skip to content

Commit 349a5a1

Browse files
photonstormphotonstorm
committed
Added MultiScriptFile file type
1 parent 226daaa commit 349a5a1

2 files changed

Lines changed: 221 additions & 0 deletions

File tree

‎src/loader/filetypes/MultiScriptFile.js‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
/**
2+
* @author Richard Davey <rich@photonstorm.com>
3+
* @copyright 2019 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 FileTypesManager = require('../FileTypesManager');
9+
var GetFastValue = require('../../utils/object/GetFastValue');
10+
var IsPlainObject = require('../../utils/object/IsPlainObject');
11+
var MultiFile = require('../MultiFile.js');
12+
var ScriptFile = require('./ScriptFile.js');
13+
14+
/**
15+
* @typedef {object} Phaser.Loader.FileTypes.MultiScriptFileConfig
16+
*
17+
* @property {string} key - The key of the file. Must be unique within the Loader.
18+
* @property {string[]} [url] - An array of absolute or relative URLs to load the script files from. They are processed in the order given in the array.
19+
* @property {string} [extension='js'] - The default file extension to use if no url is provided.
20+
* @property {Phaser.Loader.Types.XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for these files.
21+
*/
22+
23+
/**
24+
* @classdesc
25+
* A Multi Script File suitable for loading by the Loader.
26+
*
27+
* These are created when you use the Phaser.Loader.LoaderPlugin#scripts method and are not typically created directly.
28+
*
29+
* For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#scripts.
30+
*
31+
* @class MultiScriptFile
32+
* @extends Phaser.Loader.MultiFile
33+
* @memberof Phaser.Loader.FileTypes
34+
* @constructor
35+
* @since 3.17.0
36+
*
37+
* @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file.
38+
* @param {(string|Phaser.Loader.FileTypes.MultiScriptFileConfig)} key - The key to use for this file, or a file configuration object.
39+
* @param {string[]} [url] - An array of absolute or relative URLs to load the script files from. They are processed in the order given in the array.
40+
* @param {Phaser.Loader.Types.XHRSettingsObject} [xhrSettings] - An XHR Settings configuration object for the script files. Used in replacement of the Loaders default XHR Settings.
41+
*/
42+
var MultiScriptFile = new Class({
43+
44+
Extends: MultiFile,
45+
46+
initialize:
47+
48+
function MultiScriptFile (loader, key, url, xhrSettings)
49+
{
50+
var extension = 'js';
51+
var files = [];
52+
53+
if (IsPlainObject(key))
54+
{
55+
var config = key;
56+
57+
key = GetFastValue(config, 'key');
58+
url = GetFastValue(config, 'url');
59+
xhrSettings = GetFastValue(config, 'xhrSettings');
60+
extension = GetFastValue(config, 'extension', extension);
61+
}
62+
63+
if (!Array.isArray(url))
64+
{
65+
url = [ url ];
66+
}
67+
68+
for (var i = 0; i < url.length; i++)
69+
{
70+
var scriptFile = new ScriptFile(loader, {
71+
key: key + '_' + i.toString(),
72+
url: url[i],
73+
extension: extension,
74+
xhrSettings: xhrSettings
75+
});
76+
77+
// Override the default onProcess function
78+
scriptFile.onProcess = function ()
79+
{
80+
this.onProcessComplete();
81+
};
82+
83+
files.push(scriptFile);
84+
}
85+
86+
MultiFile.call(this, loader, 'scripts', key, files);
87+
},
88+
89+
/**
90+
* Adds this file to its target cache upon successful loading and processing.
91+
*
92+
* @method Phaser.Loader.FileTypes.MultiScriptFile#addToCache
93+
* @since 3.17.0
94+
*/
95+
addToCache: function ()
96+
{
97+
if (this.isReadyToProcess())
98+
{
99+
for (var i = 0; i < this.files.length; i++)
100+
{
101+
var file = this.files[i];
102+
103+
file.data = document.createElement('script');
104+
file.data.language = 'javascript';
105+
file.data.type = 'text/javascript';
106+
file.data.defer = false;
107+
file.data.text = file.xhrLoader.responseText;
108+
109+
document.head.appendChild(file.data);
110+
}
111+
112+
this.complete = true;
113+
}
114+
}
115+
116+
});
117+
118+
/**
119+
* Adds an array of Script files to the current load queue.
120+
*
121+
* The difference between this and the `ScriptFile` file type is that you give an array of scripts to this method,
122+
* and the scripts are then processed _exactly_ in that order. This allows you to load a bunch of scripts that
123+
* may have dependancies on each other without worrying about the async nature of traditional script loading.
124+
*
125+
* You can call this method from within your Scene's `preload`, along with any other files you wish to load:
126+
*
127+
* ```javascript
128+
* function preload ()
129+
* {
130+
* this.load.scripts('PostProcess', [
131+
* 'libs/shaders/CopyShader.js',
132+
* 'libs/postprocessing/EffectComposer.js',
133+
* 'libs/postprocessing/RenderPass.js',
134+
* 'libs/postprocessing/MaskPass.js',
135+
* 'libs/postprocessing/ShaderPass.js',
136+
* 'libs/postprocessing/AfterimagePass.js'
137+
* ]);
138+
* }
139+
* ```
140+
*
141+
* In the code above the script files will all be loaded in parallel but only processed (i.e. invoked) in the exact
142+
* order given in the array.
143+
*
144+
* The files are **not** loaded right away. They are added to a queue ready to be loaded either when the loader starts,
145+
* or if it's already running, when the next free load slot becomes available. This happens automatically if you
146+
* are calling this from within the Scene's `preload` method, or a related callback. Because the files are queued
147+
* it means you cannot use the files immediately after calling this method, but must wait for the files to complete.
148+
* The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the
149+
* Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been
150+
* loaded.
151+
*
152+
* The key must be a unique String and not already in-use by another file in the Loader.
153+
*
154+
* Instead of passing arguments you can pass a configuration object, such as:
155+
*
156+
* ```javascript
157+
* this.load.scripts({
158+
* key: 'PostProcess',
159+
* url: [
160+
* 'libs/shaders/CopyShader.js',
161+
* 'libs/postprocessing/EffectComposer.js',
162+
* 'libs/postprocessing/RenderPass.js',
163+
* 'libs/postprocessing/MaskPass.js',
164+
* 'libs/postprocessing/ShaderPass.js',
165+
* 'libs/postprocessing/AfterimagePass.js'
166+
* ]
167+
* });
168+
* ```
169+
*
170+
* See the documentation for `Phaser.Loader.FileTypes.MultiScriptFileConfig` for more details.
171+
*
172+
* Once all the files have finished loading they will automatically be converted into a script element
173+
* via `document.createElement('script')`. They will have their language set to JavaScript, `defer` set to
174+
* false and then the resulting element will be appended to `document.head`. Any code then in the
175+
* script will be executed. This is done in the exact order the files are specified in the url array.
176+
*
177+
* The URLs can be relative or absolute. If the URLs are relative the `Loader.baseURL` and `Loader.path` values will be prepended to them.
178+
*
179+
* Note: The ability to load this type of file will only be available if the MultiScript 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#scripts
183+
* @fires Phaser.Loader.LoaderPlugin#addFileEvent
184+
* @since 3.17.0
185+
*
186+
* @param {(string|Phaser.Loader.FileTypes.MultiScriptFileConfig|Phaser.Loader.FileTypes.MultiScriptFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them.
187+
* @param {string[]} [url] - An array of absolute or relative URLs to load the script files from. They are processed in the order given in the array.
188+
* @param {string} [extension='js'] - The default file extension to use if no url is provided.
189+
* @param {Phaser.Loader.Types.XHRSettingsObject} [xhrSettings] - Extra XHR Settings specifically for these files.
190+
*
191+
* @return {Phaser.Loader.LoaderPlugin} The Loader instance.
192+
*/
193+
FileTypesManager.register('scripts', function (key, url, xhrSettings)
194+
{
195+
var multifile;
196+
197+
// Supports an Object file definition in the key argument
198+
// Or an array of objects in the key argument
199+
// Or a single entry where all arguments have been defined
200+
201+
if (Array.isArray(key))
202+
{
203+
for (var i = 0; i < key.length; i++)
204+
{
205+
multifile = new MultiScriptFile(this, key[i]);
206+
207+
this.addFile(multifile.files);
208+
}
209+
}
210+
else
211+
{
212+
multifile = new MultiScriptFile(this, key, url, xhrSettings);
213+
214+
this.addFile(multifile.files);
215+
}
216+
217+
return this;
218+
});
219+
220+
module.exports = MultiScriptFile;

‎src/loader/filetypes/index.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ module.exports = {
2424
ImageFile: require('./ImageFile'),
2525
JSONFile: require('./JSONFile'),
2626
MultiAtlasFile: require('./MultiAtlasFile'),
27+
MultiScriptFile: require('./MultiScriptFile'),
2728
PackFile: require('./PackFile'),
2829
PluginFile: require('./PluginFile'),
2930
SceneFile: require('./SceneFile'),

0 commit comments

Comments
 (0)