Skip to content

Commit ed9dbde

Browse files
photonstormphotonstorm
committed
Added jsdocs
1 parent 5700e9a commit ed9dbde

1 file changed

Lines changed: 143 additions & 24 deletions

File tree

‎src/loader/filetypes/UnityAtlasFile.js‎

Lines changed: 143 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,38 @@ var IsPlainObject = require('../../utils/object/IsPlainObject');
1212
var MultiFile = require('../MultiFile.js');
1313
var TextFile = require('./TextFile.js');
1414

15+
/**
16+
* @typedef {object} Phaser.Loader.FileTypes.UnityAtlasFileConfig
17+
*
18+
* @property {string} key - The key of the file. Must be unique within both the Loader and the Texture Manager.
19+
* @property {string} [textureURL] - The absolute or relative URL to load the texture image file from.
20+
* @property {string} [textureExtension='png'] - The default file extension to use for the image texture if no url is provided.
21+
* @property {XHRSettingsObject} [textureXhrSettings] - Extra XHR Settings specifically for the texture image file.
22+
* @property {string} [normalMap] - The filename of an associated normal map. It uses the same path and url to load as the texture image.
23+
* @property {string} [atlasURL] - The absolute or relative URL to load the atlas data file from.
24+
* @property {string} [atlasExtension='txt'] - The default file extension to use for the atlas data if no url is provided.
25+
* @property {XHRSettingsObject} [atlasXhrSettings] - Extra XHR Settings specifically for the atlas data file.
26+
*/
27+
1528
/**
1629
* @classdesc
17-
* A Unity Atlas File.
30+
* A single text file based Unity Texture Atlas File suitable for loading by the Loader.
31+
*
32+
* These are created when you use the Phaser.Loader.LoaderPlugin#unityAtlas method and are not typically created directly.
33+
*
34+
* For documentation about what all the arguments and configuration options mean please see Phaser.Loader.LoaderPlugin#unityAtlas.
1835
*
1936
* @class UnityAtlasFile
2037
* @extends Phaser.Loader.MultiFile
2138
* @memberOf Phaser.Loader.FileTypes
2239
* @constructor
2340
*
24-
* @param {string} key - The key of the file within the loader.
25-
* @param {string} textureURL - The url to load the texture file from.
26-
* @param {string} atlasURL - The url to load the atlas file from.
27-
* @param {XHRSettingsObject} [textureXhrSettings] - Optional texture file specific XHR settings.
28-
* @param {XHRSettingsObject} [atlasXhrSettings] - Optional atlas file specific XHR settings.
41+
* @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file.
42+
* @param {(string|Phaser.Loader.FileTypes.UnityAtlasFileConfig)} key - The key to use for this file, or a file configuration object.
43+
* @param {string|string[]} [textureURL] - The absolute or relative URL to load the texture image file from. If undefined or `null` it will be set to `<key>.png`, i.e. if `key` was "alien" then the URL will be "alien.png".
44+
* @param {string} [atlasURL] - The absolute or relative URL to load the texture atlas data file from. If undefined or `null` it will be set to `<key>.txt`, i.e. if `key` was "alien" then the URL will be "alien.txt".
45+
* @param {XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the atlas image file. Used in replacement of the Loaders default XHR Settings.
46+
* @param {XHRSettingsObject} [atlasXhrSettings] - An XHR Settings configuration object for the atlas data file. Used in replacement of the Loaders default XHR Settings.
2947
*/
3048
var UnityAtlasFile = new Class({
3149

@@ -35,19 +53,33 @@ var UnityAtlasFile = new Class({
3553

3654
function UnityAtlasFile (loader, key, textureURL, atlasURL, textureXhrSettings, atlasXhrSettings)
3755
{
56+
var image;
57+
var data;
58+
3859
if (IsPlainObject(key))
3960
{
4061
var config = key;
4162

42-
key = GetFastValue(config, 'key');
43-
textureURL = GetFastValue(config, 'textureURL');
44-
atlasURL = GetFastValue(config, 'atlasURL');
45-
textureXhrSettings = GetFastValue(config, 'textureXhrSettings');
46-
atlasXhrSettings = GetFastValue(config, 'atlasXhrSettings');
63+
image = new ImageFile(loader, {
64+
key: key,
65+
url: GetFastValue(config, 'textureURL'),
66+
extension: GetFastValue(config, 'textureExtension', 'png'),
67+
normalMap: GetFastValue(config, 'normalMap'),
68+
xhrSettings: GetFastValue(config, 'textureXhrSettings')
69+
});
70+
71+
data = new TextFile(loader, {
72+
key: key,
73+
url: GetFastValue(config, 'atlasURL'),
74+
extension: GetFastValue(config, 'atlasExtension', 'txt'),
75+
xhrSettings: GetFastValue(config, 'atlasXhrSettings')
76+
});
77+
}
78+
else
79+
{
80+
image = new ImageFile(loader, key, textureURL, textureXhrSettings);
81+
data = new TextFile(loader, key, atlasURL, atlasXhrSettings);
4782
}
48-
49-
var image = new ImageFile(loader, key, textureURL, textureXhrSettings);
50-
var data = new TextFile(loader, key, atlasURL, atlasXhrSettings);
5183

5284
if (image.linkFile)
5385
{
@@ -60,6 +92,12 @@ var UnityAtlasFile = new Class({
6092
}
6193
},
6294

95+
/**
96+
* Adds this file to its target cache upon successful loading and processing.
97+
*
98+
* @method Phaser.Loader.FileTypes.UnityAtlasFile#addToCache
99+
* @since 3.7.0
100+
*/
63101
addToCache: function ()
64102
{
65103
if (this.failed === 0 && !this.complete)
@@ -79,23 +117,104 @@ var UnityAtlasFile = new Class({
79117
});
80118

81119
/**
82-
* Adds a Unity Texture Atlas file to the current load queue.
120+
* Adds a Unity YAML based Texture Atlas, or array of atlases, to the current load queue.
121+
*
122+
* You can call this method from within your Scene's `preload`, along with any other files you wish to load:
123+
*
124+
* ```javascript
125+
* function preload ()
126+
* {
127+
* this.load.unityAtlas('mainmenu', 'images/MainMenu.png', 'images/MainMenu.txt');
128+
* }
129+
* ```
130+
*
131+
* The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts,
132+
* or if it's already running, when the next free load slot becomes available. This happens automatically if you
133+
* are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued
134+
* it means you cannot use the file immediately after calling this method, but must wait for the file to complete.
135+
* The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the
136+
* Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been
137+
* loaded.
138+
*
139+
* If you call this from outside of `preload` then you are responsible for starting the Loader afterwards and monitoring
140+
* its events to know when it's safe to use the asset. Please see the Phaser.Loader.LoaderPlugin class for more details.
141+
*
142+
* Phaser expects the atlas data to be provided in a YAML formatted text file as exported from Unity.
143+
*
144+
* Phaser can load all common image types: png, jpg, gif and any other format the browser can natively handle.
145+
*
146+
* The key must be a unique String. It is used to add the file to the global Texture Manager upon a successful load.
147+
* The key should be unique both in terms of files being loaded and files already present in the Texture Manager.
148+
* Loading a file using a key that is already taken will result in a warning. If you wish to replace an existing file
149+
* then remove it from the Texture Manager first, before loading a new one.
150+
*
151+
* Instead of passing arguments you can pass a configuration object, such as:
152+
*
153+
* ```javascript
154+
* this.load.unityAtlas({
155+
* key: 'mainmenu',
156+
* textureURL: 'images/MainMenu.png',
157+
* atlasURL: 'images/MainMenu.txt'
158+
* });
159+
* ```
160+
*
161+
* See the documentation for `Phaser.Loader.FileTypes.UnityAtlasFileConfig` for more details.
162+
*
163+
* Once the atlas has finished loading you can use frames from it as textures for a Game Object by referencing its key:
164+
*
165+
* ```javascript
166+
* this.load.unityAtlas('mainmenu', 'images/MainMenu.png', 'images/MainMenu.json');
167+
* // and later in your game ...
168+
* this.add.image(x, y, 'mainmenu', 'background');
169+
* ```
170+
*
171+
* To get a list of all available frames within an atlas please consult your Texture Atlas software.
172+
*
173+
* If you have specified a prefix in the loader, via `Loader.setPrefix` then this value will be prepended to this files
174+
* key. For example, if the prefix was `MENU.` and the key was `Background` the final key will be `MENU.Background` and
175+
* this is what you would use to retrieve the image from the Texture Manager.
176+
*
177+
* The URL can be relative or absolute. If the URL is relative the `Loader.baseURL` and `Loader.path` values will be prepended to it.
178+
*
179+
* 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"
180+
* and no URL is given then the Loader will set the URL to be "alien.png". It will always add `.png` as the extension, although
181+
* this can be overridden if using an object instead of method arguments. If you do not desire this action then provide a URL.
182+
*
183+
* Phaser also supports the automatic loading of associated normal maps. If you have a normal map to go with this image,
184+
* then you can specify it by providing an array as the `url` where the second element is the normal map:
185+
*
186+
* ```javascript
187+
* this.load.unityAtlas('mainmenu', [ 'images/MainMenu.png', 'images/MainMenu-n.png' ], 'images/MainMenu.txt');
188+
* ```
189+
*
190+
* Or, if you are using a config object use the `normalMap` property:
191+
*
192+
* ```javascript
193+
* this.load.unityAtlas({
194+
* key: 'mainmenu',
195+
* textureURL: 'images/MainMenu.png',
196+
* normalMap: 'images/MainMenu-n.png',
197+
* atlasURL: 'images/MainMenu.txt'
198+
* });
199+
* ```
83200
*
84-
* Note: This method will only be available if the Unity Atlas File type has been built into Phaser.
201+
* The normal map file is subject to the same conditions as the image file with regard to the path, baseURL, CORs and XHR Settings.
202+
* Normal maps are a WebGL only feature.
85203
*
86-
* The file is **not** loaded immediately after calling this method.
87-
* Instead, the file is added to a queue within the Loader, which is processed automatically when the Loader starts.
204+
* Note: The ability to load this type of file will only be available if the Unity Atlas File type has been built into Phaser.
205+
* It is available in the default build but can be excluded from custom builds.
88206
*
89207
* @method Phaser.Loader.LoaderPlugin#unityAtlas
208+
* @fires Phaser.Loader.LoaderPlugin#addFileEvent
90209
* @since 3.0.0
91210
*
92-
* @param {string} key - The key of the file within the loader.
93-
* @param {string} textureURL - The url to load the texture file from.
94-
* @param {string} atlasURL - The url to load the atlas file from.
95-
* @param {XHRSettingsObject} [textureXhrSettings] - Optional texture file specific XHR settings.
96-
* @param {XHRSettingsObject} [atlasXhrSettings] - Optional atlas file specific XHR settings.
211+
* @param {(string|Phaser.Loader.FileTypes.UnityAtlasFileConfig|Phaser.Loader.FileTypes.UnityAtlasFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them.
212+
* @param {string|string[]} [textureURL] - The absolute or relative URL to load the texture image file from. If undefined or `null` it will be set to `<key>.png`, i.e. if `key` was "alien" then the URL will be "alien.png".
213+
* @param {string} [atlasURL] - The absolute or relative URL to load the texture atlas data file from. If undefined or `null` it will be set to `<key>.txt`, i.e. if `key` was "alien" then the URL will be "alien.txt".
214+
* @param {XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the atlas image file. Used in replacement of the Loaders default XHR Settings.
215+
* @param {XHRSettingsObject} [atlasXhrSettings] - An XHR Settings configuration object for the atlas data file. Used in replacement of the Loaders default XHR Settings.
97216
*
98-
* @return {Phaser.Loader.LoaderPlugin} The Loader.
217+
* @return {Phaser.Loader.LoaderPlugin} The Loader instance.
99218
*/
100219
FileTypesManager.register('unityAtlas', function (key, textureURL, atlasURL, textureXhrSettings, atlasXhrSettings)
101220
{

0 commit comments

Comments
 (0)