[ts][player] Closes #2536, deprecate jsonURL, skelURL, and atlasURL in favor of skeleton and atlas fields.

CHANGELOG.md

@@ -113,6 +113,7 @@
 ## C#
 
 - **Additions**
+
   - Added [`TrackEntry.AlphaAttachmentThreshold`](http://esotericsoftware.com/spine-api-reference#TrackEntry-alphaAttachmentThreshold).
 
 - **Breaking changes**
@@ -156,7 +157,7 @@
   - SkeletonGraphic: Added auto-detect functionality for parameters `Advanced` - `Tint Black`, `CanvasGroup Compatible` and `PMA Vertex Color`. If unsure which settings are correct, hit the `Detect` button next to each parameter, in top to bottom order, or the `Detect Settings` to detect all three. Also added automatic material assignment via a `Detect Material` button in the `Advanced` section and a `Detect` button next to the `Material` property at the top of the component Inspector, as well as next to the `Blend Mode Materials` section when using multiple canvas renderers with blend modes. The suitable material is selected based on these three settings, combined with texture settings (PMA or straight alpha texture settings). If you receive incorrect results, likely your texture settings are incorrectly setup for your PMA or Straight alpha texture export settings.
   - `SkeletonRenderTexture` example components now provide a `shaderPasses` parameter to customize which passes are rendered to the `RenderTexture`. It defaults to `-1` for all passes to keep the existing behaviour. You might want to set it to `0` to only render the first pass e.g. to avoid issues when using a URP shader at the original skeleton.
   - `SkeletonGraphicRenderTexture` example component now also received a `quadMaterial` property, defaulting to the newly added Material asset `RenderQuadGraphicMaterial` which applies proper premultiplied-alpha blending of the render texture. The `quadMaterial` member variable was moved from `SkeletonRenderTexture` to the common base class `SkeletonRenderTextureBase`.
-  - All Spine Outline shaders, including the URP outline shader, now provide an additional parameter `Width in Screen Space`. Enable it to keep the outline width constant in screen space instead of texture space. Requires more expensive computations, so enable only where necessary.  Defaults to `disabled` to maintain existing behaviour.
+  - All Spine Outline shaders, including the URP outline shader, now provide an additional parameter `Width in Screen Space`. Enable it to keep the outline width constant in screen space instead of texture space. Requires more expensive computations, so enable only where necessary. Defaults to `disabled` to maintain existing behaviour.
 
 - **Breaking changes**
 
@@ -176,6 +177,7 @@
 - **Restructuring (Non-Breaking)**
 
 ### XNA/MonoGame
+
 - **Additions**
   - Apply external movement to physics: If you are not directly modifying `Skeleton.X` or `Skeleton.Y`, you can apply external game object movement to skeleton physics as follows:
     Add a `Vector2 lastPosition;` member variable to your class interacting with the skeleton. Then call e.g. the following code each frame:
@@ -263,6 +265,8 @@
 - Added physics support
 - Added `scale` field to configuration which defines the scale to load the skeleton at
 - Added `updateWorldTransform` field to configuration which expects a function that updates the skeleton. Defaults to player.skeleton.updateWorldTransform(spine.Physics.update)
+- Added `skeleton` to `SpinePlayerConfig` to specify the URL of the skeleton .json or .skel file. Deprecated `jsonURL` and `binaryURL`. The old fields can still be used, but will be removed in Spine 4.3
+- Added `atlas` to `SpinePlayerConfig` to specify the URL of the .atlas file. Deprecated `atlasURL`. The old field can still be used, but will be removed in Spine 4.3.
 
 ### Pixi
 

spine-ts/spine-player/example/dispose.html

@@ -24,8 +24,8 @@
 
 	function createPlayer() {
 		return new spine.SpinePlayer("container", {
-			skelUrl: "assets/spineboy-pro.skel",
-			atlasUrl: "assets/spineboy-pma.atlas",
+			skeleton: "assets/spineboy-pro.skel",
+			atlas: "assets/spineboy-pma.atlas",
 			animation: "run",
 			premultipliedAlpha: true,
 			backgroundColor: "#cccccc",

spine-ts/spine-player/example/editor.html

@@ -1,24 +1,27 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <script src="../dist/iife/spine-player.js"></script>
-    <link rel="stylesheet" href="../../index.css" />
-    <title>Spine Player Editor</title>
-  </head>
-  <body class="flex flex-col w-full h-screen items-center">
-    <div id="editor" class="w-full h-full flex-grow"></div>
 
-    <script>
-      var code =
-        '<script src="https://unpkg.com/@esotericsoftware/[email protected].*/dist/iife/spine-player.js"></' +
-        'script>\n<link rel="stylesheet" href="https://unpkg.com/@esotericsoftware/[email protected].*/dist/spine-player.css">\n\n<div id="player-container" style="width: 100%; height: 100vh;"></div>\n\n<script>\nnew spine.SpinePlayer("player-container", {\n	jsonUrl: "http://esotericsoftware.com/files/examples/4.1/spineboy/export/spineboy-pro.json",\n	atlasUrl: "http://esotericsoftware.com/files/examples/4.1/spineboy/export/spineboy.atlas"\n});\n</' +
-        "script>".trim();
-      spine.SpinePlayerEditor.DEFAULT_CODE = code;
-      var player = new spine.SpinePlayerEditor(
-        document.getElementById("editor")
-      );
-    </script>
-  </body>
-</html>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <script src="../dist/iife/spine-player.js"></script>
+  <link rel="stylesheet" href="../../index.css" />
+  <title>Spine Player Editor</title>
+</head>
+
+<body class="flex flex-col w-full h-screen items-center">
+  <div id="editor" class="w-full h-full flex-grow"></div>
+
+  <script>
+    var code =
+      '<script src="https://unpkg.com/@esotericsoftware/[email protected].*/dist/iife/spine-player.js"></' +
+      'script>\n<link rel="stylesheet" href="https://unpkg.com/@esotericsoftware/[email protected].*/dist/spine-player.css">\n\n<div id="player-container" style="width: 100%; height: 100vh;"></div>\n\n<script>\nnew spine.SpinePlayer("player-container", {\n	skeleton: "http://esotericsoftware.com/files/examples/4.1/spineboy/export/spineboy-pro.json",\n	atlas: "http://esotericsoftware.com/files/examples/4.1/spineboy/export/spineboy.atlas"\n});\n</' +
+      "script>".trim();
+    spine.SpinePlayerEditor.DEFAULT_CODE = code;
+    var player = new spine.SpinePlayerEditor(
+      document.getElementById("editor")
+    );
+  </script>
+</body>
+
+</html>

spine-ts/spine-player/example/example.html

@@ -24,8 +24,8 @@
 	// Creates a new spine player. The debugRender option enables
 	// rendering of viewports and padding for debugging purposes.
 	new spine.SpinePlayer("container", {
-		skelUrl: "assets/spineboy-pro.skel",
-		atlasUrl: "assets/spineboy-pma.atlas",
+		skeleton: "assets/spineboy-pro.skel",
+		atlas: "assets/spineboy-pma.atlas",
 		animation: "run",
 		premultipliedAlpha: true,
 		backgroundColor: "#cccccc",
@@ -42,8 +42,8 @@
 	// so content from the website shines through. Hides the controls.
 	// Instead, the user can control the animation via buttons.
 	var jsControlledPlayer = new spine.SpinePlayer("container-raptor", {
-		jsonUrl: "assets/raptor-pro.json",
-		atlasUrl: "assets/raptor-pma.atlas",
+		skeleton: "assets/raptor-pro.json",
+		atlas: "assets/raptor-pma.atlas",
 		animation: "walk",
 		showControls: false,
 		premultipliedAlpha: true,

spine-ts/spine-player/example/physics.html

@@ -1,47 +1,50 @@
 <!DOCTYPE html>
 <html>
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <script src="../dist/iife/spine-player.js"></script>
-    <link rel="stylesheet" href="../dist/spine-player.css" />
-    <link rel="stylesheet" href="../../index.css" />
-  </head>
-  <body style="margin: 0">
-    <span class="overlay">Drag the swinging lady</span>
-    <div id="player" style="width: 100%; height: 100vh"></div>
-    <script>
-      var mouse = new spine.Vector3(),
-        last = new spine.Vector3();
-      new spine.SpinePlayer("player", {
-        skelUrl: "assets/celestial-circus-pro.skel",
-        atlasUrl: "assets/celestial-circus-pma.atlas",
-        showControls: true,
-        animation: "swing",
-        success: (player) => {
-          new spine.Input(player.canvas).addListener({
-            down: (x, y) => {
-              player.sceneRenderer.camera.screenToWorld(
-                mouse.set(x, y, 0),
-                player.canvas.clientWidth,
-                player.canvas.clientHeight
-              );
-              last.setFrom(mouse);
-            },
-            dragged: (x, y) => {
-              player.sceneRenderer.camera.screenToWorld(
-                mouse.set(x, y, 0),
-                player.canvas.clientWidth,
-                player.canvas.clientHeight
-              );
-              player.skeleton.getRootBone().x += mouse.x - last.x;
-              player.skeleton.getRootBone().y += mouse.y - last.y;
-              last.setFrom(mouse);
-            },
-            up: () => (player.paused = false),
-          });
-        },
-      });
-    </script>
-  </body>
-</html>
+
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <script src="../dist/iife/spine-player.js"></script>
+  <link rel="stylesheet" href="../dist/spine-player.css" />
+  <link rel="stylesheet" href="../../index.css" />
+</head>
+
+<body style="margin: 0">
+  <span class="overlay">Drag the swinging lady</span>
+  <div id="player" style="width: 100%; height: 100vh"></div>
+  <script>
+    var mouse = new spine.Vector3(),
+      last = new spine.Vector3();
+    new spine.SpinePlayer("player", {
+      skeleton: "assets/celestial-circus-pro.skel",
+      url: "assets/celestial-circus-pma.atlas",
+      showControls: true,
+      animation: "swing",
+      success: (player) => {
+        new spine.Input(player.canvas).addListener({
+          down: (x, y) => {
+            player.sceneRenderer.camera.screenToWorld(
+              mouse.set(x, y, 0),
+              player.canvas.clientWidth,
+              player.canvas.clientHeight
+            );
+            last.setFrom(mouse);
+          },
+          dragged: (x, y) => {
+            player.sceneRenderer.camera.screenToWorld(
+              mouse.set(x, y, 0),
+              player.canvas.clientWidth,
+              player.canvas.clientHeight
+            );
+            player.skeleton.getRootBone().x += mouse.x - last.x;
+            player.skeleton.getRootBone().y += mouse.y - last.y;
+            last.setFrom(mouse);
+          },
+          up: () => (player.paused = false),
+        });
+      },
+    });
+  </script>
+</body>
+
+</html>

spine-ts/spine-player/src/Player.ts

@@ -31,23 +31,29 @@ import { Animation, AnimationState, AnimationStateData, AtlasAttachmentLoader, B
 import { AssetManager, GLTexture, Input, LoadingScreen, ManagedWebGLRenderingContext, ResizeMode, SceneRenderer, Vector3 } from "@esotericsoftware/spine-webgl"
 
 export interface SpinePlayerConfig {
-	/* The URL of the skeleton JSON file (.json). Undefined if binaryUrl is given. */
+	/* The URL of the skeleton JSON (.json) or binary (.skel) file */
+	skeleton?: string;
+
+	/* @deprecated Use skeleton instead. The URL of the skeleton JSON file (.json). Undefined if binaryUrl is given. */
 	jsonUrl?: string
 
 	/* Optional: The name of a field in the JSON that holds the skeleton data. Default: none */
 	jsonField?: string
 
-	/* The URL of the skeleton binary file (.skel). Undefined if jsonUrl is given. */
+	/* @deprecated Use skeleton instead. The URL of the skeleton binary file (.skel). Undefined if jsonUrl is given. */
 	binaryUrl?: string
 
 	/* The scale when loading the skeleton data. Default: 1 */
 	scale?: number
 
-	/* The URL of the skeleton atlas file (.atlas). Atlas page images are automatically resolved. */
+	/* @deprecated Use atlas instead. The URL of the skeleton atlas file (.atlas). Atlas page images are automatically resolved. */
 	atlasUrl?: string
 
-	/* Raw data URIs, mapping a path to base64 encoded raw data. When player's asset manager resolves the jsonUrl, binaryUrl,
-	   atlasUrl, or the image paths referenced in the atlas, it will first look for that path in the raw data URIs. This
+	/* The URL of the skeleton atlas file (.atlas). Atlas page images are automatically resolved. */
+	atlas?: string;
+
+	/* Raw data URIs, mapping a path to base64 encoded raw data. When player's asset manager resolves the skeleton,
+	   atlas, or the image paths referenced in the atlas, it will first look for that path in the raw data URIs. This
 	   allows embedding assets directly in HTML/JS. Default: none */
 	rawDataURIs?: StringMap<string>
 
@@ -285,10 +291,14 @@ export class SpinePlayer implements Disposable {
 
 	private validateConfig (config: SpinePlayerConfig) {
 		if (!config) throw new Error("A configuration object must be passed to to new SpinePlayer().");
-		if ((config as any).skelUrl) config.binaryUrl = (config as any).skelUrl;
-		if (!config.jsonUrl && !config.binaryUrl) throw new Error("A URL must be specified for the skeleton JSON or binary file.");
+		if (!config.skeleton && !config.jsonUrl && !config.binaryUrl) throw new Error("A URL must be specified for the skeleton JSON or binary file.");
 		if (!config.scale) config.scale = 1;
-		if (!config.atlasUrl) throw new Error("A URL must be specified for the atlas file.");
+		if (!config.atlas && !config.atlasUrl) throw new Error("A URL must be specified for the atlas file.");
+
+		if (config.jsonUrl && !config.skeleton) config.skeleton = config.jsonUrl;
+		if (config.binaryUrl && !config.skeleton) config.skeleton = config.binaryUrl;
+		if (config.atlasUrl && !config.atlas) config.atlas = config.atlasUrl;
+
 		if (!config.backgroundColor) config.backgroundColor = config.alpha ? "00000000" : "000000";
 		if (!config.fullScreenBackgroundColor) config.fullScreenBackgroundColor = config.backgroundColor;
 		if (config.backgroundImage && !config.backgroundImage.url) config.backgroundImage = undefined;
@@ -346,11 +356,11 @@ export class SpinePlayer implements Disposable {
 			for (let path in config.rawDataURIs)
 				this.assetManager.setRawDataURI(path, config.rawDataURIs[path]);
 		}
-		if (config.jsonUrl)
-			this.assetManager.loadJson(config.jsonUrl);
+		if (config.skeleton!.endsWith(".json"))
+			this.assetManager.loadJson(config.skeleton!);
 		else
-			this.assetManager.loadBinary(config.binaryUrl!);
-		this.assetManager.loadTextureAtlas(config.atlasUrl!);
+			this.assetManager.loadBinary(config.skeleton!);
+		this.assetManager.loadTextureAtlas(config.atlas!);
 		if (config.backgroundImage) this.assetManager.loadTexture(config.backgroundImage.url);
 
 		// Setup the UI elements.
@@ -442,7 +452,7 @@ export class SpinePlayer implements Disposable {
 		let config = this.config;
 
 		// Configure filtering, don't use mipmaps in WebGL1 if the atlas page is non-POT
-		let atlas = this.assetManager!.require(config.atlasUrl!) as TextureAtlas;
+		let atlas = this.assetManager!.require(config.atlas!) as TextureAtlas;
 		let gl = this.context!.gl, anisotropic = gl.getExtension("EXT_texture_filter_anisotropic");
 		let isWebGL1 = gl.getParameter(gl.VERSION).indexOf("WebGL 1.0") != -1;
 		for (let page of atlas.pages) {
@@ -466,8 +476,8 @@ export class SpinePlayer implements Disposable {
 		let skeletonData: SkeletonData;
 		try {
 			let loader: any, data: any, attachmentLoader = new AtlasAttachmentLoader(atlas);
-			if (config.jsonUrl) {
-				data = this.assetManager!.remove(config.jsonUrl);
+			if (config.skeleton!.endsWith(".json")) {
+				data = this.assetManager!.remove(config.skeleton!);
 				if (!data) throw new Error("Empty JSON data.");
 				if (config.jsonField) {
 					data = data[config.jsonField];
@@ -475,7 +485,7 @@ export class SpinePlayer implements Disposable {
 				}
 				loader = new SkeletonJson(attachmentLoader);
 			} else {
-				data = this.assetManager!.remove(config.binaryUrl!);
+				data = this.assetManager!.remove(config.skeleton!);
 				loader = new SkeletonBinary(attachmentLoader);
 			}
 			loader.scale = config.scale;