@melonjs/spine-plugin 1.3.0 → 1.4.0

package/src/AssetManager.js

@@ -2,28 +2,50 @@ import { event, video } from "melonjs";
 import * as spineWebGL from "@esotericsoftware/spine-webgl";
 import * as spineCanvas from "@esotericsoftware/spine-canvas";
 
+/**
+ * @classdesc
+ * An Asset Manager class to load spine assets
+ */
 export default class AssetManager {
     asset_manager;
     pathPrefix;
 
+    /**
+     * @param {string} [pathPrefix=""] - a default path prefix for assets location
+     */
     constructor(pathPrefix = "") {
-        event.once(event.VIDEO_INIT, this.initAssetManager.bind(this));
-        this.pathPrefix = pathPrefix;
-    }
-
-    initAssetManager() {
-        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);
-        }
+        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);
+            }
+        });
     }
 
+    /**
+     * set a default path prefix for assets location
+     * @see loadAsset
+     * @param {string} pathPrefix
+     */
     setPrefix(pathPrefix) {
-        this.asset_manager.pathPrefix = pathPrefix;
+        this.asset_manager.pathPrefix =  this.pathPrefix = pathPrefix;
     }
 
+    /**
+     * define all spine assets to be loaded
+     * @see setPrefix
+     * @see loadAll
+     * @param {string} atlas
+     * @param {string} skel
+     * @example
+     * // 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);
@@ -36,6 +58,10 @@ export default class AssetManager {
         }
     }
 
+    /**
+     * load all defined spine assets
+     * @see loadAsset
+     */
     loadAll() {
         return this.asset_manager.loadAll();
     }

package/src/index.js

@@ -1,5 +1,4 @@
-import { Math, Renderable, Vector2d, video } from "melonjs";
-
+import { Math, Renderable, Vector2d, video, loader, utils, event } from "melonjs";
 import * as spineWebGL from "@esotericsoftware/spine-webgl";
 import * as spineCanvas from "@esotericsoftware/spine-canvas";
 import { Vector2 } from "@esotericsoftware/spine-core";
@@ -7,8 +6,53 @@ import { Vector2 } from "@esotericsoftware/spine-core";
 import AssetManager from "./AssetManager.js";
 import SkeletonRenderer from "./SkeletonRenderer.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;
