From dc332f1e1ec85bd10be28a38da2e3d2b90b85bfa Mon Sep 17 00:00:00 2001 From: Richard Davey Date: Wed, 7 Aug 2019 17:43:19 +0100 Subject: [PATCH] JSDocs added for whole Spine Plugin --- plugins/spine/src/SpineFile.js | 18 +- plugins/spine/src/SpinePlugin.js | 871 ++++++++++++++---- .../spine/src/gameobject/SpineGameObject.js | 23 +- .../SpineGameObjectCanvasRenderer.js | 8 +- .../src/gameobject/SpineGameObjectRender.js | 2 +- .../SpineGameObjectWebGLRenderer.js | 4 +- 6 files changed, 711 insertions(+), 215 deletions(-) diff --git a/plugins/spine/src/SpineFile.js b/plugins/spine/src/SpineFile.js index 22a3705e6..d437aa659 100644 --- a/plugins/spine/src/SpineFile.js +++ b/plugins/spine/src/SpineFile.js @@ -39,11 +39,11 @@ var TextFile = require('../../../src/loader/filetypes/TextFile.js'); * @constructor * * @param {Phaser.Loader.LoaderPlugin} loader - A reference to the Loader that is responsible for this file. - * @param {(string|Phaser.Loader.FileTypes.UnityAtlasFileConfig)} key - The key to use for this file, or a file configuration object. - * @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 `.png`, i.e. if `key` was "alien" then the URL will be "alien.png". + * @param {(string|Phaser.Loader.FileTypes.SpineFileConfig)} key - The key to use for this file, or a file configuration object. + * @param {string|string[]} [jsonURL] - The absolute or relative URL to load the JSON file from. If undefined or `null` it will be set to `.json`, i.e. if `key` was "alien" then the URL will be "alien.json". * @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 `.txt`, i.e. if `key` was "alien" then the URL will be "alien.txt". - * @param {boolean} [preMultipliedAlpha=false] - - * @param {XHRSettingsObject} [textureXhrSettings] - An XHR Settings configuration object for the atlas image file. Used in replacement of the Loaders default XHR Settings. + * @param {boolean} [preMultipliedAlpha=false] - Do the textures contain pre-multiplied alpha or not? + * @param {XHRSettingsObject} [jsonXhrSettings] - An XHR Settings configuration object for the json file. Used in replacement of the Loaders default XHR Settings. * @param {XHRSettingsObject} [atlasXhrSettings] - An XHR Settings configuration object for the atlas data file. Used in replacement of the Loaders default XHR Settings. */ var SpineFile = new Class({ @@ -89,11 +89,10 @@ var SpineFile = new Class({ key: key, url: atlasURL[i], extension: GetFastValue(config, 'atlasExtension', 'atlas'), - xhrSettings: GetFastValue(config, 'atlasXhrSettings'), + xhrSettings: GetFastValue(config, 'atlasXhrSettings') }); atlas.cache = cache; - // atlas.config.preMultipliedAlpha = preMultipliedAlpha; files.push(atlas); } @@ -111,7 +110,6 @@ var SpineFile = new Class({ { atlas = new TextFile(loader, key + '_' + i, atlasURL[i], atlasXhrSettings); atlas.cache = cache; - // atlas.config.preMultipliedAlpha = preMultipliedAlpha; files.push(atlas); } @@ -127,8 +125,8 @@ var SpineFile = new Class({ /** * Called by each File when it finishes loading. * - * @method Phaser.Loader.MultiFile#onFileComplete - * @since 3.7.0 + * @method Phaser.Loader.FileTypes.SpineFile#onFileComplete + * @since 3.19.0 * * @param {Phaser.Loader.File} file - The File that has completed processing. */ @@ -201,7 +199,7 @@ var SpineFile = new Class({ * Adds this file to its target cache upon successful loading and processing. * * @method Phaser.Loader.FileTypes.SpineFile#addToCache - * @since 3.16.0 + * @since 3.19.0 */ addToCache: function () { diff --git a/plugins/spine/src/SpinePlugin.js b/plugins/spine/src/SpinePlugin.js index b80c1ab6f..3d82aeef8 100644 --- a/plugins/spine/src/SpinePlugin.js +++ b/plugins/spine/src/SpinePlugin.js @@ -1,23 +1,49 @@ /** * @author Richard Davey - * @copyright 2018 Photon Storm Ltd. + * @copyright 2019 Photon Storm Ltd. * @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License} */ var BuildGameObject = require('../../../src/gameobjects/BuildGameObject'); var Class = require('../../../src/utils/Class'); var GetValue = require('../../../src/utils/object/GetValue'); -var ScenePlugin = require('../../../src/plugins/ScenePlugin'); -var SpineFile = require('./SpineFile'); -var Spine = require('Spine'); -var SpineGameObject = require('./gameobject/SpineGameObject'); var ResizeEvent = require('../../../src/scale/events/RESIZE_EVENT'); +var ScenePlugin = require('../../../src/plugins/ScenePlugin'); +var Spine = require('Spine'); +var SpineFile = require('./SpineFile'); +var SpineGameObject = require('./gameobject/SpineGameObject'); /** * @classdesc - * TODO + * The Spine Plugin is a Scene based plugin that handles the creation and rendering of Spine Game objects. + * + * 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 + * Spine files directly, i.e.: + * + * ```javascript + * this.load.spine('stretchyman', 'stretchyman-pro.json', [ 'stretchyman-pma.atlas' ], true); + * ``` + * + * It also installs a Game Object Factory method, allowin you to create Spine Game Objects: + * + * ```javascript + * this.add.spine(512, 650, 'stretchyman') + * ``` + * + * The first argument is the key which you used when importing the Spine data. There are lots of + * things you can specify, such as the animation name, skeleton, slot attachments and more. Please + * see the respective documentation and examples for further details. + * + * 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 + * stored in their own caches, which are global, meaning they're accessible from any Scene in your + * game, regardless if the Scene loaded the Spine data or not. * * @class SpinePlugin + * @memberOf Phaser * @extends Phaser.Plugins.ScenePlugin * @constructor * @since 3.19.0 @@ -37,27 +63,149 @@ var SpinePlugin = new Class({ var game = pluginManager.game; + /** + * A read-only flag that indicates if the game is running under WebGL or Canvas. + * + * @name SpinePlugin#isWebGL + * @type {boolean} + * @readonly + * @since 3.19.0 + */ this.isWebGL = (game.config.renderType === 2); - // Create a custom cache to store the spine data (.atlas files) + /** + * A custom cache that stores the Spine atlas data. + * + * This cache is global across your game, allowing you to access Spine data loaded from other Scenes, + * no matter which Scene you are in. + * + * @name SpinePlugin#cache + * @type {Phaser.Cache.BaseCache} + * @since 3.19.0 + */ this.cache = game.cache.addCustom('spine'); + /** + * A custom cache that stores the Spine Textures. + * + * This cache is global across your game, allowing you to access Spine data loaded from other Scenes, + * no matter which Scene you are in. + * + * @name SpinePlugin#spineTextures + * @type {Phaser.Cache.BaseCache} + * @since 3.19.0 + */ this.spineTextures = game.cache.addCustom('spineTextures'); + /** + * A reference to the global JSON Cache. + * + * @name SpinePlugin#json + * @type {Phaser.Cache.BaseCache} + * @since 3.19.0 + */ this.json = game.cache.json; + /** + * A reference to the global Texture Manager. + * + * @name SpinePlugin#textures + * @type {Phaser.Textures.TextureManager} + * @since 3.19.0 + */ this.textures = game.textures; + /** + * A flag that sets if the Skeleton Renderers will render debug information over the top + * of the skeleton or not. + * + * @name SpinePlugin#drawDebug + * @type {boolean} + * @since 3.19.0 + */ this.drawDebug = false; + /** + * The underlying WebGL context of the Phaser renderer. + * + * Only set if running in WebGL mode. + * + * @name SpinePlugin#gl + * @type {WebGLRenderingContext} + * @since 3.19.0 + */ this.gl; + + /** + * A reference to either the Canvas or WebGL Renderer that this Game is using. + * + * @name SpinePlugin#renderer + * @type {(Phaser.Renderer.Canvas.CanvasRenderer|Phaser.Renderer.WebGL.WebGLRenderer)} + * @since 3.19.0 + */ this.renderer; + + /** + * An instance of the Spine WebGL Scene Renderer. + * + * Only set if running in WebGL mode. + * + * @name SpinePlugin#sceneRenderer + * @type {spine.webgl.SceneRenderer} + * @since 3.19.0 + */ this.sceneRenderer; + + /** + * An instance of the Spine Skeleton Renderer. + * + * @name SpinePlugin#skeletonRenderer + * @type {(spine.canvas.SkeletonRenderer|spine.webgl.SkeletonRenderer)} + * @since 3.19.0 + */ this.skeletonRenderer; + + /** + * An instance of the Spine Skeleton Debug Renderer. + * + * Only set if running in WebGL mode. + * + * @name SpinePlugin#skeletonDebugRenderer + * @type {spine.webgl.skeletonDebugRenderer} + * @since 3.19.0 + */ this.skeletonDebugRenderer; + /** + * A reference to the Spine runtime. + * This is the runtime created by Esoteric Software + * + * @name SpinePlugin#plugin + * @type {spine} + * @since 3.19.0 + */ this.plugin = Spine; + /** + * An internal vector3 used by the screen to world method. + * + * @name SpinePlugin#temp1 + * @private + * @type {spine.webgl.Vector3} + * @since 3.19.0 + */ + this.temp1; + + /** + * An internal vector3 used by the screen to world method. + * + * @name SpinePlugin#temp2 + * @private + * @type {spine.webgl.Vector3} + * @since 3.19.0 + */ + this.temp2; + if (this.isWebGL) { this.runtime = Spine.webgl; @@ -76,14 +224,18 @@ var SpinePlugin = new Class({ this.getAtlas = this.getAtlasCanvas; } - this.temp1; - this.temp2; - pluginManager.registerFileType('spine', this.spineFileCallback, scene); pluginManager.registerGameObject('spine', this.add.bind(this), this.make.bind(this)); }, + /** + * Internal boot handler. + * + * @method SpinePlugin#boot + * @private + * @since 3.19.0 + */ boot: function () { if (this.isWebGL) @@ -103,11 +255,69 @@ var SpinePlugin = new Class({ eventEmitter.once('destroy', this.destroy, this); }, + /** + * Internal boot handler for the Canvas Renderer. + * + * @method SpinePlugin#bootCanvas + * @private + * @since 3.19.0 + */ bootCanvas: function () { this.skeletonRenderer = new Spine.canvas.SkeletonRenderer(this.scene.sys.context); }, + /** + * Internal boot handler for the WebGL Renderer. + * + * @method SpinePlugin#bootWebGL + * @private + * @since 3.19.0 + */ + bootWebGL: function () + { + this.sceneRenderer = new Spine.webgl.SceneRenderer(this.renderer.canvas, this.gl, true); + + // Monkeypatch the Spine setBlendMode functions, or batching is destroyed + + var setBlendMode = function (srcBlend, dstBlend) + { + if (srcBlend !== this.srcBlend || dstBlend !== this.dstBlend) + { + var gl = this.context.gl; + + this.srcBlend = srcBlend; + this.dstBlend = dstBlend; + + if (this.isDrawing) + { + this.flush(); + gl.blendFunc(this.srcBlend, this.dstBlend); + } + } + }; + + this.sceneRenderer.batcher.setBlendMode = setBlendMode; + this.sceneRenderer.shapes.setBlendMode = setBlendMode; + + this.skeletonRenderer = this.sceneRenderer.skeletonRenderer; + this.skeletonDebugRenderer = this.sceneRenderer.skeletonDebugRenderer; + + this.temp1 = new Spine.webgl.Vector3(0, 0, 0); + this.temp2 = new Spine.webgl.Vector3(0, 0, 0); + }, + + /** + * Gets a loaded Spine Atlas from the cache and creates a new Spine Texture Atlas, + * then returns it. You do not normally need to invoke this method directly. + * + * @method SpinePlugin#getAtlasCanvas + * @since 3.19.0 + * + * @param {string} key - The key of the Spine Atlas to create. + * + * @return {spine.TextureAtlas} The Spine Texture Atlas, or undefined if the given key wasn't found. + */ getAtlasCanvas: function (key) { var atlasEntry = this.cache.get(key); @@ -145,68 +355,17 @@ var SpinePlugin = new Class({ return atlas; }, - bootWebGL: function () - { - this.sceneRenderer = new Spine.webgl.SceneRenderer(this.renderer.canvas, this.gl, true); - - // Monkeypatch the Spine setBlendMode functions, or batching is destroyed - - var setBlendMode = function (srcBlend, dstBlend) - { - if (srcBlend !== this.srcBlend || dstBlend !== this.dstBlend) - { - var gl = this.context.gl; - - this.srcBlend = srcBlend; - this.dstBlend = dstBlend; - - if (this.isDrawing) - { - this.flush(); - gl.blendFunc(this.srcBlend, this.dstBlend); - } - } - }; - - this.sceneRenderer.batcher.setBlendMode = setBlendMode; - this.sceneRenderer.shapes.setBlendMode = setBlendMode; - - this.skeletonRenderer = this.sceneRenderer.skeletonRenderer; - this.skeletonDebugRenderer = this.sceneRenderer.skeletonDebugRenderer; - - this.temp1 = new Spine.webgl.Vector3(0, 0, 0); - this.temp2 = new Spine.webgl.Vector3(0, 0, 0); - }, - - worldToLocal: function (x, y, skeleton, bone) - { - var temp1 = this.temp1; - var temp2 = this.temp2; - var camera = this.sceneRenderer.camera; - - temp1.set(x + skeleton.x, y - skeleton.y, 0); - - var width = camera.viewportWidth; - var height = camera.viewportHeight; - - camera.screenToWorld(temp1, width, height); - - if (bone && bone.parent !== null) - { - bone.parent.worldToLocal(temp2.set(temp1.x - skeleton.x, temp1.y - skeleton.y, 0)); - - return new Spine.Vector2(temp2.x, temp2.y); - } - else if (bone) - { - return new Spine.Vector2(temp1.x - skeleton.x, temp1.y - skeleton.y); - } - else - { - return new Spine.Vector2(temp1.x, temp1.y); - } - }, - + /** + * Gets a loaded Spine Atlas from the cache and creates a new Spine Texture Atlas, + * then returns it. You do not normally need to invoke this method directly. + * + * @method SpinePlugin#getAtlasWebGL + * @since 3.19.0 + * + * @param {string} key - The key of the Spine Atlas to create. + * + * @return {spine.TextureAtlas} The Spine Texture Atlas, or undefined if the given key wasn't found. + */ getAtlasWebGL: function (key) { var atlasEntry = this.cache.get(key); @@ -248,95 +407,111 @@ var SpinePlugin = new Class({ return atlas; }, - getVector2: function (x, y) - { - return new Spine.Vector2(x, y); - }, - - getVector3: function (x, y, z) - { - return new Spine.webgl.Vector3(x, y, z); - }, - - setDebugBones: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawBones = value; - - return this; - }, - - setDebugRegionAttachments: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawRegionAttachments = value; - - return this; - }, - - setDebugBoundingBoxes: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawBoundingBoxes = value; - - return this; - }, - - setDebugMeshHull: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawMeshHull = value; - - return this; - }, - - setDebugMeshTriangles: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawMeshTriangles = value; - - return this; - }, - - setDebugPaths: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawPaths = value; - - return this; - }, - - setDebugSkeletonXY: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawSkeletonXY = value; - - return this; - }, - - setDebugClipping: function (value) - { - if (value === undefined) { value = true; } - - this.skeletonDebugRenderer.drawClipping = value; - - return this; - }, - - setEffect: function (effect) - { - this.sceneRenderer.skeletonRenderer.vertexEffect = effect; - - return this; - }, - + /** + * Adds a JSON based Texture Atlas, or array of atlases, 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'); + * } + * ``` + * + * The file is **not** loaded right away. It is added to a queue ready to be loaded either when the loader starts, + * or if it's already running, when the next free load slot becomes available. This happens automatically if you + * are calling this from within the Scene's `preload` method, or a related callback. Because the file is queued + * it means you cannot use the file immediately after calling this method, but must wait for the file to complete. + * The typical flow for a Phaser Scene is that you load assets in the Scene's `preload` method and then when the + * Scene's `create` method is called you are guaranteed that all of those assets are ready for use and have been + * loaded. + * + * 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. + * + * Instead of passing arguments you can pass a configuration object, such as: + * + * ```javascript + * this.load.atlas({ + * key: 'mainmenu', + * textureURL: 'images/MainMenu.png', + * atlasURL: 'images/MainMenu.json' + * }); + * ``` + * + * 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: + * + * ```javascript + * this.load.atlas('mainmenu', 'images/MainMenu.png', 'images/MainMenu.json'); + * // and later in your game ... + * this.add.image(x, y, 'mainmenu', 'background'); + * ``` + * + * To get a list of all available frames within an atlas please consult your Texture Atlas software. + * + * 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. + * + * 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 + * 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. + * + * @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 `.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 `.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. + * + * @return {Phaser.Loader.LoaderPlugin} The Loader instance. + */ spineFileCallback: function (key, jsonURL, atlasURL, preMultipliedAlpha, jsonXhrSettings, atlasXhrSettings) { var multifile; @@ -362,16 +537,21 @@ var SpinePlugin = new Class({ /** * Creates a new Spine Game Object and adds it to the Scene. + * + * 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. * - * @method Phaser.GameObjects.GameObjectFactory#add + * @method SpinePlugin#add * @since 3.19.0 * - * @param {number} x - The horizontal position of this Game Object. - * @param {number} y - The vertical position of this Game Object. - * @param {string} texture - The key of the Texture this Game Object will use to render with, as stored in the Texture Manager. - * @param {(string|integer)} [frame] - An optional frame from the Texture this Game Object is rendering with. + * @param {number} x - The horizontal position of this Game Object in the world. + * @param {number} y - The vertical position of this Game Object in the world. + * @param {string} [key] - The key of the Spine Skeleton this Game Object will use, as stored in the Spine Plugin. + * @param {string} [animationName] - The name of the animation to set on this Skeleton. + * @param {boolean} [loop=false] - Should the animation playback be looped or not? * - * @return {Phaser.GameObjects.Spine} The Game Object that was created. + * @return {SpineGameObject} The Game Object that was created. */ add: function (x, y, key, animationName, loop) { @@ -384,17 +564,19 @@ var SpinePlugin = new Class({ }, /** - * Creates a new Image Game Object and returns it. + * Creates a new Spine Game Object from the given configuration file and optionally adds it to the Scene. + * + * 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. * - * Note: This method will only be available if the Image Game Object has been built into Phaser. + * @method SpinePlugin#make + * @since 3.19.0 * - * @method Phaser.GameObjects.GameObjectCreator#image - * @since 3.0.0 - * - * @param {object} config - The configuration object this Game Object will use to create itself. + * @param {any} config - The configuration object this Game Object will use to create itself. * @param {boolean} [addToScene] - Add this Game Object to the Scene after creating it? If set this argument overrides the `add` property in the config object. * - * @return {Phaser.GameObjects.Image} The Game Object that was created. + * @return {SpineGameObject} The Game Object that was created. */ make: function (config, addToScene) { @@ -432,11 +614,285 @@ var SpinePlugin = new Class({ return spineGO.refresh(); }, - getRuntime: function () + /** + * Converts the given x and y screen coordinates into the world space of the given Skeleton. + * + * Only works in WebGL. + * + * @method SpinePlugin#worldToLocal + * @since 3.19.0 + * + * @param {number} x - The screen space x coordinate to convert. + * @param {number} y - The screen space y coordinate to convert. + * @param {spine.Skeleton} skeleton - The Spine Skeleton to convert into. + * @param {spine.Bone} [bone] - Optional bone of the Skeleton to convert into. + * + * @return {spine.Vector2} A Vector2 containing the translated point. + */ + worldToLocal: function (x, y, skeleton, bone) { - return this.runtime; + var temp1 = this.temp1; + var temp2 = this.temp2; + var camera = this.sceneRenderer.camera; + + temp1.set(x + skeleton.x, y - skeleton.y, 0); + + var width = camera.viewportWidth; + var height = camera.viewportHeight; + + camera.screenToWorld(temp1, width, height); + + if (bone && bone.parent !== null) + { + bone.parent.worldToLocal(temp2.set(temp1.x - skeleton.x, temp1.y - skeleton.y, 0)); + + return new Spine.Vector2(temp2.x, temp2.y); + } + else if (bone) + { + return new Spine.Vector2(temp1.x - skeleton.x, temp1.y - skeleton.y); + } + else + { + return new Spine.Vector2(temp1.x, temp1.y); + } }, + /** + * Returns a Spine Vector2 based on the given x and y values. + * + * @method SpinePlugin#getVector2 + * @since 3.19.0 + * + * @param {number} x - The Vector x value. + * @param {number} y - The Vector y value. + * + * @return {spine.Vector2} A Spine Vector2 based on the given values. + */ + getVector2: function (x, y) + { + return new Spine.Vector2(x, y); + }, + + /** + * Returns a Spine Vector2 based on the given x, y and z values. + * + * Only works in WebGL. + * + * @method SpinePlugin#getVector3 + * @since 3.19.0 + * + * @param {number} x - The Vector x value. + * @param {number} y - The Vector y value. + * @param {number} z - The Vector z value. + * + * @return {spine.Vector2} A Spine Vector2 based on the given values. + */ + getVector3: function (x, y, z) + { + return new Spine.webgl.Vector3(x, y, z); + }, + + /** + * Sets `drawBones` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugBones + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugBones: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawBones = value; + + return this; + }, + + /** + * Sets `drawRegionAttachments` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugRegionAttachments + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugRegionAttachments: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawRegionAttachments = value; + + return this; + }, + + /** + * Sets `drawBoundingBoxes` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugBoundingBoxes + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugBoundingBoxes: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawBoundingBoxes = value; + + return this; + }, + + /** + * Sets `drawMeshHull` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugMeshHull + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugMeshHull: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawMeshHull = value; + + return this; + }, + + /** + * Sets `drawMeshTriangles` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugMeshTriangles + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugMeshTriangles: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawMeshTriangles = value; + + return this; + }, + + /** + * Sets `drawPaths` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugPaths + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugPaths: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawPaths = value; + + return this; + }, + + /** + * Sets `drawSkeletonXY` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugSkeletonXY + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugSkeletonXY: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawSkeletonXY = value; + + return this; + }, + + /** + * Sets `drawClipping` in the Spine Skeleton Debug Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setDebugClipping + * @since 3.19.0 + * + * @param {boolean} [value=true] - The value to set in the debug property. + * + * @return {this} This Spine Plugin. + */ + setDebugClipping: function (value) + { + if (value === undefined) { value = true; } + + this.skeletonDebugRenderer.drawClipping = value; + + return this; + }, + + /** + * Sets the given vertex effect on the Spine Skeleton Renderer. + * + * Only works in WebGL. + * + * @method SpinePlugin#setEffect + * @since 3.19.0 + * + * @param {spine.VertexEffect} [effect] - The vertex effect to set on the Skeleton Renderer. + * + * @return {this} This Spine Plugin. + */ + setEffect: function (effect) + { + this.sceneRenderer.skeletonRenderer.vertexEffect = effect; + + return this; + }, + + /** + * Creates a Spine Skeleton based on the given key and optional Skeleton JSON data. + * + * The Skeleton data should have already been loaded before calling this method. + * + * @method SpinePlugin#createSkeleton + * @since 3.19.0 + * + * @param {string} key - The key of the Spine skeleton data, as loaded by the plugin. If the Spine JSON contains multiple skeletons, reference them with a period, i.e. `set.spineBoy`. + * @param {object} [skeletonJSON] - Optional Skeleton JSON data to use, instead of getting it from the cache. + * + * @return {(any|null)} This Spine Skeleton data object, or `null` if the key was invalid. + */ createSkeleton: function (key, skeletonJSON) { var atlasKey = key; @@ -492,6 +948,42 @@ var SpinePlugin = new Class({ } }, + /** + * Creates a new Animation State and Animation State Data for the given skeleton. + * + * The returned object contains two properties: `state` and `stateData` respectively. + * + * @method SpinePlugin#createAnimationState + * @since 3.19.0 + * + * @param {spine.Skeleton} skeleton - The Skeleton to create the Animation State for. + * + * @return {any} An object containing the Animation State and Animation State Data instances. + */ + createAnimationState: function (skeleton) + { + var stateData = new Spine.AnimationStateData(skeleton.data); + + var state = new Spine.AnimationState(stateData); + + return { stateData: stateData, state: state }; + }, + + /** + * Returns the axis aligned bounding box (AABB) of the region and mesh attachments for the current pose. + * + * The returned object contains two properties: `offset` and `size`: + * + * `offset` - The distance from the skeleton origin to the bottom left corner of the AABB. + * `size` - The width and height of the AABB. + * + * @method SpinePlugin#getBounds + * @since 3.19.0 + * + * @param {spine.Skeleton} skeleton - The Skeleton to get the bounds from. + * + * @return {any} The bounds object. + */ getBounds: function (skeleton) { var offset = new Spine.Vector2(); @@ -502,15 +994,14 @@ var SpinePlugin = new Class({ return { offset: offset, size: size }; }, - createAnimationState: function (skeleton) - { - var stateData = new Spine.AnimationStateData(skeleton.data); - - var state = new Spine.AnimationState(stateData); - - return { stateData: stateData, state: state }; - }, - + /** + * Internal handler for when the renderer resizes. + * + * Only called if running in WebGL. + * + * @method SpinePlugin#onResize + * @since 3.19.0 + */ onResize: function () { var renderer = this.renderer; @@ -528,11 +1019,12 @@ var SpinePlugin = new Class({ /** * The Scene that owns this plugin is shutting down. + * * We need to kill and reset all internal properties as well as stop listening to Scene events. * - * @method Camera3DPlugin#shutdown + * @method SpinePlugin#shutdown * @private - * @since 3.0.0 + * @since 3.19.0 */ shutdown: function () { @@ -545,11 +1037,12 @@ var SpinePlugin = new Class({ /** * The Scene that owns this plugin is being destroyed. + * * We need to shutdown and then kill off all external references. * - * @method Camera3DPlugin#destroy + * @method SpinePlugin#destroy * @private - * @since 3.0.0 + * @since 3.19.0 */ destroy: function () { diff --git a/plugins/spine/src/gameobject/SpineGameObject.js b/plugins/spine/src/gameobject/SpineGameObject.js index 21c715727..457e112b6 100644 --- a/plugins/spine/src/gameobject/SpineGameObject.js +++ b/plugins/spine/src/gameobject/SpineGameObject.js @@ -1,24 +1,24 @@ /** * @author Richard Davey - * @copyright 2018 Photon Storm Ltd. + * @copyright 2019 Photon Storm Ltd. * @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License} */ -var Class = require('../../../../src/utils/Class'); +var AngleBetween = require('../../../../src/math/angle/Between'); var Clamp = require('../../../../src/math/Clamp'); +var Class = require('../../../../src/utils/Class'); var ComponentsComputedSize = require('../../../../src/gameobjects/components/ComputedSize'); var ComponentsDepth = require('../../../../src/gameobjects/components/Depth'); var ComponentsFlip = require('../../../../src/gameobjects/components/Flip'); var ComponentsScrollFactor = require('../../../../src/gameobjects/components/ScrollFactor'); var ComponentsTransform = require('../../../../src/gameobjects/components/Transform'); var ComponentsVisible = require('../../../../src/gameobjects/components/Visible'); -var SpineEvents = require('../events/'); -var GameObject = require('../../../../src/gameobjects/GameObject'); -var SpineGameObjectRender = require('./SpineGameObjectRender'); -var AngleBetween = require('../../../../src/math/angle/Between'); var CounterClockwise = require('../../../../src/math/angle/CounterClockwise'); var DegToRad = require('../../../../src/math/DegToRad'); +var GameObject = require('../../../../src/gameobjects/GameObject'); var RadToDeg = require('../../../../src/math/RadToDeg'); +var SpineEvents = require('../events/'); +var SpineGameObjectRender = require('./SpineGameObjectRender'); /** * @classdesc @@ -26,10 +26,15 @@ var RadToDeg = require('../../../../src/math/RadToDeg'); * * @class SpineGameObject * @constructor - * @since 3.16.0 + * @since 3.19.0 * - * @param {Phaser.Scene} scene - A reference to the Scene that has installed this plugin. - * @param {Phaser.Plugins.PluginManager} pluginManager - A reference to the Phaser Plugin Manager. + * @param {Phaser.Scene} scene - A reference to the Scene that this Game Object belongs to. + * @param {SpinePlugin} pluginManager - A reference to the Phaser Spine Plugin. + * @param {number} x - The horizontal position of this Game Object in the world. + * @param {number} y - The vertical position of this Game Object in the world. + * @param {string} [key] - The key of the Spine Skeleton this Game Object will use, as stored in the Spine Plugin. + * @param {string} [animationName] - The name of the animation to set on this Skeleton. + * @param {boolean} [loop=false] - Should the animation playback be looped or not? */ var SpineGameObject = new Class({ diff --git a/plugins/spine/src/gameobject/SpineGameObjectCanvasRenderer.js b/plugins/spine/src/gameobject/SpineGameObjectCanvasRenderer.js index 6e6d31673..567643042 100644 --- a/plugins/spine/src/gameobject/SpineGameObjectCanvasRenderer.js +++ b/plugins/spine/src/gameobject/SpineGameObjectCanvasRenderer.js @@ -1,6 +1,6 @@ /** * @author Richard Davey - * @copyright 2018 Photon Storm Ltd. + * @copyright 2019 Photon Storm Ltd. * @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License} */ @@ -13,12 +13,12 @@ var Wrap = require('../../../../src/math/Wrap'); * The object will not render if any of its renderFlags are set or it is being actively filtered out by the Camera. * This method should not be called directly. It is a utility function of the Render module. * - * @method Phaser.GameObjects.SpineGameObject#renderCanvas - * @since 3.16.0 + * @method SpineGameObject#renderCanvas + * @since 3.19.0 * @private * * @param {Phaser.Renderer.Canvas.CanvasRenderer} renderer - A reference to the current active Canvas renderer. - * @param {Phaser.GameObjects.SpineGameObject} src - The Game Object being rendered in this call. + * @param {SpineGameObject} src - The Game Object being rendered in this call. * @param {number} interpolationPercentage - Reserved for future use and custom pipelines. * @param {Phaser.Cameras.Scene2D.Camera} camera - The Camera that is rendering the Game Object. * @param {Phaser.GameObjects.Components.TransformMatrix} parentMatrix - This transform matrix is defined if the game object is nested diff --git a/plugins/spine/src/gameobject/SpineGameObjectRender.js b/plugins/spine/src/gameobject/SpineGameObjectRender.js index d355e60cb..8ec1766f5 100644 --- a/plugins/spine/src/gameobject/SpineGameObjectRender.js +++ b/plugins/spine/src/gameobject/SpineGameObjectRender.js @@ -1,6 +1,6 @@ /** * @author Richard Davey - * @copyright 2018 Photon Storm Ltd. + * @copyright 2019 Photon Storm Ltd. * @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License} */ diff --git a/plugins/spine/src/gameobject/SpineGameObjectWebGLRenderer.js b/plugins/spine/src/gameobject/SpineGameObjectWebGLRenderer.js index 2cc729c06..949c39139 100644 --- a/plugins/spine/src/gameobject/SpineGameObjectWebGLRenderer.js +++ b/plugins/spine/src/gameobject/SpineGameObjectWebGLRenderer.js @@ -1,6 +1,6 @@ /** * @author Richard Davey - * @copyright 2018 Photon Storm Ltd. + * @copyright 2019 Photon Storm Ltd. * @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License} */ @@ -13,7 +13,7 @@ var Wrap = require('../../../../src/math/Wrap'); * The object will not render if any of its renderFlags are set or it is being actively filtered out by the Camera. * This method should not be called directly. It is a utility function of the Render module. * - * @method Phaser.GameObjects.SpineGameObject#renderWebGL + * @method SpineGameObject#renderWebGL * @since 3.19.0 * @private *