@melonjs/spine-plugin 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## 1.4.0 - 2023-09-xx
+## 1.5.0 - 2023-09-23
+
+- fix the `addAnimation()` method not returning the corresponding set TrackEntry
+- fix the base renderable `flip[X/Y]` method when used/applied to the Spine renderable
+- add a `isCurrentAnimation()` method that returns true if the given name is corresponding to the current track current animation
+- expose the `currentTrack` property to access the corresponding current animation track entry
+- clarify in the readme that the current plugin support both the 4.1 and 4.2-beta Spine runtime versions
+- the spine-plugin now requires to be properly registered using `me.plugin.register(SpinePlugin);`
+- the spine-plugin now requires melonJS v15.12.0 or higher
+- add check for minimum melonJS version when the plugin is registered
+- restructure code to adhere to the updated plugin API and get a proper reference to the melonjs renderer instance
+
+## 1.4.0 - 2023-09-05
 
 - add support for loading spine assets through the melonJS preloader (see README)
 - add inline documentation for the Spine class, properties and methods

package/README.md

@@ -1,6 +1,6 @@
 # melonJS Spine Plugin
 
-a [Spine](http://en.esotericsoftware.com/spine-in-depth) 4.1 plugin implementation for [melonJS 2](http://www.melonjs.org)
+a [Spine](http://en.esotericsoftware.com/spine-in-depth) 4.x plugin implementation for [melonJS 2](http://www.melonjs.org)
 
 ![melonjs-spine-gif](https://github.com/melonjs/spine-plugin/assets/4033090/dc259c8e-def6-419e-83a9-cda374715686)
 
@@ -11,10 +11,10 @@ a [Spine](http://en.esotericsoftware.com/spine-in-depth) 4.1 plugin implementati
 [![jsDeliver](https://data.jsdelivr.com/v1/package/npm/@melonjs/spine-plugin/badge?style=rounded)](https://www.jsdelivr.com/package/npm/@melonjs/spine-plugin)
 
 
-Installation
+## Installation
 -------------------------------------------------------------------------------
 this plugin is already bundled with the required Spine [4.x runtime](package.json#dependencies), so there is no need to install it separately.
->Note: this plugin requires melonJS version 15.10 or higher.
+>Note: this plugin requires melonJS version 15.12 or higher.
 
 To install the plugin using npm :
 
@@ -22,9 +22,12 @@ To install the plugin using npm :
 
 Then import and use the plugin in your project. For example:
 ```JavaScript
-import * as Spine from '@melonjs/spine-plugin';
+import { SpinePlugin } from '@melonjs/spine-plugin';
 import * as me from 'melonjs';
 
+// register the plugin
+me.plugin.register(SpinePlugin);
+
 // prepare/declare assets for the preloader
 const DataManifest = [
     {
@@ -37,22 +40,41 @@ const DataManifest = [
         "type": "spine",
         "src": "data/spine/alien.atlas"
     },
-]
+];
+
+// import default Spine class
+import Spine from '@melonjs/spine-plugin';
+
+// preload assets
+me.loader.preload(DataManifest, async function() {
 
-// create a new Spine Renderable
-let spineAlien = new Spine(100, 100, {atlasFile: "alien.atlas", jsonFile: "alien-ess.json"});
+    // create a new Spine Renderable
+    let spineAlien = new Spine(100, 100, {atlasFile: "alien.atlas", jsonFile: "alien-ess.json"});
 
-// set default animation
-spineAlien.setAnimation(0, "death", true);
+    // set default animation
+    spineAlien.setAnimation(0, "death", true);
 
-// add it to the game world
-me.game.world.addChild(spineAlien);
+    // add it to the game world
+    me.game.world.addChild(spineAlien);
+
+}
 ```
 >Note: use "spine" as a value for the `type` property to indicate which assets and are actual Spine assets and to be loaded using the plugin (requires version 1.4.0 or higher of the Spine plugin)
 
 for more details, see a complete usage example in the [test](test) folder
 
-Questions, need help ?
+## Compatibility
+-------------------------------------------------------------------------------
+
+below is the compatibility version matrix :
+
+| melonJS | @melonjs/spine-plugin | spine-runtime |
+|---|---|---|
+| v15.12.x (or higher) | v1.x | v4.1, v4.2-beta |
+
+>Note: the current version of the spine-plugin is bundled with the 4.2.x beta version of the Spine runtime, which is for now backward compatible with the Spine 4.1 runtime (from a player/rendering point of view). 
+
+## Questions, need help ?
 -------------------------------------------------------------------------------
 If you need technical support, you can contact us through the following channels :
 * Forums: with melonJS 2 we moved to a new discourse [forum](https://melonjs.discourse.group), but we can still also find the previous one [here](http://www.html5gamedevs.com/forum/32-melonjs/)

package/dist/@melonjs/spine-plugin.d.ts

@@ -1,7 +1,15 @@
-export let assetManager: AssetManager;
 /**
  * @classdesc
- * An object to display a Spine animated skeleton on screen.
+ * a Spine 4.x plugin implementation for melonJS
+ * @augments plugin.BasePlugin
+ */
+export class SpinePlugin extends plugin.BasePlugin {
+    constructor();
+    assetManager: AssetManager;
+}
+/**
+ * @classdesc
+ * An renderable object to render Spine animated skeleton.
  * @augments Renderable
  */
 declare class Spine extends Renderable {
@@ -240,7 +248,6 @@ declare class Spine extends Renderable {
         VertexAttachment: typeof VertexAttachment;
         VertexAttribute: typeof VertexAttribute;
         readonly VertexAttributeType: any;
-        WebGLBlendModeConverter: typeof WebGLBlendModeConverter;
         WindowedMean: typeof WindowedMean;
     } | {
         __proto__: null;
@@ -400,12 +407,36 @@ declare class Spine extends Renderable {
         WindowedMean: typeof WindowedMean;
     };
     skeleton: any;
+    plugin: plugin.BasePlugin;
+    renderer: any;
     animationState: any;
     skeletonRenderer: SkeletonRenderer;
-    assetManager: any;
     root: any;
     boneOffset: Vector2;
     boneSize: Vector2;
+    isSpineFlipped: {
+        x: boolean;
+        y: boolean;
+    };
+    /**
+     * Stores settings and other state for the playback of the current animation (if any).
+     * @type {TrackEntry}
+     * @see http://en.esotericsoftware.com/spine-api-reference#TrackEntry
+     * @see setAnimation
+     * @default undefined
+     * @example
+     * // set a default animation to "run"
+     * this.setAnimation(0, "run", true);
+     * ...
+     * ...
+     * // pause the animation
+     * this.currentTrack.timeScale = 0;
+     * ...
+     * ...
+     * // resume the animation
+     * this.currentTrack.timeScale = 1;
+     */
+    currentTrack: TrackEntry;
     mixTime: number;
     jsonFile: number | undefined;
     atlasFile: number | undefined;
@@ -435,7 +466,19 @@ declare class Spine extends Renderable {
      * me.game.world.addChild(spineAlien);
      */
     setSkeleton(atlasFile?: number | undefined, jsonFile?: number | undefined): void;
+    /**
+     * flip the Spine skeleton on the horizontal axis (around its center)
+     * @param {boolean} [flip=true] - `true` to flip this Spine object.
+     * @returns {Spine} Reference to this object for method chaining
+     */
+    flipX(flip?: boolean | undefined): Spine;
     isDirty: boolean | undefined;
+    /**
+     * flip the Spine skeleton on the vertical axis (around its center)
+     * @param {boolean} [flip=true] - `true` to flip this Spine object.
+     * @returns {Spine} Reference to this object for method chaining
+     */
+    flipY(flip?: boolean | undefined): Spine;
     /**
     * Rotate this Spine object by the specified angle (in radians).
     * @param {number} angle - The angle to rotate (in radians)
@@ -478,26 +521,37 @@ declare class Spine extends Renderable {
      * @param {number} [track_index] -  If the formerly current track entry was never applied to a skeleton, it is replaced (not mixed from). In either case trackEnd determines when the track is cleared.
      * @param {number} [index] - the animation index
      * @param {boolean} [loop= false] - If true, the animation will repeat. If false it will not, instead its last frame is applied if played beyond its duration.
-     * @returns A track entry to allow further customization of animation playback. References to the track entry must not be kept after the dispose event occurs.
+     * @returns {TrackEntry} A track entry to allow further customization of animation playback. References to the track entry must not be kept after the dispose event occurs.
      */
-    setAnimationByIndex(track_index?: number | undefined, index?: number | undefined, loop?: boolean | undefined): void;
+    setAnimationByIndex(track_index?: number | undefined, index?: number | undefined, loop?: boolean | undefined): TrackEntry;
     /**
      * Sets the current animation for a track, discarding any queued animations.
      * @param {number} [track_index] -  If the formerly current track entry was never applied to a skeleton, it is replaced (not mixed from). In either case trackEnd determines when the track is cleared.
      * @param {string} [name] - the animation name
      * @param {boolean} [loop= false] - If true, the animation will repeat. If false it will not, instead its last frame is applied if played beyond its duration.
-     * @returns A track entry to allow further customization of animation playback. References to the track entry must not be kept after the dispose event occurs.
+     * @returns {TrackEntry} A track entry to allow further customization of animation playback. References to the track entry must not be kept after the dispose event occurs.
      * @example
      * // set the current animation
      * spineAlien.setAnimation(0, "death", true);
      */
-    setAnimation(track_index?: number | undefined, name?: string | undefined, loop?: boolean | undefined): void;
+    setAnimation(track_index?: number | undefined, name?: string | undefined, loop?: boolean | undefined): TrackEntry;
+    /**
+     * return true if the given animation name is the current running animation for the current track.
+     * @name isCurrentAnimation
+     * @param {string} name - animation name
+     * @returns {boolean}
+     * @example
+     * if (!this.isCurrentAnimation("death")) {
+     *     // do something funny...
+     * }
+     */
+    isCurrentAnimation(name: string): boolean;
     /**
      * Adds an animation to be played after the current or last queued animation for a track, and sets the track entry's mixDuration.
      * @param {number} [delay=0] - If > 0, sets delay. If <= 0, the delay set is the duration of the previous track entry minus any mix duration plus the specified `delay` (ie the mix ends at (`delay` = 0) or before (`delay` < 0) the previous track entry duration). If the previous entry is looping, its next loop completion is used instead of its duration.
-     * @return A track entry to allow further customization of animation playback. References to the track entry must not be kept after the dispose} event occurs.
+     * @return {TrackEntry} A track entry to allow further customization of animation playback. References to the track entry must not be kept after the dispose} event occurs.
      */
-    addAnimationByIndex(track_index: any, index: any, loop?: boolean, delay?: number | undefined): void;
+    addAnimationByIndex(track_index: any, index: any, loop?: boolean, delay?: number | undefined): TrackEntry;
     addAnimationByName(track_index: any, animationName: any, loop?: boolean, delay?: number): void;
     getSpinePosition(): Vector2d;
     setSpineSize(width: any, height: any): void;
@@ -534,21 +588,79 @@ declare class Spine extends Renderable {
      */
     setSkinByName(skinName: string): void;
     /**
-     * Sets this slot to the setup pose.
+     * Reset this slot to the setup pose.
      */
     setToSetupPose(): void;
 }
+import { plugin } from 'melonjs';
 /**
  * @classdesc
  * An Asset Manager class to load spine assets
  */
 declare class AssetManager {
     /**
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a melonJS renderer instance
      * @param {string} [pathPrefix=""] - a default path prefix for assets location
      */
-    constructor(pathPrefix?: string | undefined);
-    asset_manager: any;
-    pathPrefix: any;
+    constructor(renderer: CanvasRenderer | WebGLRenderer, pathPrefix?: string | undefined);
+    asset_manager: {
+        pathPrefix: string;
+        assets: {};
+        errors: {};
+        toLoad: number;
+        loaded: number;
+        textureLoader: any;
+        downloader: Downloader;
+        start(path: any): string;
+        success(callback: any, path: any, asset: any): void;
+        error(callback: any, path: any, message: any): void;
+        loadAll(): Promise<any>;
+        setRawDataURI(path: any, data: any): void;
+        loadBinary(path: any, success?: () => void, error?: () => void): void;
+        loadText(path: any, success?: () => void, error?: () => void): void;
+        loadJson(path: any, success?: () => void, error?: () => void): void;
+        loadTexture(path: any, success?: () => void, error?: () => void): void;
+        loadTextureAtlas(path: any, success: (() => void) | undefined, error: (() => void) | undefined, fileAlias: any): void;
+        get(path: any): any;
+        require(path: any): any;
+        remove(path: any): any;
+        removeAll(): void;
+        isLoadingComplete(): boolean;
+        getToLoad(): number;
+        getLoaded(): number;
+        dispose(): void;
+        hasErrors(): boolean;
+        getErrors(): {};
+    } | {
+        pathPrefix: string;
+        assets: {};
+        errors: {};
+        toLoad: number;
+        loaded: number;
+        textureLoader: any;
+        downloader: Downloader;
+        start(path: any): string;
+        success(callback: any, path: any, asset: any): void;
+        error(callback: any, path: any, message: any): void;
+        loadAll(): Promise<any>;
+        setRawDataURI(path: any, data: any): void;
+        loadBinary(path: any, success?: () => void, error?: () => void): void;
+        loadText(path: any, success?: () => void, error?: () => void): void;
+        loadJson(path: any, success?: () => void, error?: () => void): void;
+        loadTexture(path: any, success?: () => void, error?: () => void): void;
+        loadTextureAtlas(path: any, success: (() => void) | undefined, error: (() => void) | undefined, fileAlias: any): void;
+        get(path: any): any;
+        require(path: any): any;
+        remove(path: any): any;
+        removeAll(): void;
+        isLoadingComplete(): boolean;
+        getToLoad(): number;
+        getLoaded(): number;
+        dispose(): void;
+        hasErrors(): boolean;
+        getErrors(): {};
+    };
+    pathPrefix: string;
     /**
      * set a default path prefix for assets location
      * @see loadAsset
@@ -562,17 +674,37 @@ declare class AssetManager {
      * @param {string} atlas
      * @param {string} skel
      * @example
-     * // load spine assets
+     * // "manually" load spine assets
      * Spine.assetManager.setPrefix("data/spine/");
      * Spine.assetManager.loadAsset("alien.atlas", "alien-ess.json");
      * await Spine.assetManager.loadAll();
      */
     loadAsset(atlas: string, skel: string): void;
+    /**
+     * load the given texture atlas
+     * @param {string} atlas
+     */
+    loadTextureAtlas(atlas: string, onload: any, onerror: any): void;
+    /**
+     * load the given skeleton .skel file
+     * @param {string} skel
+     */
+    loadBinary(skel: string, onload: any, onerror: any): void;
+    /**
+     * load the given skeleton binary file
+     * @param {string} skel
+     */
+    loadText(skel: string, onload: any, onerror: any): void;
     /**
      * load all defined spine assets
      * @see loadAsset
      */
-    loadAll(): any;
+    loadAll(): Promise<any>;
+    /**
+     * get the loaded skeleton data
+     * @param {string} path
+     */
+    require(path: string): any;
 }
 /******************************************************************************
  * Spine Runtimes License Agreement
@@ -2369,34 +2501,6 @@ declare class PointAttachment extends VertexAttachment {
     computeWorldRotation(bone: any): number;
     copy(): PointAttachment;
 }
-/******************************************************************************
- * Spine Runtimes License Agreement
- * Last updated July 28, 2023. Replaces all prior versions.
- *
- * Copyright (c) 2013-2023, Esoteric Software LLC
- *
- * Integration of the Spine Runtimes into software or otherwise creating
- * derivative works of the Spine Runtimes is permitted under the terms and
- * conditions of Section 2 of the Spine Editor License Agreement:
- * http://esotericsoftware.com/spine-editor-license
- *
- * Otherwise, it is permitted to integrate the Spine Runtimes into software or
- * otherwise create derivative works of the Spine Runtimes (collectively,
- * "Products"), provided that each user of the Products must obtain their own
- * Spine Editor license and redistribution of the Products in any form must
- * include this license and copyright notice.
- *
- * THE SPINE RUNTIMES ARE PROVIDED BY ESOTERIC SOFTWARE LLC "AS IS" AND ANY
- * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
- * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- * DISCLAIMED. IN NO EVENT SHALL ESOTERIC SOFTWARE LLC BE LIABLE FOR ANY
- * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES,
- * BUSINESS INTERRUPTION, OR LOSS OF USE, DATA, OR PROFITS) HOWEVER CAUSED AND
- * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE
- * SPINE RUNTIMES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *****************************************************************************/
 declare class PolygonBatcher {
     static getAndResetGlobalDrawCalls(): number;
     constructor(context: any, twoColorTint?: boolean, maxVertices?: number);
@@ -2411,10 +2515,9 @@ declare class PolygonBatcher {
     mesh: Mesh;
     srcColorBlend: any;
     srcAlphaBlend: any;
-    dstColorBlend: any;
-    dstAlphaBlend: any;
+    dstBlend: any;
     begin(shader: any): void;
-    setBlendMode(srcColorBlend: any, srcAlphaBlend: any, dstColorBlend: any, dstAlphaBlend: any): void;
+    setBlendMode(blendMode: any, premultipliedAlpha: any): void;
     draw(texture: any, vertices: any, indices: any): void;
     flush(): void;
     end(): void;
@@ -2424,6 +2527,12 @@ declare class PolygonBatcher {
 declare namespace PolygonBatcher {
     let disableCulling: boolean;
     let globalDrawCalls: number;
+    let blendModesGL: {
+        srcRgb: number;
+        srcRgbPma: number;
+        dstRgb: number;
+        srcAlpha: number;
+    }[];
 }
 declare class Pool {
     constructor(instantiator: any);
@@ -2781,10 +2890,9 @@ declare class ShapeRenderer {
     mesh: Mesh;
     srcColorBlend: any;
     srcAlphaBlend: any;
-    dstColorBlend: any;
-    dstAlphaBlend: any;
+    dstBlend: any;
     begin(shader: any): void;
-    setBlendMode(srcColorBlend: any, srcAlphaBlend: any, dstColorBlend: any, dstAlphaBlend: any): void;
+    setBlendMode(srcColorBlend: any, srcAlphaBlend: any, dstBlend: any): void;
     setColor(color: any): void;
     setColorWith(r: any, g: any, b: any, a: any): void;
     point(x: any, y: any, color: any): void;
@@ -3562,8 +3670,10 @@ declare class SlotData {
 declare class SpineCanvas {
     /** Constructs a new spine canvas, rendering to the provided HTML canvas. */
     constructor(canvas: any, config: any);
+    config: any;
     /** Tracks the current time, delta, and other time related statistics. */
     time: TimeKeeper;
+    disposed: boolean;
     htmlCanvas: any;
     context: ManagedWebGLRenderingContext;
     renderer: SceneRenderer;
@@ -3600,6 +3710,8 @@ declare class SpineCanvas {
     input: Input;
     /** Clears the canvas with the given color. The color values are given in the range [0,1]. */
     clear(r: any, g: any, b: any, a: any): void;
+    /** Disposes the app, so the update() and render() functions are no longer called. Calls the dispose() callback.*/
+    dispose(): void;
 }
 declare class StringSet {
     entries: {};
@@ -4185,13 +4297,6 @@ declare class VertexAttribute {
     type: any;
     numElements: any;
 }
-declare class WebGLBlendModeConverter {
-    static getDestGLBlendMode(blendMode: any): 1 | 771;
-    static getDestColorGLBlendMode(blendMode: any): 1 | 769 | 771;
-    static getDestAlphaGLBlendMode(blendMode: any, premultipliedAlpha?: boolean): 1 | 771;
-    static getSourceColorGLBlendMode(blendMode: any, premultipliedAlpha?: boolean): 1 | 770 | 774;
-    static getSourceAlphaGLBlendMode(blendMode: any, premultipliedAlpha?: boolean): 1 | 770;
-}
 declare class WindowedMean {
     constructor(windowSize?: number);
     addedValues: number;