mirror of
https://github.com/photonstorm/phaser
synced 2024-11-21 20:23:19 +00:00
More docs added
This commit is contained in:
parent
9486487a3e
commit
172ebef093
1 changed files with 69 additions and 56 deletions
|
@ -17,6 +17,9 @@ var SpineGameObject = require('./gameobject/SpineGameObject');
|
|||
* @classdesc
|
||||
* The Spine Plugin is a Scene based plugin that handles the creation and rendering of Spine Game objects.
|
||||
*
|
||||
* All rendering and object creation is handled via the official Spine Runtimes. This version of the plugin
|
||||
* uses the Spine 3.7 runtimes. Files created in a more recent version of Spine may not work as a result.
|
||||
*
|
||||
* Assuming a default environment you access it from within a Scene by using the `this.spine` reference.
|
||||
*
|
||||
* When this plugin is installed into a Scene it will add a Loader File Type, allowing you to load
|
||||
|
@ -36,6 +39,11 @@ var SpineGameObject = require('./gameobject/SpineGameObject');
|
|||
* things you can specify, such as the animation name, skeleton, slot attachments and more. Please
|
||||
* see the respective documentation and examples for further details.
|
||||
*
|
||||
* Phaser expects the Spine data to be exported from the Spine application in a JSON format, not binary.
|
||||
* The associated atlas files are scanned for any texture files present in them, which are then loaded.
|
||||
* If you have exported your Spine data with preMultipiedAlpha set, then you should enable this in the
|
||||
* load arguments, or you may see black outlines around skeleton textures.
|
||||
*
|
||||
* The Spine plugin is local to the Scene in which it is installed. This means a change to something,
|
||||
* such as the Skeleton Debug Renderer, in this Scene, will not impact the renderer in any other Scene.
|
||||
* The only exception to this is with the caches this plugin creates. Spine atlas and texture data are
|
||||
|
@ -408,14 +416,14 @@ var SpinePlugin = new Class({
|
|||
},
|
||||
|
||||
/**
|
||||
* Adds a JSON based Texture Atlas, or array of atlases, to the current load queue.
|
||||
* Adds a Spine Skeleton and Atlas file, or array of files, to the current load queue.
|
||||
*
|
||||
* You can call this method from within your Scene's `preload`, along with any other files you wish to load:
|
||||
*
|
||||
* ```javascript
|
||||
* function preload ()
|
||||
* {
|
||||
* this.load.atlas('mainmenu', 'images/MainMenu.png', 'images/MainMenu.json');
|
||||
* this.load.spine('spineBoy', 'boy.json', 'boy.atlas', true);
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
|
@ -429,86 +437,60 @@ var SpinePlugin = new Class({
|
|||
*
|
||||
* If you call this from outside of `preload` then you are responsible for starting the Loader afterwards and monitoring
|
||||
* its events to know when it's safe to use the asset. Please see the Phaser.Loader.LoaderPlugin class for more details.
|
||||
*
|
||||
* Phaser expects the atlas data to be provided in a JSON file, using either the JSON Hash or JSON Array format.
|
||||
* These files are created by software such as Texture Packer, Shoebox and Adobe Flash / Animate.
|
||||
* If you are using Texture Packer and have enabled multi-atlas support, then please use the Phaser Multi Atlas loader
|
||||
* instead of this one.
|
||||
*
|
||||
* Phaser can load all common image types: png, jpg, gif and any other format the browser can natively handle.
|
||||
*
|
||||
* The key must be a unique String. It is used to add the file to the global Texture Manager upon a successful load.
|
||||
* The key should be unique both in terms of files being loaded and files already present in the Texture Manager.
|
||||
* Loading a file using a key that is already taken will result in a warning. If you wish to replace an existing file
|
||||
* then remove it from the Texture Manager first, before loading a new one.
|
||||
* Phaser expects the Spine data to be exported from the Spine application in a JSON format, not binary. The associated
|
||||
* atlas files are scanned for any texture files present in them, which are then loaded. If you have exported
|
||||
* your Spine data with preMultipiedAlpha set, then you should enable this in the arguments, or you may see black
|
||||
* outlines around skeleton textures.
|
||||
*
|
||||
* The key must be a unique String. It is used to add the file to the global Spine cache upon a successful load.
|
||||
* The key should be unique both in terms of files being loaded and files already present in the Spine cache.
|
||||
* Loading a file using a key that is already taken will result in a warning.
|
||||
*
|
||||
* Instead of passing arguments you can pass a configuration object, such as:
|
||||
*
|
||||
* ```javascript
|
||||
* this.load.atlas({
|
||||
* this.load.spine({
|
||||
* key: 'mainmenu',
|
||||
* textureURL: 'images/MainMenu.png',
|
||||
* atlasURL: 'images/MainMenu.json'
|
||||
* jsonURL: 'boy.json',
|
||||
* atlasURL: 'boy.atlas',
|
||||
* preMultipliedAlpha: true
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* See the documentation for `Phaser.Types.Loader.FileTypes.AtlasJSONFileConfig` for more details.
|
||||
*
|
||||
* Instead of passing a URL for the atlas JSON data you can also pass in a well formed JSON object instead.
|
||||
*
|
||||
* Once the atlas has finished loading you can use frames from it as textures for a Game Object by referencing its key:
|
||||
*
|
||||
* If you need to load multiple Spine atlas files, provide them as an array:
|
||||
*
|
||||
* ```javascript
|
||||
* this.load.atlas('mainmenu', 'images/MainMenu.png', 'images/MainMenu.json');
|
||||
* // and later in your game ...
|
||||
* this.add.image(x, y, 'mainmenu', 'background');
|
||||
* function preload ()
|
||||
* {
|
||||
* this.load.spine('demos', 'demos.json', [ 'atlas1.atlas', 'atlas2.atlas' ], true);
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* To get a list of all available frames within an atlas please consult your Texture Atlas software.
|
||||
* See the documentation for `Phaser.Types.Loader.FileTypes.SpineFileConfig` for more details.
|
||||
*
|
||||
* If you have specified a prefix in the loader, via `Loader.setPrefix` then this value will be prepended to this files
|
||||
* key. For example, if the prefix was `MENU.` and the key was `Background` the final key will be `MENU.Background` and
|
||||
* this is what you would use to retrieve the image from the Texture Manager.
|
||||
* this is what you would use to retrieve the data from the Spine plugin.
|
||||
*
|
||||
* The URL can be relative or absolute. If the URL is relative the `Loader.baseURL` and `Loader.path` values will be prepended to it.
|
||||
*
|
||||
* 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"
|
||||
* 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
|
||||
* and no URL is given then the Loader will set the URL to be "alien.json". It will always add `.json` as the extension, although
|
||||
* this can be overridden if using an object instead of method arguments. If you do not desire this action then provide a URL.
|
||||
*
|
||||
* Phaser also supports the automatic loading of associated normal maps. If you have a normal map to go with this image,
|
||||
* then you can specify it by providing an array as the `url` where the second element is the normal map:
|
||||
*
|
||||
* ```javascript
|
||||
* this.load.atlas('mainmenu', [ 'images/MainMenu.png', 'images/MainMenu-n.png' ], 'images/MainMenu.json');
|
||||
* ```
|
||||
*
|
||||
* Or, if you are using a config object use the `normalMap` property:
|
||||
*
|
||||
* ```javascript
|
||||
* this.load.atlas({
|
||||
* key: 'mainmenu',
|
||||
* textureURL: 'images/MainMenu.png',
|
||||
* normalMap: 'images/MainMenu-n.png',
|
||||
* atlasURL: 'images/MainMenu.json'
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* The normal map file is subject to the same conditions as the image file with regard to the path, baseURL, CORs and XHR Settings.
|
||||
* Normal maps are a WebGL only feature.
|
||||
*
|
||||
* Note: The ability to load this type of file will only be available if the Atlas JSON File type has been built into Phaser.
|
||||
* It is available in the default build but can be excluded from custom builds.
|
||||
* Note: The ability to load this type of file will only be available if the Spine Plugin has been built or loaded into Phaser.
|
||||
*
|
||||
* @method Phaser.Loader.LoaderPlugin#spine
|
||||
* @fires Phaser.Loader.LoaderPlugin#addFileEvent
|
||||
* @since 3.19.0
|
||||
*
|
||||
* @param {(string|Phaser.Types.Loader.FileTypes.AtlasJSONFileConfig|Phaser.Types.Loader.FileTypes.AtlasJSONFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them.
|
||||
* @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".
|
||||
* @param {string} [atlasURL] - The absolute or relative URL to load the texture atlas json data file from. If undefined or `null` it will be set to `<key>.json`, i.e. if `key` was "alien" then the URL will be "alien.json".
|
||||
* @param {Phaser.Types.Loader.XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the atlas image file. Used in replacement of the Loaders default XHR Settings.
|
||||
* @param {Phaser.Types.Loader.XHRSettingsObject} [atlasXhrSettings] - An XHR Settings configuration object for the atlas json file. Used in replacement of the Loaders default XHR Settings.
|
||||
* @param {(string|Phaser.Types.Loader.FileTypes.JSONFileConfig|Phaser.Types.Loader.FileTypes.JSONFileConfig[])} key - The key to use for this file, or a file configuration object, or array of them.
|
||||
* @param {string} jsonURL - The absolute or relative URL to load the Spine json file from. If undefined or `null` it will be set to `<key>.json`, i.e. if `key` was "alien" then the URL will be "alien.json".
|
||||
* @param {string|string[]} atlasURL - The absolute or relative URL to load the Spine atlas file from. If undefined or `null` it will be set to `<key>.atlas`, i.e. if `key` was "alien" then the URL will be "alien.atlas".
|
||||
* @param {boolean} [preMultipiedAlpha=false] - Do the texture files include pre-multiplied alpha or not?
|
||||
* @param {Phaser.Types.Loader.XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the Spine json file. Used in replacement of the Loaders default XHR Settings.
|
||||
* @param {Phaser.Types.Loader.XHRSettingsObject} [atlasXhrSettings] - An XHR Settings configuration object for the Spine atlas file. Used in replacement of the Loaders default XHR Settings.
|
||||
*
|
||||
* @return {Phaser.Loader.LoaderPlugin} The Loader instance.
|
||||
*/
|
||||
|
@ -541,6 +523,22 @@ var SpinePlugin = new Class({
|
|||
* The x and y coordinate given is used to set the placement of the root Spine bone, which can vary from
|
||||
* skeleton to skeleton. All rotation and scaling happens from the root bone placement. Spine Game Objects
|
||||
* do not have a Phaser origin.
|
||||
*
|
||||
* If the Spine JSON file exported multiple Skeletons within it, then you can specify them by using a period
|
||||
* character in the key. For example, if you loaded a Spine JSON using the key `monsters` and it contains
|
||||
* multiple Skeletons, including one called `goblin` then you would use the key `monsters.goblin` to reference
|
||||
* that.
|
||||
*
|
||||
* ```javascript
|
||||
* let jelly = this.add.spine(512, 550, 'jelly', 'jelly-think', true);
|
||||
* ```
|
||||
*
|
||||
* The key is optional. If not passed here, you need to call `SpineGameObject.setSkeleton()` to use it.
|
||||
*
|
||||
* The animation name is also optional and can be set later via `SpineGameObject.setAnimation`.
|
||||
*
|
||||
* Should you wish for more control over the object creation, such as setting a slot attachment or skin
|
||||
* name, then use `SpinePlugin.make` instead.
|
||||
*
|
||||
* @method SpinePlugin#add
|
||||
* @since 3.19.0
|
||||
|
@ -569,6 +567,21 @@ var SpinePlugin = new Class({
|
|||
* The x and y coordinate given is used to set the placement of the root Spine bone, which can vary from
|
||||
* skeleton to skeleton. All rotation and scaling happens from the root bone placement. Spine Game Objects
|
||||
* do not have a Phaser origin.
|
||||
*
|
||||
* If the Spine JSON file exported multiple Skeletons within it, then you can specify them by using a period
|
||||
* character in the key. For example, if you loaded a Spine JSON using the key `monsters` and it contains
|
||||
* multiple Skeletons, including one called `goblin` then you would use the key `monsters.goblin` to reference
|
||||
* that.
|
||||
*
|
||||
* ```javascript
|
||||
* let jelly = this.make.spine({
|
||||
* x: 500, y: 500, key: 'jelly',
|
||||
* scale: 1.5,
|
||||
* skinName: 'square_Green',
|
||||
* animationName: 'jelly-idle', loop: true,
|
||||
* slotName: 'hat', attachmentName: 'images/La_14'
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @method SpinePlugin#make
|
||||
* @since 3.19.0
|
||||
|
|
Loading…
Reference in a new issue