@melonjs/spine-plugin 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melonjs/spine-plugin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "melonJS Spine plugin",
   "homepage": "https://github.com/melonjs/spine-plugin#readme",
   "type": "module",
@@ -46,12 +46,12 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "melonjs": "^15.10.0"
+    "melonjs": "^15.12.0"
   },
   "dependencies": {
-    "@esotericsoftware/spine-canvas": "^4.2.19",
-    "@esotericsoftware/spine-core": "^4.2.19",
-    "@esotericsoftware/spine-webgl": "^4.2.19"
+    "@esotericsoftware/spine-canvas": "^4.2.23",
+    "@esotericsoftware/spine-core": "^4.2.23",
+    "@esotericsoftware/spine-webgl": "^4.2.23"
   },
   "devDependencies": {
     "@babel/eslint-parser": "^7.22.15",
@@ -61,9 +61,9 @@
     "@rollup/plugin-node-resolve": "^15.2.1",
     "@rollup/plugin-replace": "^5.0.2",
     "del-cli": "^5.1.0",
-    "eslint": "^8.48.0",
-    "eslint-plugin-jsdoc": "^46.5.1",
-    "rollup": "^3.28.1",
+    "eslint": "^8.50.0",
+    "eslint-plugin-jsdoc": "^46.8.2",
+    "rollup": "^3.29.2",
     "rollup-plugin-bundle-size": "^1.0.3",
     "typescript": "^5.2.2"
   },

package/src/AssetManager.js

@@ -1,4 +1,4 @@
-import { event, video } from "melonjs";
+import { utils, loader } from "melonjs";
 import * as spineWebGL from "@esotericsoftware/spine-webgl";
 import * as spineCanvas from "@esotericsoftware/spine-canvas";
 
