Class: SpinePlugin

SpinePlugin

The Spine Plugin is a Scene based plugin that handles the creation and rendering of Spine Game Objects.

Find more details about Spine itself at http://esotericsoftware.com/.

All rendering and object creation is handled via the official Spine Runtimes. This version of the plugin uses the Spine 3.8.95 runtimes. Please note that due to the way the Spine runtimes use semver, you will get breaking changes in point-releases. Therefore, files created in a different version of Spine may not work as a result, without you first updating the runtimes and rebuilding the plugin.

Esoteric themselves recommend that you freeze your Spine editor version against the runtime versions. You can find more information about this here: http://esotericsoftware.com/spine-settings#Version

Please note that you require a Spine license in order to use Spine Runtimes in your games.

You can install this plugin into your Phaser game by either importing it, if you're using ES6:

import * as SpinePlugin from './SpinePlugin.js';

and then adding it to your Phaser Game configuration:

plugins: {
    scene: [
        { key: 'SpinePlugin', plugin: window.SpinePlugin, mapping: 'spine' }
    ]
}

If you're using ES5 then you can load the Spine Plugin in a Scene files payload, within your Game Configuration object, like this:

scene: {
    preload: preload,
    create: create,
    pack: {
        files: [
            { type: 'scenePlugin', key: 'SpinePlugin', url: 'plugins/SpinePlugin.js', sceneKey: 'spine' }
        ]
    }
}

Loading it like this allows you to then use commands such as this.load.spine from within the same Scene. Alternatively, you can use the method this.load.plugin to load the plugin via the normal Phaser Loader. However, doing so will not add it to the current Scene. It will be available from any subsequent Scenes.

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.:

this.load.spine('stretchyman', 'stretchyman-pro.json', [ 'stretchyman-pma.atlas' ], true);

It also installs two Game Object Factory methods, allowing you to create Spine Game Objects and Spine Containers:

const man = this.add.spine(512, 650, 'stretchyman');

const container = this.add.spineContainer();

container.add(man);

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.

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 preMultipliedAlpha 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 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.

When destroying a Phaser Game instance, if you need to re-create it again on the same page without reloading, you must remember to remove the Spine Plugin as part of your tear-down process:

this.plugins.removeScenePlugin('SpinePlugin');

For details about the Spine Runtime API see http://esotericsoftware.com/spine-api-reference

new SpinePlugin(scene, pluginManager)

Parameters:

Name	Type	Description
`scene`	Phaser.Scene	A reference to the Scene that has installed this plugin.
`pluginManager`	Phaser.Plugins.PluginManager	A reference to the Phaser Plugin Manager.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 21)

Extends

Phaser.Plugins.ScenePlugin

Members

cache :Phaser.Cache.BaseCache

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.

Type:

Phaser.Cache.BaseCache

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 147)

drawDebug :boolean

A flag that sets if the Skeleton Renderers will render debug information over the top of the skeleton or not.

Type:

boolean

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 189)

<protected> game :Phaser.Game

A reference to the Game instance this plugin is running under.

Type:

Phaser.Game

Since: 3.8.0

Inherited From:

Phaser.Plugins.BasePlugin#game

Source: src/plugins/BasePlugin.js (Line 38)

gl :WebGLRenderingContext

The underlying WebGL context of the Phaser renderer.

Only set if running in WebGL mode.

Type:

WebGLRenderingContext

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 199)

<readonly> isWebGL :boolean

A read-only flag that indicates if the game is running under WebGL or Canvas.

Type:

boolean

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 137)

json :Phaser.Cache.BaseCache

A reference to the global JSON Cache.

Type:

Phaser.Cache.BaseCache

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 171)

plugin :spine

A reference to the Spine runtime. This is the runtime created by Esoteric Software.

Type:

spine

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 252)

<protected> pluginManager :Phaser.Plugins.PluginManager

A handy reference to the Plugin Manager that is responsible for this plugin. Can be used as a route to gain access to game systems and events.

Type:

Phaser.Plugins.PluginManager

Since: 3.8.0

Inherited From:

Phaser.Plugins.BasePlugin#pluginManager

Source: src/plugins/BasePlugin.js (Line 27)

renderer :Phaser.Renderer.Canvas.CanvasRenderer|Phaser.Renderer.WebGL.WebGLRenderer

A reference to either the Canvas or WebGL Renderer that this Game is using.

