@sakia/spine

Spine runtime plugin for Sakia. Drives Spine 4.3 characters into Sakia **Track-B Mesh**es — not a GL bypass overlay — so they participate in layer management, the Render Queue, picking, and @sakia/physics like any other scene mesh. See ADR-026 and the guide SPINE_PLUGIN.md.

Design (ADR-026)

• Runtime is @esotericsoftware/spine-core (pinned ~4.3, renderer-agnostic). spine-webgl is deliberately not used — the previous bypass-overlay host was removed (ADR-023 obsolete).
• Each frame: AnimationState.update → apply → Skeleton.updateWorldTransform(Physics.update), then SkeletonRendererCore.render(skeleton, pma) produces a batched RenderCommand list. The mesh bridge writes each command into a Track-B Mesh (positions / uv / color / indices) with a cached Base2DMaterial per atlas page + blend mode.
• Coordinates are Sakia Y-up world units (ADR-013); Spine is Y-up too, so no flip is applied.

Install / dev resolution

peerDependencies: @sakia/core. The runtime resolves from @esotericsoftware/spine-core (npm). In the playground, a Vite alias can point @esotericsoftware/spine-core at a local spine-runtimes checkout for dev fidelity (see playground/vite.config.ts, SAKIA_SPINE_CORE_SRC).

Usage

import { enableSpine, SpineSkeletonInstance } from "@sakia/spine";

enableSpine(scene); // registers the SpineSystem scene component
const hero = await SpineSkeletonInstance.create(scene, {
  skeleton: "/assets/spine/spineboy/spineboy-pro.json",
  atlas:    "/assets/spine/spineboy/spineboy-pma.atlas",
}, { defaultAnimation: "idle", layerName: null });

hero.setAnimation(0, "walk", true);
const { x, y, width, height } = hero.getBounds();

Game physics layer on top via @sakia/physics (PhysicsAggregate); the demo drives the skeleton root from a dynamic body so the character falls onto a ground while animating.

Assets

Export with premultiplied alpha (*-pma.atlas + *-pma.png) — the default pma: true renders them with premultiplied blending. The Spine Editor License governs redistribution; see LICENSE.spine.

Upgrade (4.3 → 4.4 / 5.x)

1. Bump @esotericsoftware/spine-core in package.json.
2. Update SAKIA_SPINE_EDITOR_COMPAT in src/constants.ts.
3. Adjust src/internal/** adapters if the upstream API drifted.
4. Re-export assets from the new editor.
5. yarn sp:version-smoke.