+}
+
+// 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}`);
+});
+
+/**
+ * @classdesc
+ * An object to display a Spine animated skeleton on screen.
+ * @augments Renderable
+ */
 export default class Spine extends Renderable {
     runtime;
     skeleton;
@@ -19,6 +63,40 @@ export default class Spine extends Renderable {
     boneOffset;
     boneSize;
 
+    /**
+     * @param {number} x - the x coordinates of the Spine object
+     * @param {number} y - the y coordinates of the Spine object
+     * @param {object} settings - Configuration parameters for the Spine object
+     * @param {number} [settings.atlasFile] - the name of the atlasFile to be used to create this spine animation
+     * @param {number} [settings.jsonFile] - the name of the atlasFile to be used to create this spine animation
+     * @param {number} [settings.mixTime = 0.2] - the default mix duration to use when no mix duration has been defined between two animations.
+     * @example
+    * import * as Spine from '@melonjs/spine-plugin';
+    * import * as me from 'melonjs';
+    *
+    * // prepare/declare assets for the preloader
+    * const DataManifest = [
+    *     {
+    *         "name": "alien-ess.json",
+    *         "type": "spine",
+    *         "src": "data/spine/alien-ess.json"
+    *     },
+    *     {
+    *         "name": "alien.atlas",
+    *         "type": "spine",
+    *         "src": "data/spine/alien.atlas"
+    *     },
+    * ]
+    *
+    * // 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);
+    *
+    * // add it to the game world
+    * me.game.world.addChild(spineAlien);
+    */
     constructor(x, y, settings) {
         super(x, y, settings.width, settings.height);
 
@@ -39,20 +117,26 @@ export default class Spine extends Renderable {
             this.pos.z = settings.z;
         }
 
-        this.scaleValue = {x: 1, y: 1};
+        // use internally when calulcating bounds
         this.boneOffset = new Vector2();
         this.boneSize = new Vector2();
 
-        this.mixTime = settings.mixTime || 0.2;
+        // default mixTime
+        this.mixTime = typeof settings.mixTime !== "undefined" ? settings.mixTime :  0.2;
+
 
         if (settings.jsonFile) {
             this.jsonFile = settings.jsonFile;
             this.atlasFile = settings.atlasFile;
-
             this.setSkeleton(this.atlasFile, this.jsonFile);
         }
     }
 
+    /**
+     * Whether to enabler the debug mode when rendering the spine object
+     * @default false
+     * @type {boolean}
+     */
     get debugRendering() {
         return this.skeletonRenderer.debugRendering;
     }
@@ -61,14 +145,25 @@ export default class Spine extends Renderable {
         this.skeletonRenderer.debugRendering = value;
     }
 
+    /**
+     * set and load the given skeleton atlas and json definition files
+     * (use this if you did not specify any json or atlas through the constructor)
+     * @param {number} [atlasFile] - the name of the atlasFile to be used to create this spine animation
+     * @param {number} [jsonFile] - the name of the atlasFile to be used to create this spine animation
+     * @example
+     * // create a new Spine Renderable
+     * let spineAlien = new Spine(100, 100);
+     *
+     * // set the skeleton
+     * spineAlien.setSkeleton("alien.atlas", "alien-ess.json");
+     *
+     * // set default animation
+     * spineAlien.setAnimation(0, "death", true);
+     *
+     * // add it to the game world
+     * me.game.world.addChild(spineAlien);
+     */
     setSkeleton(atlasFile, jsonFile) {
-        this.loadSpineAssets(atlasFile, jsonFile);
-        this.root = this.skeleton.getRootBone();
-         // Spine uses Y-up, melonJS uses Y-down
-        this.root.scaleY *= -1;
-    }
-
-    loadSpineAssets(atlasFile, jsonFile) {
         // Create the texture atlas and skeleton data.
         let atlas = this.assetManager.require(atlasFile);
         let atlasLoader = new this.runtime.AtlasAttachmentLoader(atlas);
@@ -84,20 +179,50 @@ export default class Spine extends Renderable {
         var animationStateData = new this.runtime.AnimationStateData(this.skeleton.data);
         animationStateData.defaultMix = this.mixTime;
         this.animationState = new this.runtime.AnimationState(animationStateData);
+
+        // 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;
     }
 
+     /**
+     * Rotate this Spine object by the specified angle (in radians).
+     * @param {number} angle - The angle to rotate (in radians)
+     * @param {Vector2d|ObservableVector2d} [v] - an optional point to rotate around
+     * @returns {Spine} Reference to this object for method chaining
+     */
     rotate(angle, v) {
         // rotation for rootBone is in degrees (anti-clockwise)
         this.skeleton.getRootBone().rotation -= Math.radToDeg(angle) + 90;
         // melonJS rotate method takes radians
-        super.rotate(angle, v);
+        return super.rotate(angle, v);
     }
 
+     /**
+     * scale the Spine object around his anchor point.  Scaling actually applies changes
+     * to the currentTransform member wich is used by the renderer to scale the object
+     * when rendering.  It does not scale the object itself.  For example if the renderable
+     * is an image, the image.width and image.height properties are unaltered but the currentTransform
+     * member will be changed.
+     * @param {number} x - a number representing the abscissa of the scaling vector.
+     * @param {number} [y=x] - a number representing the ordinate of the scaling vector.
+     * @returns {Spine} Reference to this object for method chaining
+     */
     scale(x, y = x) {
-        this.scaleValue = {x, y};
-        super.scale(x, y);
+        // untested
+        return super.scale(x, y);
     }
 
+    /**
+     * update the bounding box for this spine object.
+     * (this will automatically update the bounds of the entire skeleton animation)
+     * @param {boolean} [absolute=true] - update the bounds size and position in (world) absolute coordinates
+     * @returns {Bounds} this shape bounding box Rectangle object
+     */
     updateBounds(absolute = true) {
         if (this.isRenderable) {
             let bounds = this.getBounds();
@@ -173,9 +298,6 @@ export default class Spine extends Renderable {
 
     /**
      * draw this spine object
-     * @name draw
-     * @memberof Spine
-     * @protected
      * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
      * @param {Camera2d} [viewport] - the viewport to (re)draw
      */
@@ -183,6 +305,13 @@ export default class Spine extends Renderable {
         this.skeletonRenderer.draw(renderer, this.skeleton);
     }
 
+    /**
+     * 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 {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.
+     */
     setAnimationByIndex(track_index, index, loop = false) {
         if (index < 0 || index >= this.skeleton.data.animations.length) {
             return (console.log("Animation Index not found"));
@@ -191,10 +320,25 @@ export default class Spine extends Renderable {
         }
     }
 
+    /**
+     * 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.
+     * @example
+     * // set the current animation
+     * spineAlien.setAnimation(0, "death", true);
+     */
     setAnimation(track_index, name, loop = false) {
         this.animationState.setAnimation(track_index, name, loop);
     }
 
+    /**
+     * 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.
+     */
     addAnimationByIndex(track_index, index, loop = false, delay = 0) {
         if (index < 0 || index >= this.skeleton.data.animations.length) {
             return (console.log("Animation Index not found"));
@@ -223,18 +367,44 @@ export default class Spine extends Renderable {
         };
     }
 
+    /**
+     * Set the default mix duration to use when no mix duration has been defined between two animations.
+     * @param {number} mixTime
+     */
     setDefaultMixTime(mixTime) {
-        this.animationState.data.defaultMix = mixTime;
+        this.animationState.data.defaultMix = this.mixTime = mixTime;
     }
 
+    /**
+     * Sets a mix duration by animation name.
+     */
     setTransitionMixTime(firstAnimation, secondAnimation, mixTime) {
         this.animationState.setMix(firstAnimation, secondAnimation, mixTime);
     }
 
+    /**
+     * Sets a skin by name.
+     * @param {string} skinName
+     * @example
+     * // create a new Spine Renderable
+     * let spineAlien = new Spine(100, 100, {atlasFile: "mix-and-match-pma.atlas", jsonFile: "mix-and-match-pro.json"});
+     *
+     * // set default animation
+     * spineAlien.setAnimation(0, "dance", true);
+     *
+     * // set default skin
+     * spineAlien.setSkinByName("full-skins/girl");
+     *
+     * // add it to the game world
+     * me.game.world.addChild(spineAlien);
+     */
     setSkinByName(skinName) {
         this.skeleton.setSkinByName(skinName);
     }
 
+    /**
+     * Sets this slot to the setup pose.
+     */
     setToSetupPose() {
         this.skeleton.setToSetupPose();
     }