Type:

Phaser.Renderer.Canvas.CanvasRenderer | Phaser.Renderer.WebGL.WebGLRenderer

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 210)

<protected, nullable> scene :Phaser.Scene

A reference to the Scene that has installed this plugin. Only set if it's a Scene Plugin, otherwise null. This property is only set when the plugin is instantiated and added to the Scene, not before. You can use it during the boot method.

Type:

Phaser.Scene

Since: 3.8.0

Inherited From:

Phaser.Plugins.ScenePlugin#scene

Source: src/plugins/ScenePlugin.js (Line 36)

sceneRenderer :spine.webgl.SceneRenderer

An instance of the Spine WebGL Scene Renderer.

There is only one instance of the Scene Renderer shared across the whole plugin.

Only set if running in WebGL mode.

Type:

spine.webgl.SceneRenderer

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 219)

skeletonDebugRenderer :spine.webgl.skeletonDebugRenderer

An instance of the Spine Skeleton Debug Renderer.

Only set if running in WebGL mode.

Type:

spine.webgl.skeletonDebugRenderer

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 241)

skeletonRenderer :spine.canvas.SkeletonRenderer|spine.webgl.SkeletonRenderer

An instance of the Spine Skeleton Renderer.

Type:

spine.canvas.SkeletonRenderer | spine.webgl.SkeletonRenderer

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 232)

spineTextures :Phaser.Cache.BaseCache

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.

Type:

Phaser.Cache.BaseCache

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 159)

<protected, nullable> systems :Phaser.Scenes.Systems

A reference to the Scene Systems of the Scene that has installed this plugin. Only set if it's a Scene Plugin, otherwise null. This property is only set when the plugin is instantiated and added to the Scene, not before. You can use it during the boot method.

Type:

Phaser.Scenes.Systems

Since: 3.8.0

Inherited From:

Phaser.Plugins.ScenePlugin#systems

Source: src/plugins/ScenePlugin.js (Line 49)

textures :Phaser.Textures.TextureManager

A reference to the global Texture Manager.

Type:

Phaser.Textures.TextureManager

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 180)

Methods

add(x, y [, key] [, animationName] [, loop])

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.

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.

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.

Parameters:

Name	Type	Argument	Default	Description
`x`	number			The horizontal position of this Game Object in the world.
`y`	number			The vertical position of this Game Object in the world.
`key`	string	<optional>		The key of the Spine Skeleton this Game Object will use, as stored in the Spine Plugin.
`animationName`	string	<optional>		The name of the animation to set on this Skeleton.
`loop`	boolean	<optional>	false	Should the animation playback be looped or not?

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 1150)

Returns:

The Game Object that was created.

Type: SpineGameObject

createAnimationState(skeleton)

Creates a new Animation State and Animation State Data for the given skeleton.

The returned object contains two properties: state and stateData respectively.

Parameters:

Name	Type	Description
`skeleton`	spine.Skeleton	The Skeleton to create the Animation State for.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 1006)

Returns:

An object containing the Animation State and Animation State Data instances.

Type: any

createSkeleton(key [, skeletonJSON])

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.

Parameters:

Name	Type	Argument	Description
`key`	string		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`.
`skeletonJSON`	object	<optional>	Optional Skeleton JSON data to use, instead of getting it from the cache.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 933)

Returns:

This Spine Skeleton data object, or null if the key was invalid.

Type: any | null

getAtlasCanvas(key)

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.

Parameters:

Name	Type	Description
`key`	string	The key of the Spine Atlas to create.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 479)

Returns:

The Spine Texture Atlas, or undefined if the given key wasn't found.

Type: spine.TextureAtlas

getAtlasWebGL(key)

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.

Parameters:

Name	Type	Description
`key`	string	The key of the Spine Atlas to create.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 520)

Returns:

The Spine Texture Atlas, or undefined if the given key wasn't found.

Type: spine.TextureAtlas

getBounds(skeleton)

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.

Parameters:

Name	Type	Description
`skeleton`	spine.Skeleton	The Skeleton to get the bounds from.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 1027)

Returns:

The bounds object.

Type: any

getVector2(x, y)

Returns a Spine Vector2 based on the given x and y values.

Parameters:

Name	Type	Description
`x`	number	The Vector x value.
`y`	number	The Vector y value.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 711)

Returns:

A Spine Vector2 based on the given values.

Type: spine.Vector2

getVector3(x, y, z)

Returns a Spine Vector2 based on the given x, y and z values.

Only works in WebGL.

Parameters:

Name	Type	Description
`x`	number	The Vector x value.
`y`	number	The Vector y value.
`z`	number	The Vector z value.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 727)

Returns:

A Spine Vector2 based on the given values.

Type: spine.Vector2

init( [data])

The PluginManager calls this method on a Global Plugin when the plugin is first instantiated. It will never be called again on this instance. In here you can set-up whatever you need for this plugin to run. If a plugin is set to automatically start then BasePlugin.start will be called immediately after this. On a Scene Plugin, this method is never called. Use Phaser.Plugins.ScenePlugin#boot instead.

Parameters:

Name	Type	Argument	Description
`data`	any	<optional> <nullable>	A value specified by the user, if any, from the `data` property of the plugin's configuration object (if started at game boot) or passed in the PluginManager's `install` method (if started manually).

Since: 3.8.0

Inherited From:

Phaser.Plugins.BasePlugin#init

Source: src/plugins/BasePlugin.js (Line 49)

make(config [, addToScene])

Creates a new Spine Game Object from the given configuration file and optionally adds it to the Scene.

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'
});

Parameters:

Name	Type	Argument	Description
`config`	any		The configuration object this Game Object will use to create itself.
`addToScene`	boolean	<optional>	Add this Game Object to the Scene after creating it? If set this argument overrides the `add` property in the config object.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 1185)

Returns:

The Game Object that was created.

Type: SpineGameObject

onResize()

Internal handler for when the renderer resizes.

Only called if running in WebGL.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 1052)

setDebugBones( [value])

Sets drawBones in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 746)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugBoundingBoxes( [value])

Sets drawBoundingBoxes in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 788)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugClipping( [value])

Sets drawClipping in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 893)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugMeshHull( [value])

Sets drawMeshHull in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 809)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugMeshTriangles( [value])

Sets drawMeshTriangles in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 830)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugPaths( [value])

Sets drawPaths in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 851)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugRegionAttachments( [value])

Sets drawRegionAttachments in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 767)

Returns:

This Spine Plugin.

Type: SpinePlugin

setDebugSkeletonXY( [value])

Sets drawSkeletonXY in the Spine Skeleton Debug Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Default	Description
`value`	boolean	<optional>	true	The value to set in the debug property.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 872)

Returns:

This Spine Plugin.

Type: SpinePlugin

setEffect( [effect])

Sets the given vertex effect on the Spine Skeleton Renderer.

Only works in WebGL.

Parameters:

Name	Type	Argument	Description
`effect`	spine.VertexEffect	<optional>	The vertex effect to set on the Skeleton Renderer.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 914)

Returns:

This Spine Plugin.

Type: SpinePlugin

start()

The PluginManager calls this method on a Global Plugin when the plugin is started. If a plugin is stopped, and then started again, this will get called again. Typically called immediately after BasePlugin.init. On a Scene Plugin, this method is never called.

Since: 3.8.0

Inherited From:

Phaser.Plugins.BasePlugin#start

Source: src/plugins/BasePlugin.js (Line 65)

stop()

The PluginManager calls this method on a Global Plugin when the plugin is stopped. The game code has requested that your plugin stop doing whatever it does. It is now considered as 'inactive' by the PluginManager. Handle that process here (i.e. stop listening for events, etc) If the plugin is started again then BasePlugin.start will be called again. On a Scene Plugin, this method is never called.

Since: 3.8.0

Inherited From:

Phaser.Plugins.BasePlugin#stop

Source: src/plugins/BasePlugin.js (Line 92)

worldToLocal(x, y, skeleton [, bone])

Converts the given x and y screen coordinates into the world space of the given Skeleton.

Only works in WebGL.

Parameters:

Name	Type	Argument	Description
`x`	number		The screen space x coordinate to convert.
`y`	number		The screen space y coordinate to convert.
`skeleton`	spine.Skeleton		The Spine Skeleton to convert into.
`bone`	spine.Bone	<optional>	Optional bone of the Skeleton to convert into.

Since: 3.19.0
Source: plugins/spine/src/SpinePlugin.js (Line 667)

Returns:

A Vector2 containing the translated point.

Type: spine.Vector2