@@ -11,18 +11,46 @@ export default class AssetManager {
     pathPrefix;
 
     /**
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a melonJS renderer instance
      * @param {string} [pathPrefix=""] - a default path prefix for assets location
      */
-    constructor(pathPrefix = "") {
-        event.once(event.VIDEO_INIT, () => {
-            this.pathPrefix = pathPrefix;
-            if (video.renderer.WebGLVersion >= 1) {
-                this.asset_manager = new spineWebGL.AssetManager(video.renderer.getContext(), this.pathPrefix);
-            } else {
-                // canvas renderer
-                this.asset_manager = new spineCanvas.AssetManager(this.pathPrefix);
+    constructor(renderer, pathPrefix = "") {
+        this.pathPrefix = pathPrefix;
+        if (renderer.WebGLVersion >= 1) {
+            this.asset_manager = new spineWebGL.AssetManager(renderer.getContext(), this.pathPrefix);
+        } else {
+            // canvas renderer
+            this.asset_manager = new spineCanvas.AssetManager(this.pathPrefix);
+        }
+
+        // set the spine custom parser
+        loader.setParser("spine", (data, onload, onerror) => {
+            // decompose data.src for the spine loader
+            const ext = utils.file.getExtension(data.src);
+            const basename = utils.file.getBasename(data.src);
+            const path = utils.file.getPath(data.src);
+            const filename = basename + "." + ext;
+
+            this.setPrefix(path);
+
+            // load asset
+            switch (ext) {
+                case "atlas":
+                    this.loadTextureAtlas(filename, onload, onerror);
+                    break;
+                case "json":
+                    this.loadText(filename, onload, onerror);
+                    break;
+                case "skel":
+                    this.loadBinary(filename, onload, onerror);
+                    break;
+                default:
+                    throw "Spine plugin: unknown extension when preloading spine assets";
             }
+
+            return 1;
         });
+
     }
 
     /**
@@ -41,23 +69,48 @@ export default 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, skel) {
         if (atlas) {
-            this.asset_manager.loadTextureAtlas(atlas);
+            this.loadTextureAtlas(atlas);
         }
 
         if (skel.endsWith(".skel")) {
-            this.asset_manager.loadBinary(skel);
+            this.loadBinary(skel);
         } else {
-            this.asset_manager.loadText(skel);
+            this.loadText(skel);
         }
     }
 
+    /**
+     * load the given texture atlas
+     * @param {string} atlas
+     */
+    loadTextureAtlas(atlas, onload, onerror) {
+        return this.asset_manager.loadTextureAtlas(atlas, onload, onerror);
+    }
+
+
+    /**
+     * load the given skeleton .skel file
+     * @param {string} skel
+     */
+    loadBinary(skel, onload, onerror) {
+        return this.asset_manager.loadBinary(skel, onload, onerror);
+    }
+
+    /**
+     * load the given skeleton binary file
+     * @param {string} skel
+     */
+    loadText(skel, onload, onerror) {
+        return this.asset_manager.loadText(skel, onload, onerror);
+    }
+
     /**
      * load all defined spine assets
      * @see loadAsset
@@ -65,4 +118,12 @@ export default class AssetManager {
     loadAll() {
         return this.asset_manager.loadAll();
     }
+
+    /**
+     * get the loaded skeleton data
+     * @param {string} path
+     */
+    require(path) {
+        return this.asset_manager.require(path);
+    }
 }

package/src/SpinePlugin.js

@@ -0,0 +1,24 @@
+import { plugin } from "melonjs";
+import { name, version, dependencies, homepage, peerDependencies } from "../package.json";
+import AssetManager from "./AssetManager";
+
+/**
+ * @classdesc
+ * a Spine 4.x plugin implementation for melonJS
+ * @augments plugin.BasePlugin
+ */
+export class SpinePlugin extends plugin.BasePlugin {
+    constructor() {
+        // call the super constructor
+        super();
+
+        // minimum melonJS version expected to run this plugin
+        this.version = peerDependencies["melonjs"];
+
+        // hello world
+        console.log(`${name} ${version} - spine runtime ${dependencies["@esotericsoftware/spine-core"]} | ${homepage}`);
+
+        // instantiate the asset manager
+        this.assetManager = new AssetManager(this.app.renderer);
+    }
+}

package/src/index.js

@@ -1,67 +1,55 @@
-import { Math, Renderable, Vector2d, video, loader, utils, event } from "melonjs";
+import { Math, Renderable, Vector2d, plugin } from "melonjs";
 import * as spineWebGL from "@esotericsoftware/spine-webgl";
 import * as spineCanvas from "@esotericsoftware/spine-canvas";
 import { Vector2 } from "@esotericsoftware/spine-core";
 
-import AssetManager from "./AssetManager.js";
 import SkeletonRenderer from "./SkeletonRenderer.js";
+import { SpinePlugin } from "./SpinePlugin.js";
 
-import { name, version, dependencies, homepage } from "../package.json";
-
-export let assetManager = new AssetManager();
-
-// a custom Spine parser for melonJS preloader
-function spineParser(data, onload, onerror) {
-
-    // decompose data.src for the spine loader
-    const ext = utils.file.getExtension(data.src);
-    const basename = utils.file.getBasename(data.src);
-    const path = utils.file.getPath(data.src);
-    const filename = basename + "." + ext;
-
-    // set url prefix
-    assetManager.setPrefix(path);
-
-    // load asset
-    switch (ext) {
-        case "atlas":
-            assetManager.asset_manager.loadTextureAtlas(filename, onload, onerror);
-            break;
-        case "json":
-            assetManager.asset_manager.loadText(filename, onload, onerror);
-            break;
-        case "skel":
-            assetManager.asset_manager.loadBinary(filename, onload, onerror);
-            break;
-        default:
-            throw "Spine plugin: unknown extension when preloading spine assets";
-    }
-
-    return 1;
-}
+export { SpinePlugin } from "./SpinePlugin.js";
 
-// set the spine custom parser
-loader.setParser("spine", spineParser);
-
-// hello world
-event.once(event.VIDEO_INIT, () => {
-    console.log(`${name} ${version} - spine runtime ${dependencies["@esotericsoftware/spine-core"]} | ${homepage}`);
-});
+// a temporary array used for skeleton.getBounds();
+let tempArray = [];
 
 /**
  * @classdesc
- * An object to display a Spine animated skeleton on screen.
+ * An renderable object to render Spine animated skeleton.
  * @augments Renderable
  */
 export default class Spine extends Renderable {
     runtime;
     skeleton;
+    plugin;
+    renderer;
     animationState;
     skeletonRenderer;
-    assetManager;
     root;
     boneOffset;
     boneSize;
+    isSpineFlipped = {
+        x : false,
+        y : false
+    };
+
+    /**
+     * 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;
 
     /**
      * @param {number} x - the x coordinates of the Spine object
@@ -100,13 +88,19 @@ export default class Spine extends Renderable {
     constructor(x, y, settings) {
         super(x, y, settings.width, settings.height);
 
-        if (video.renderer.WebGLVersion >= 1) {
+        // ensure plugin was properly registered
+        this.plugin = plugin.get(SpinePlugin);
+        if (typeof this.plugin === "undefined") {
+            throw "Spine plugin: plugin needs to be registered first using plugin.register";
+        }
+        this.renderer = this.plugin.app.renderer;
+
+        if (this.renderer.WebGLVersion >= 1) {
             this.runtime = spineWebGL;
         } else {
             this.runtime = spineCanvas;
         }
 
-        this.assetManager = assetManager.asset_manager;
         this.skeletonRenderer = new SkeletonRenderer(this.runtime);
 
         // force anchorPoint to 0,0
@@ -165,15 +159,15 @@ export default class Spine extends Renderable {
      */
     setSkeleton(atlasFile, jsonFile) {
         // Create the texture atlas and skeleton data.
-        let atlas = this.assetManager.require(atlasFile);
+        let atlas = this.plugin.assetManager.require(atlasFile);
         let atlasLoader = new this.runtime.AtlasAttachmentLoader(atlas);
         let skeletonJson = new this.runtime.SkeletonJson(atlasLoader);
-        let skeletonData = skeletonJson.readSkeletonData(this.assetManager.require(jsonFile));
+        let skeletonData = skeletonJson.readSkeletonData(this.plugin.assetManager.require(jsonFile));
 
         // Instantiate a new skeleton based on the atlas and skeleton data.
         this.skeleton = new this.runtime.Skeleton(skeletonData);
-        this.skeleton.setToSetupPose();
-        this.skeleton.updateWorldTransform();
+
+        this.setToSetupPose();
 
         // Setup an animation state with a default mix of 0.2 seconds.
         var animationStateData = new this.runtime.AnimationStateData(this.skeleton.data);
@@ -182,11 +176,34 @@ export default class Spine extends Renderable {
 
         // get a reference to the root bone
         this.root = this.skeleton.getRootBone();
-        // Spine uses Y-up, melonJS uses Y-down
-        this.root.scaleY *= -1;
+    }
 
-        // mark the object as dirty
-        this.isDirty = true;
+    /**
+     * 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 = true) {
+        if (this.isSpineFlipped.x !== flip) {
+            this.isSpineFlipped.x = flip;
+            this.root.scaleX *= -1;
+            this.isDirty = true;
+        }
+        return this;
+    }
+
+    /**
+     * 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 = true) {
+        if (this.isSpineFlipped.y !== flip) {
+            this.isSpineFlipped.y = flip;
+            this.root.scaleY *= -1;
+            this.isDirty = true;
+        }
+        return this;
     }
 
      /**
@@ -235,13 +252,16 @@ export default class Spine extends Renderable {
                 let boneOffset = this.boneOffset;
                 let boneSize = this.boneSize;
 
-                this.skeleton.getBounds(boneOffset, boneSize);
+                this.skeleton.getBounds(boneOffset, boneSize, tempArray);
+
+                let minX = boneOffset.x - rootBone.x,
+                    minY = boneOffset.y - rootBone.y;
 
                 bounds.addFrame(
-                    boneOffset.x - rootBone.x,
-                    boneOffset.y - rootBone.y,
-                    boneSize.x + boneOffset.x - rootBone.x,
-                    boneSize.y + boneOffset.y  - rootBone.y,
+                    minX,
+                    minY,
+                    minX + boneSize.x,
+                    minY + boneSize.y,
                     !isIdentity ? this.currentTransform : undefined
                 );
             } else {
@@ -256,6 +276,7 @@ export default class Spine extends Renderable {
 
             if (absolute === true) {
                 var absPos = this.getAbsolutePosition();
+                //bounds.translate(absPos.x, absPos.y);
                 bounds.centerOn(absPos.x + bounds.centerX,  absPos.y + bounds.centerY);
             }
             return bounds;
@@ -275,22 +296,24 @@ export default class Spine extends Renderable {
     update(dt) {
         if (typeof this.skeleton !== "undefined") {
             let rootBone = this.skeleton.getRootBone();
-
-            // update the root bone position
-            if (rootBone.x !== this.pos.x) {
-                rootBone.x = this.pos.x;
-            }
-            if (rootBone.y !== this.pos.y) {
-                rootBone.y = this.pos.y;
-            }
+            //let height = this.renderer.getHeight();
 
             // Update and apply the animation state, update the skeleton's
-            // world transforms and render the skeleton.
             this.animationState.update(dt / 1000);
             this.animationState.apply(this.skeleton);
+
+            // update the root bone position
+            rootBone.x = this.pos.x;
+            rootBone.y = this.pos.y;
+
+            // world transforms
             this.skeleton.updateWorldTransform();
 
+            // update Bounds
             this.updateBounds();
+
+            // world transforms
+            //this.skeleton.updateWorldTransform();
         }
         return true;
     }
@@ -310,13 +333,13 @@ export default 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, index, loop = false) {
         if (index < 0 || index >= this.skeleton.data.animations.length) {
             return (console.log("Animation Index not found"));
         } else {
-            this.animationState.setAnimation(track_index, this.skeleton.data.animations[index].name, loop);
+            return this.setAnimation(track_index, this.skeleton.data.animations[index].name, loop);
         }
     }
 
@@ -325,25 +348,40 @@ export default 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 {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, name, loop = false) {
-        this.animationState.setAnimation(track_index, name, loop);
+        this.currentTrack = this.animationState.setAnimation(track_index, name, loop);
+        return this.currentTrack;
+    }
+
+    /**
+     * 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) {
+        return typeof this.currentTrack !== "undefined" && this.currentTrack.animation.name === name;
     }
 
     /**
      * 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, index, loop = false, delay = 0) {
         if (index < 0 || index >= this.skeleton.data.animations.length) {
             return (console.log("Animation Index not found"));
         } else {
-            this.animationState.addAnimation(track_index, this.skeleton.data.animations[index].name, loop, delay);
+            return this.addAnimation(track_index, this.skeleton.data.animations[index].name, loop, delay);
         }
     }
 
@@ -403,9 +441,19 @@ export default class Spine extends Renderable {
     }
 
     /**
-     * Sets this slot to the setup pose.
+     * Reset this slot to the setup pose.
      */
     setToSetupPose() {
         this.skeleton.setToSetupPose();
+        // Spine uses Y-up, melonJS uses Y-down
+        this.skeleton.getRootBone().scaleY *= -1;
+        this.skeleton.updateWorldTransform();
+        // reset flip flags
+        this.isSpineFlipped.y = false;
+        this.isSpineFlipped.x = false;
+        // reset reference to current track entry
+        this.currentTrack = undefined;
+        // mark the object as dirty
+        this.isDirty = true;
     }
 }