@melonjs/spine-plugin 1.5.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 2.0.1
+
+### Changed
+- minimum melonJS version is now 18.2.1 (loading screen race condition fix)
+
+## 2.0.0
+
+### Changed
+- migrated into the melonJS monorepo
+- replaced rollup build with esbuild (aligned with debug-plugin)
+- bumped Spine runtime dependencies to ^4.2.108
+- minimum melonJS version is now 18.2.0
+- WebGL rendering now uses a custom `SpineBatcher` extending melonJS `Batcher` with indexed drawing, instead of Spine's own `PolygonBatcher` — integrates through melonJS's batcher system (`setBatcher("spine")`)
+- SpineBatcher uses Spine's official two-color tinting shader (`Shader.newTwoColoredTextured`) and attribute names
+- blend modes now delegate to melonJS `renderer.setBlendMode()` with premultiplied alpha support
+- canvas `SkeletonRenderer` refactored: extracted `drawRegion()`, `drawMesh()`, `drawTriangle()` methods from monolithic `draw()`
+- `AssetManager` cleaned up: renamed `asset_manager` to `spineAssetManager`, added `dispose()`, fixed JSDoc
+- source reorganized: `index.js` is the proper entry point, `Spine.js` is the renderable, `SpinePlugin.js` is the plugin registration
+- `SpinePlugin.js` renamed from `index.js` for clarity
+
+### Fixed
+- use `setBatcher`/`currentBatcher` instead of deprecated `setCompositor`/`currentCompositor`
+- replace removed `utils.file.getPath()` with inline path extraction
+- `rotate()` now always calls `super.rotate()` and returns `this` for chaining (WebGL path was missing both)
+- `scale()` now applies scale to the Spine root bone as well as the melonJS transform
+- `dispose()` now guards against calling WebGL-only methods on canvas renderer
+- `throw "string"` replaced with `throw new Error()` for proper stack traces
+- `setAnimationByIndex`/`addAnimationByIndex` now use `console.warn` instead of `console.log` for errors
+- canvas `drawTriangle()` now guards against degenerate triangles (zero-area UV)
+- canvas mesh drawing now subtracts 1 pixel from UV dimensions to prevent edge bleeding (matches official spine-canvas)
+
+### Added
+- `SpineBatcher`: custom melonJS `Batcher` for two-color tinted Spine rendering via indexed `drawElements`
+- `addAnimation(trackIndex, name, loop, delay)` method for adding queued animations by name
+- `setCombinedSkin(combinedName, ...skinNames)` for mix-and-match skin combining
+- `setEmptyAnimation(trackIndex, mixDuration)` for clearing animation tracks
+- `findBone(boneName)` and `findSlot(slotName)` for direct skeleton access
+- `addAnimationListener(listener)` and `removeAnimationListener(listener)` for animation state events (start, end, complete, event, etc.)
+- `getAnimationNames()` and `getSkinNames()` for skeleton introspection
+- `skeleton.update(delta)` call before `updateWorldTransform()` as required by Spine 4.2+
+- canvas `SkeletonRenderer` auto-detects mesh attachments and enables `triangleRendering` only when needed
+- spine example added to the monorepo examples app with character selector dropdown and debug plugin
+
+### Removed
+- redundant `getSpinePosition()`, `setSpineSize()`, `getSpineSize()` methods (use inherited `pos`, `width`, `height`)
+- redundant `addAnimationByName()` (replaced by `addAnimation()`)
+- old melonJS version check hack in constructor (no longer needed with >=18.2.0)
+- old test/examples folder (replaced by monorepo examples)
+- custom GLSL shaders (now uses Spine's official `Shader.newTwoColoredTextured`)
+- manual GL state management in `resetRenderer()`/`enableRenderer()`/`end()` (replaced by melonJS batcher system)
+
 ## 1.5.0 - 2023-09-23
 
 - fix the `addAnimation()` method not returning the corresponding set TrackEntry

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (C) 2011 - 2023 Olivier Biot (AltByte Pte Ltd)
+Copyright (C) 2011 - 2026 Olivier Biot (AltByte Pte Ltd)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,28 +1,44 @@
 # melonJS Spine Plugin
 
-a [Spine](http://en.esotericsoftware.com/spine-in-depth) 4.x plugin implementation for [melonJS 2](http://www.melonjs.org)
+A [Spine](http://en.esotericsoftware.com/spine-in-depth) 4.2 runtime integration for the [melonJS](http://www.melonjs.org) game engine, using the official [@esotericsoftware/spine-webgl](https://www.npmjs.com/package/@esotericsoftware/spine-webgl) and [@esotericsoftware/spine-canvas](https://www.npmjs.com/package/@esotericsoftware/spine-canvas) runtimes.
 
 ![melonjs-spine-gif](https://github.com/melonjs/spine-plugin/assets/4033090/dc259c8e-def6-419e-83a9-cda374715686)
 
->Note: although functional, this plugin is still a work in progress. Feedback and especially contributions are welcome!
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/melonjs/es6-boilerplate/blob/master/LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/melonjs/melonJS/blob/master/packages/spine-plugin/LICENSE)
 [![NPM Package](https://img.shields.io/npm/v/@melonjs/spine-plugin)](https://www.npmjs.com/package/@melonjs/spine-plugin)
-[![jsDeliver](https://data.jsdelivr.com/v1/package/npm/@melonjs/spine-plugin/badge?style=rounded)](https://www.jsdelivr.com/package/npm/@melonjs/spine-plugin)
+[![Spine Runtime](https://img.shields.io/badge/spine--runtime-4.2-orange)](http://esotericsoftware.com/spine-runtimes)
+
+[Live Example](https://melonjs.github.io/melonJS/examples/#/spine) — 17 official Spine characters including spineboy, raptor, owl, dragon, and more
 
+## Features
+-------------------------------------------------------------------------------
+- **WebGL rendering** via custom `SpineBatcher` extending melonJS `Batcher` with two-color tinting and indexed drawing
+- **Canvas rendering** with full mesh, clipping, tinting, and blend mode support
+- **Spine 4.2 physics** support with automatic gravity correction for Y-down coordinate system
+- **Two-color tinting** (dark/light color) using Spine's official shader
+- **Blend modes** (Normal, Additive, Multiply, Screen) with premultiplied alpha support
+- **Clipping attachments** via melonJS masking (canvas) and Spine's SkeletonClipping (WebGL)
+- **Skin support** including mix-and-match skin combining via `setCombinedSkin()`
+- **Animation state events** (start, end, complete, event, interrupt, dispose)
+- **Skeleton introspection** — `findBone()`, `findSlot()`, `getAnimationNames()`, `getSkinNames()`
+- **Animation queuing** — `setAnimation()`, `addAnimation()`, `setEmptyAnimation()`
+- **Debug rendering** for bones, regions, meshes, and clipping areas
+- **Auto-detection** of mesh attachments for optimized canvas rendering (fast path for region-only skeletons)
+- **Binary skeleton** (.skel) and JSON skeleton loading via melonJS preloader
+- **Integrated** with melonJS batcher system — no manual GL state management
 
 ## 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.12 or higher.
+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 18.2.1 or higher.
 
-To install the plugin using npm :
+To install the plugin using npm:
 
-`$ [sudo] npm install @melonjs/spine-plugin`
+`$ npm install @melonjs/spine-plugin`
 
 Then import and use the plugin in your project. For example:
 ```JavaScript
-import { SpinePlugin } from '@melonjs/spine-plugin';
+import Spine, { SpinePlugin } from '@melonjs/spine-plugin';
 import * as me from 'melonjs';
 
 // register the plugin
@@ -42,9 +58,6 @@ const DataManifest = [
     },
 ];
 
-// import default Spine class
-import Spine from '@melonjs/spine-plugin';
-
 // preload assets
 me.loader.preload(DataManifest, async function() {
 
@@ -59,24 +72,59 @@ me.loader.preload(DataManifest, async function() {
 
 }
 ```
->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)
+>Note: use "spine" as a value for the `type` property to indicate which assets are actual Spine assets and to be loaded using the plugin
 
-for more details, see a complete usage example in the [test](test) folder
+## API
+-------------------------------------------------------------------------------
+
+### Animation
+| Method | Description |
+|---|---|
+| `setAnimation(trackIndex, name, loop)` | Set the current animation for a track |
+| `setAnimationByIndex(trackIndex, index, loop)` | Set animation by index |
+| `addAnimation(trackIndex, name, loop, delay)` | Queue an animation after the current one |
+| `setEmptyAnimation(trackIndex, mixDuration)` | Clear a track with optional mix out |
+| `isCurrentAnimation(name)` | Check if a specific animation is playing |
+| `setDefaultMixTime(mixTime)` | Set default mix duration between animations |
+| `setTransitionMixTime(from, to, mixTime)` | Set mix duration between two specific animations |
+| `addAnimationListener(listener)` | Register animation event callbacks |
+| `removeAnimationListener(listener)` | Remove a registered listener |
+| `getAnimationNames()` | Get list of available animation names |
+
+### Skins
+| Method | Description |
+|---|---|
+| `setSkinByName(skinName)` | Set a skin by name |
+| `setCombinedSkin(name, ...skinNames)` | Combine multiple skins (mix-and-match) |
+| `getSkinNames()` | Get list of available skin names |
+
+### Skeleton
+| Method | Description |
+|---|---|
+| `findBone(boneName)` | Find a bone by name |
+| `findSlot(slotName)` | Find a slot by name |
+| `setToSetupPose()` | Reset skeleton to setup pose |
+| `setSkeleton(atlasFile, jsonFile)` | Load a skeleton (if not set via constructor) |
+
+### Transform
+| Method | Description |
+|---|---|
+| `flipX(flip)` | Flip horizontally |
+| `flipY(flip)` | Flip vertically |
+| `scale(x, y)` | Scale the skeleton |
+| `rotate(angle)` | Rotate the skeleton |
 
 ## Compatibility
 -------------------------------------------------------------------------------
 
-below is the compatibility version matrix :
-
-| melonJS | @melonjs/spine-plugin | spine-runtime |
+| @melonjs/spine-plugin | melonJS | 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). 
+| v2.0.1+ | v18.2.1 (or higher) | v4.2.x |
+| v2.0.0 | v18.2.0 | v4.2.x |
+| v1.5.x | v15.12.x — v18.0.x | v4.1, v4.2-beta |
 
 ## 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/)
-* Chat: come and chat with us on [discord](https://discord.gg/aur7JMk), or [gitter](https://gitter.im/melonjs/public)
-* we tried to keep our [wikipage](https://github.com/melonjs/melonJS/wiki) up-to-date with useful links, tutorials, and anything related melonJS.
+If you need technical support, you can contact us through the following channels:
+* Chat: come and chat with us on [discord](https://discord.gg/aur7JMk)
+* We tried to keep our [wiki](https://github.com/melonjs/melonJS/wiki) up-to-date with useful links, tutorials, and anything related to melonJS.

package/build/AssetManager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @classdesc
+ * An Asset Manager class that integrates Spine's asset loading with
+ * melonJS's preloader via a custom "spine" parser.
+ * Handles loading of atlas, JSON skeleton, and binary skeleton (.skel) files.
+ */
+export default class AssetManager {
+    /**
+     * @param {CanvasRenderer|WebGLRenderer} renderer - a melonJS renderer instance
+     * @param {string} [pathPrefix=""] - a default path prefix for assets location
+     */
+    constructor(renderer: CanvasRenderer | WebGLRenderer, pathPrefix?: string);
+    /**
+     * the underlying Spine asset manager
+     * @ignore
+     */
+    spineAssetManager: spineWebGL.AssetManager | spineCanvas.AssetManager;
+    /**
+     * Set a default path prefix for assets location.
+     * @param {string} pathPrefix
+     */
+    setPrefix(pathPrefix: string): void;
+    /**
+     * Load a spine atlas and skeleton file pair.
+     * @param {string} atlas - atlas filename (e.g. "alien.atlas")
+     * @param {string} skel - skeleton filename (.json or .skel)
+     * @example
+     * // manually load spine assets
+     * plugin.assetManager.setPrefix("data/spine/");
+     * plugin.assetManager.loadAsset("alien.atlas", "alien-ess.json");
+     * await plugin.assetManager.loadAll();
+     */
+    loadAsset(atlas: string, skel: string): void;
+    /**
+     * Load a texture atlas file.
+     * @param {string} atlas - atlas filename
+     * @param {Function} [onload] - callback on successful load
+     * @param {Function} [onerror] - callback on error
+     */
+    loadTextureAtlas(atlas: string, onload?: Function, onerror?: Function): void;
+    /**
+     * Load a binary skeleton (.skel) file.
+     * @param {string} skel - skeleton binary filename
+     * @param {Function} [onload] - callback on successful load
+     * @param {Function} [onerror] - callback on error
+     */
+    loadBinary(skel: string, onload?: Function, onerror?: Function): void;
+    /**
+     * Load a JSON skeleton file.
+     * @param {string} skel - skeleton JSON filename
+     * @param {Function} [onload] - callback on successful load
+     * @param {Function} [onerror] - callback on error
+     */
+    loadText(skel: string, onload?: Function, onerror?: Function): void;
+    /**
+     * Load all queued spine assets.
+     * @returns {Promise} resolves when all assets are loaded
+     * @see loadAsset
+     */
+    loadAll(): Promise<any>;
+    /**
+     * Get a loaded asset by path.
+     * @param {string} path - the asset path/name
+     * @returns {*} the loaded asset (TextureAtlas, skeleton data, etc.)
+     */
+    require(path: string): any;
+    /**
+     * Dispose all loaded assets and release GPU resources.
+     */
+    dispose(): void;
+}
+import * as spineWebGL from "@esotericsoftware/spine-webgl";
+import * as spineCanvas from "@esotericsoftware/spine-canvas";
+//# sourceMappingURL=AssetManager.d.ts.map

package/build/AssetManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetManager.d.ts","sourceRoot":"","sources":["../src/AssetManager.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACC;;;OAGG;IACH,sBAHW,cAAc,GAAC,aAAa,eAC5B,MAAM,EA0ChB;IAvCA;;;OAGG;IACH,sEAG4C;IAkC7C;;;OAGG;IACH,sBAFW,MAAM,QAIhB;IAED;;;;;;;;;OASG;IACH,iBARW,MAAM,QACN,MAAM,QAgBhB;IAED;;;;;OAKG;IACH,wBAJW,MAAM,+CAMhB;IAED;;;;;OAKG;IACH,iBAJW,MAAM,+CAMhB;IAED;;;;;OAKG;IACH,eAJW,MAAM,+CAMhB;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;OAIG;IACH,cAHW,MAAM,GACJ,GAAC,CAIb;IAED;;OAEG;IACH,gBAEC;CACD;4BA3I2B,+BAA+B;6BAD9B,gCAAgC"}

package/build/SkeletonRenderer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @classdesc
+ * A Canvas-based Spine skeleton renderer that draws through melonJS's
+ * canvas renderer API (drawImage, transform, setTint, setMask, etc.).
+ * This provides proper integration with melonJS's canvas rendering pipeline
+ * including tinting, blend modes, and clipping support.
+ */
+export default class SkeletonRenderer {
+    /**
+     * Whether to enable triangle rendering for mesh attachments.
+     * When false, only region (image) attachments are rendered using the
+     * fast bone-transform path. Automatically enabled by Spine when the
+     * skeleton contains mesh attachments.
+     * @type {boolean}
+     * @default false
+     */
+    triangleRendering: boolean;
+    /**
+     * Whether to render debug outlines for regions, meshes, and clips
+     * @type {boolean}
+     * @default false
+     */
+    debugRendering: boolean;
+    tintColor: MColor;
+    tempColor: MColor;
+    clipper: SkeletonClipping;
+    clippingVertices: any[];
+    clippingMask: Polygon;
+    /**
+     * Draw the given skeleton using the melonJS canvas renderer.
+     * @param {CanvasRenderer} renderer - the melonJS canvas renderer
+     * @param {Skeleton} skeleton - the Spine skeleton to draw
+     */
+    draw(renderer: CanvasRenderer, skeleton: Skeleton): void;
+    /**
+     * Draw a region attachment (single quad image).
+     * @param {CanvasRenderer} renderer
+     * @param {HTMLImageElement} image
+     * @param {Bone} bone
+     * @param {RegionAttachment} attachment
+     * @param {TextureRegion} region
+     * @param {Polygon|null} mask - clipping mask if active
+     * @param {boolean} debug - whether to draw debug outline
+     * @ignore
+     */
+    drawRegion(renderer: CanvasRenderer, image: HTMLImageElement, bone: Bone, attachment: RegionAttachment, region: TextureRegion, mask: Polygon | null, debug: boolean): void;
+    /**
+     * Draw a mesh attachment as a series of textured triangles.
+     * @param {CanvasRenderer} renderer
+     * @param {HTMLImageElement} image
+     * @param {Float32Array} vertices - world vertices
+     * @param {number[]} triangles - triangle indices
+     * @ignore
+     */
+    drawMesh(renderer: CanvasRenderer, image: HTMLImageElement, vertices: Float32Array, triangles: number[]): void;
+    /**
+     * Draw a single textured triangle using affine transform.
+     * @ignore
+     */
+    drawTriangle(renderer: any, img: any, x0: any, y0: any, u0: any, v0: any, x1: any, y1: any, u1: any, v1: any, x2: any, y2: any, u2: any, v2: any): void;
+    /**
+     * Compute world vertices for a mesh attachment with color and UV data.
+     * @param {Slot} slot
+     * @param {MeshAttachment} mesh
+     * @param {number} vertexSize - floats per vertex
+     * @ignore
+     */
+    computeMeshVertices(slot: Slot, mesh: MeshAttachment, vertexSize: number): void;
+}
+import { Color as MColor } from "melonjs";
+import { SkeletonClipping } from "@esotericsoftware/spine-core";
+import { Polygon } from "melonjs";
+import { RegionAttachment } from "@esotericsoftware/spine-core";
+import { MeshAttachment } from "@esotericsoftware/spine-core";
+//# sourceMappingURL=SkeletonRenderer.d.ts.map

package/build/SkeletonRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkeletonRenderer.d.ts","sourceRoot":"","sources":["../src/SkeletonRenderer.js"],"names":[],"mappings":"AA0BA;;;;;;GAMG;AACH;IACC;;;;;;;OAOG;IACH,mBAHU,OAAO,CAGS;IAE1B;;;;OAIG;IACH,gBAHU,OAAO,CAGM;IAGvB,kBAAyB;IACzB,kBAAyB;IAGzB,0BAAiC;IACjC,wBAAsB;IACtB,sBAIG;IAEH;;;;OAIG;IACH,eAHW,cAAc,YACd,QAAQ,QAiGlB;IAED;;;;;;;;;;OAUG;IACH,qBATW,cAAc,SACd,gBAAgB,QAChB,IAAI,cACJ,gBAAgB,UAChB,aAAa,QACb,OAAO,GAAC,IAAI,SACZ,OAAO,QAqDjB;IAED;;;;;;;OAOG;IACH,mBANW,cAAc,SACd,gBAAgB,YAChB,YAAY,aACZ,MAAM,EAAE,QA8BlB;IAED;;;OAGG;IACH,wJA2CC;IAED;;;;;;OAMG;IACH,0BALW,IAAI,QACJ,cAAc,cACd,MAAM,QAwChB;CACD;gCAlWuD,SAAS;iCAD1D,8BAA8B;wBACmB,SAAS;iCAD1D,8BAA8B;+BAA9B,8BAA8B"}