Ligamen Unity Runtime
Package com.ligamen.unity · version 1.0.0 · Unity 2018.3+
Unity runtime for skeletons exported from Ligamen Studio or Spine (format versions 4.0, 4.1, 4.2, 4.3; JSON and binary .skel.bytes). It is its own implementation: no spine-csharp / spine-unity code, and it can live next to the official spine-unity package in one project (assemblies and namespaces Ligamen.*).
State (1.0.0): the runtime is feature-complete against spine-unity 4.3 and is checked against the official runtimes in Unity (batchmode test labs).
- Formats: Spine 4.0, 4.1, 4.2, 4.3 JSON and binary, Ligamen Studio exports of the same versions, the atlas (multi-page, PMA and straight alpha); one runtime and one data model for every version (
Ligamen.Core, noUnityEngine). - Pose: bones, slots, skins, all attachment types (region, mesh, linked mesh, clipping, bounding box, path, point, sequences), IK, transform (4.3 mapping), path, physics (4.2+) and slider (4.3) constraints,
AnimationStatewith the rules of each version (mix, additive, events, attachment / draw order thresholds). - Unity: importer, Scene (
MeshRenderer) and Canvas components, Animator (Mecanim), Timeline, root motion, followers and SkeletonUtility, animation events and audio, Built-in / URP / HDRP shaders (tint black, blend modes, separators). - Checked: poses, meshes, images and the Unity components against spine-csharp / spine-unity 4.0–4.3 (golden data and conformance tests in the labs; the list of checks —
docs/unity-manual-checks/README.mdof the Ligamen repository). Frame time against spine-unity 4.3 (decision D9,tools/unity_perf.sh): Scene, Canvas, Mecanim and Timeline 0.71–0.98× on spineboy / raptor / Kuzya, no managed allocations per frame. - Declared supported (1.0.0): Spine 4.0, 4.1, 4.2 and 4.3 data (JSON and binary) and Ligamen Studio exports of the same versions; Unity 2018.3 and later, tested on 6000.3.1f1 with Built-in, URP 17.3 and HDRP 17.3. All 57 checks of the registry passed (4.0 / 4.2 / 4.3 against spine-unity of that version; 4.1 through the pose golden of the mixed 4.0–4.3 sets).
Install
Unity Package Manager → Add package from git URL: <repository>.git?path=/unity/com.ligamen.unity, or Add package from disk with unity/com.ligamen.unity/package.json of a local checkout.
Unity versions
Minimum: 2018.3 (the unity field of official spine-unity 4.0–4.3, decision D3). Actually tested on Unity 6000.3.1f1 (Built-in, URP 17.3, HDRP 17.3).
Assemblies
| Assembly | Contents |
|---|---|
Ligamen.Core | formats, data model, pose, animation; no UnityEngine (noEngineReferences) |
Ligamen.Unity | assets and components |
Ligamen.Unity.UI | Canvas component (only with com.unity.ugui) |
Ligamen.Unity.Editor | importer and inspectors (Editor only) |
Ligamen.Core.Tests, Ligamen.Unity.Tests | NUnit tests (testables) |
The core is also built and tested outside Unity: tools/unity_core_test.sh in the Ligamen repository (dotnet test, netstandard2.0, C# 7.3).
Import
Put the export (.json or .skel.bytes, .atlas.txt, page PNGs) into one folder under Assets/. Select the skeleton and use Assets → Ligamen → Import Skeleton: it creates <skeleton>_LigamenSkeletonData.asset, <atlas>_LigamenAtlas.asset and one <atlas>_<page>_LigamenMaterial.mat per page. Assets → Ligamen → Automatic Import imports new skeletons on their own (on by default only when spine-unity is not installed). Reimport updates the assets in place; errors are listed in the Console and write nothing.
Play
Add Ligamen → Ligamen Skeleton Animation to a GameObject, assign the skeleton data asset and pick a skin and an animation in the inspector. From C#: GetComponent<LigamenSkeletonAnimation>().AnimationName = "run"; or .AnimationState.SetAnimation(0, "run", true); Skeleton gives bones and slots.
Inside a Canvas use Ligamen → Ligamen Skeleton Graphic (needs com.unity.ugui): same inspector and API, masks and CanvasGroup work; extra atlas pages are drawn by hidden child canvas renderers.
Animator (Mecanim): select the skeleton data asset → Assets → Ligamen → Generate Mecanim Controller (a wrapper clip per animation), build states in the controller, then add Ligamen → Ligamen Skeleton Mecanim next to Ligamen Skeleton Animation (an Animator is added) — the Animator drives the skeleton; Auto Reset and Custom MixMode per layer as in spine-unity's SkeletonMecanim. Outside Play Mode, scrubbing a wrapper clip in the Animation window (Preview on) poses the skeleton at that time (Scene and Canvas); turning Preview off returns it to the Animator.
Timeline (with com.unity.timeline installed; the Ligamen.Unity.Timeline assembly builds only then): add a Ligamen Animation State Track bound to a Ligamen Skeleton Animation and put Ligamen Animation State Clips on it (animation name, loop, mix settings, Don't End with Clip, Clip End Mix Out Duration, thresholds, alpha — as spine-unity's Timeline clip). In Play Mode each clip starts its animation on the track index; scrubbing the Timeline in the Editor poses the skeleton. Track option Unscaled Time sets the component's unscaledTime. For a Canvas use Ligamen Animation State Graphic Track (binds a Ligamen Skeleton Graphic; needs uGUI). With the director open in the Timeline window, the clip Inspector lists the bound skeleton's animations and the clip shows the animation as its caption (an unknown name is marked as an error). Ligamen Skeleton Flip Track (bound to the skeleton's GameObject) flips it along X / Y while its clips are active and restores the start scale outside them.
Events: add Ligamen → Ligamen Animation Events next to either component for UnityEvents per skeleton event and per track start / complete / end; audio events play the clip bound to their audio path (context menu Find Audio Clips binds them by file name).
Root motion: Ligamen → Ligamen Skeleton Root Motion (next to Ligamen Skeleton Animation or Graphic) or Ligamen Skeleton Mecanim Root Motion (with Ligamen Skeleton Mecanim) moves the GameObject — or its Rigidbody2D / Rigidbody — by the root bone's animated translation, as spine-unity's SkeletonRootMotion components.
Followers: Ligamen Bone Follower / Point Follower / Bounding Box Follower (and the Graphic variants for a Canvas) keep a GameObject on a bone, a point attachment or a bounding box (polygon colliders per attachment). Ligamen Skeleton Utility spawns a GameObject hierarchy for the bones (Ligamen Skeleton Utility Bone: Follow or Override with a mix); custom constraints derive from LigamenSkeletonUtilityConstraint.
Physics constraints (Spine 4.2+) simulate in the components' update; Ligamen Physics Movement makes them react to the GameObject moving and turning.
Rendering: the Ligamen/Skeleton and Ligamen/SkeletonGraphic shaders work in the Built-in pipeline, URP and HDRP (straight / premultiplied alpha, tint black, blend mode materials); a skeleton can be split into parts at separator slots (separator slots of Ligamen Skeleton Animation: one child part renderer per part, as spine-unity's SkeletonPartsRenderer).
Scripting API: see Scripting API below.
License
Source-available, not open source: License Agreement (Ligamen Unity Runtime License Agreement, also at https://ligamenstudio.com/legal/unity-runtime-license; Russian translation русский перевод). Governed by the laws of England and Wales, disputes by SIAC arbitration (Singapore). You may use, modify and ship the runtime inside your own games and applications. Using this runtime does not require a Ligamen Studio license. Creating or editing content with Ligamen Studio requires a license for that editor under the terms of the edition used; third-party or Spine content does not require a Ligamen Studio license merely because this runtime plays it. The runtime may not be redistributed as a standalone package or used as the basis of a competing animation tool, and its notices must stay. Other tools and content remain subject to their own licenses. The linked license applies to copies obtained from Git or the Ligamen website; Unity Asset Store distribution is subject to that store's terms and may require Unity's approval of separate terms.
Scripting API
Spine version detection
using Ligamen.Core;
SpineVersion v = SpineVersion.Detect(File.ReadAllBytes(path)); // JSON or binary
// v.Full = "4.2.43", v.Profile = "4.2", v.Format = SpineDataFormat.Binary
- JSON: version from
skeleton.spine; binary: header (64-bit hash, then the version string). - Readable profiles:
SpineVersion.SupportedProfiles= 4.0, 4.1, 4.2, 4.3. The patch part does not matter; the major.minor does (a binary is read only by a reader of the same major.minor). - Anything else throws
UnsupportedSpineVersionException(.Version= the string from the file) orLigamenFormatExceptionfor broken data; the message names what was found.
Skeleton data (Spine 4.3 JSON)
using Ligamen.Core;
using Ligamen.Core.Json;
SkeletonData data = SkeletonJson43.Read(File.ReadAllText(path));
BoneData hip = data.FindBone("hip");
var mesh = data.DefaultSkin.GetAttachment(data.FindSlot("torso").Index, "torso") as MeshAttachment;
- One model for every format version: bones, slots, skins (attachments by slot and placeholder name), events, constraints (
IkConstraintData,TransformConstraintData,PathConstraintData,PhysicsConstraintData,SliderConstraintData, in update order). - Missing keys take the Spine format defaults. A file of another version, an unknown bone / slot / skin / constraint / attachment type or bad geometry throws
LigamenFormatExceptionwith the place in the file, e.g.bones[1] 'arm': parent bone 'body' not found. - Animations (
SkeletonData.Animations): timelines of bones, slots, constraints (ik, transform, path, physics, slider), deform / sequence, draw order (+ 4.3 folders) and events, with key values and curves (linear / stepped / bezier) as stored in the file. Playback comes next.
Skeleton data (Spine 4.3 binary)
using Ligamen.Core.Binary;
SkeletonData data = SkeletonBinary43.Read(File.ReadAllBytes(path)); // .skel / .skel.bytes
- Same model, defaults and checks as the JSON reader (
ReadDocumentgives the equivalent 4.3 JSON document);data.Version.FormatisSpineDataFormat.Binary. - A truncated or corrupted file throws
LigamenFormatExceptionwith the byte offset (Unexpected end of data: the file is truncated (at byte 5000)).
Other format versions (4.0, 4.1, 4.2)
Each version has its own JSON and binary reader into the same model: SkeletonJson40 / SkeletonJson41 / SkeletonJson42 and SkeletonBinary40 / SkeletonBinary41 / SkeletonBinary42. A reader accepts only its own version (SpineVersion.Detect tells which one a file needs); another version throws LigamenFormatException.
Coexistence with spine-unity
Assemblies Ligamen.*, namespaces Ligamen.Core / Ligamen.Unity; components and assets are prefixed Ligamen…. When spine-unity is installed (LIGAMEN_SPINE_UNITY_PRESENT), the Ligamen importer does not claim .json / .skel.bytes by itself (from slice E14).