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

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:
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:
Since: 3.8.0
Inherited From:
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:
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:
Since: 3.8.0
Inherited From:
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:
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:
Since: 3.8.0
Inherited From:
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:
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:
Since: 3.8.0
Inherited From:
Source: src/plugins/ScenePlugin.js (Line 49)

textures :Phaser.Textures.TextureManager

A reference to the global Texture Manager.

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

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