spine-ts: One runtime to serve all your HTML5 needs!

August 18th, 2016

In our recent quest to update all our runtimes, we have decided to give the spine-js runtime a complete overhaul. JavaScript doesn't lend itself well to maintainability, mostly due to its dynamic typing nature, so we now have completely rewritten spine-ts using TypeScript.

We are generally quite conservative here at Esoteric Software when it comes to following hyped technology and fads. But TypeScript is different. It is a strict super set of JavaScript and also compiles down to very pretty, easily debuggable JavaScript. TypeScript allows gradual or full typing, depending on your taste. It also comes with integrations for editors and IDEs such as Visual Studio Code and IntelliJ IDEA/WebStorm, which allows refactoring and excellent code navigation. For our spine-js overhaul, we've decided to give TypeScript a try, and it turned out wonderfully!

Instead of a ball of spaghetti, the new spine-ts runtime is fully typed, modular, and maintainable. The output is plain old JavaScript, which itself looks pretty nice and is easily consumable from JavaScript, TypeScript, or any other compile-to-JavaScript language you may use.

Let's see what spine-ts has in store!

Deprecating spine-ts and spine-threejs

This will probably not come as a shocker, but we are deprecating the old spine-js and spine-threejs runtimes in favor of spine-ts. You can find the latest versions of both deprecated runtimes in the spine-js branch and spine-threejs branch respectively. Going forward, neither one of the deprecated runtimes will receive any updates from our end. We've engineered spine-ts in such a way that switching over should be very simple.

An overview of spine-ts

spine-ts consists of multiple modules:

• core, this is the generic TypeScript/JavaScript runtime and a direct port of the reference spine-libgdx runtime.
• canvas, an HTML5 Canvas based backend, built on top of core.
• webgl, an HTML5 WebGL based backend, built on top of core, with a libGDX-like abstraction of all things WebGL.
• threejs, a THREE.js backend.
• widget, an embeddable HTML5 WebGL based widget, making it extremely simple to show off your Spine animations on your own website.

Each module comes with its own tsconfig.json file, which will instruct the TypeScript compiler to output a single JavaScript file once the sources are compiled. E.g. the tsconfig.webgl.json file will produce the file build/spine-webgl.json which you can simply include in your HTML5 app via a script tag. Check out the spine-ts README in case you want to modify and recompile the TypeScript sources yourself. We push up-to-date JavaScript files to the spine-ts/build/ directory for your convenience.

Let's have a look at each module individually.

spine-ts core

The spine-ts core module constitutes a direct port of the core classes of spine-libgdx. The port is extremely faithful, making it very simple to translate the samples from the generic runtime documentation to the spine-ts API. All classes are contained in their own spine scope as to not pollute the global scope of your HTML5 application.

spine-ts also comes with a simple, built-in asset manager implementation. It provides asynchronous loading of text files and images, translating the images into whatever format is required for a specific backend, e.g. a WebGL texture for the WebGL backend. Each backend derives from the core AssetManager to do the magic conversion from HTMLImageElement to whatever the backend needs to display images. If you want to use your own loading mechanism that's fine too, none of the core classes depend on AssetManager.

Unlike the old spine-js runtime, spine-ts also knows how to read texture atlases, making the ergonomics of spine-ts much better. Instead of having to individually load every image used in your animation, spine-ts can simply read a texture atlas you export from Spine, like any other runtime.

spine-ts Canvas

The spine-ts canvas module is a backend targeting the HTML5 Canvas API. Check out the spine-ts HTML5 Canvas example:

Due to the limitations of the Canvas API, shearing, mesh attachments, and tinting are not possible and therefore not supported. If you really want mesh attachments, we have included an experimental renderer that can render meshes. While it works correctly in Google Chrome, it may exhibit filtering artifacts along triangle edges in some other browsers.

spine-ts WebGL

The spine-ts WebGL module is a backend targeting the HTML5 WebGL API. It supports all spine features, including shearing, mesh attachments, tinting, and premultiplied alpha.

Integration of spine-ts WebGL into your own WebGL based application is extremely simple. All you need to do is pass a WebGLRenderingContext to the spine-ts WebGL classes like SkeletonRenderer and spine-ts will do the rest. We've created a nice abstraction over WebGL shaders, meshes, and so forth that you can reuse for your own app. Check out the spine-ts WebGL sources to see what's available.

Check out the spine-ts HTML5 WebGL example.

spine-ts THREE.js

The spine-js THREE.js module is a backend targeting THREE.js, the most popular higher-level 3D API for the web. It currently lacks support for tinting, premultiplied alpha, advanced blending functions, and multi-page texture atlases.

You can simply load SkeletonData, then create a SkeletonMesh and attach it to your THREE.js scene. The backend will do the rest.

Check out the spine-ts HTML5 THREE.js example.

spine-ts Widget

For our final trick, we've created an extremely easy to use widget that allows you to embed Spine animations directly on your website, with zero coding. Just include the spine-widget.js script, add a div or any other element to your site, give it the class spine-widget and specify the .jsonand .atlas file and the animation you want to play. E.g.:

Which would result in:

The raptor is offset to the right a little, as the widget uses the setup pose bounding box to automatically scale and center the animation, whereas the bounding box of the walking animation is a bit to the right. You can set data-fit-to-canvas to false and provide your own translation and scale.

By default, the widget will load all animations for elements having the spine-widget class. You can also programmatically load animations dynamically. Check out the spine-ts Widget example to see more usage patterns, including changing animations, etc.

Next Up

With the JavaScript runtime having been completely brought up to speed, only the spine-lua runtime needs some more love. We hope to have that work complete within the next few weeks.

Let us know what you think about these new additions on the Spine forum!