A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file SpineRuntime.hpp
* @brief What a vendored Spine runtime owes the module, and nothing more.
*
* @details SpineModuleEntry.cpp implements the exported ABI (SpineBindings.hpp):
* handle tables, batch packing, the string and event buffers the caller
* reads back. None of that changes with the Spine release. Everything
* that does — the runtime's own types, its spelling of "update the world
* transform", whether slot colour is a struct or four floats — lives
* behind this header, implemented once per vendored runtime.
*
* Exactly one implementation links into a binary: the web ships a module
* per version (spine38 / spine41 / spine42 / spine43) and a native host
* compiles the one its project needs. Selection is therefore a link-time
* fact, not a runtime one — no vtable, no dispatch, and a backend that
* forgets a function fails to link rather than failing on a device.
*
* Skeleton and Instance stay incomplete here on purpose: the entry layer
* only ever holds them by pointer, so it cannot reach into a runtime's
* structs and quietly grow a dependency on one release's layout.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
#include <cstdint>
#include <memory>
#include <string>
#include "./SkeletalModule.hpp"
// The namespace this release's backend lives in. A web side module carries one
// release and keeps the plain name; a native host carries every release, so its
// build compiles each backend with its own (spine38, spine42, …), the same way
// each spine-c release gets its own C names (native/spine/SpineCRename*.hpp).
#ifndef ES_SPINE_NS
#define ES_SPINE_NS spine
#endif
namespace es::ES_SPINE_NS {
/** A loaded skeleton: its atlas, its data, and the mix table instances share. */
struct Skeleton;
/** One posable copy of a Skeleton, with its own animation state. */
struct Instance;
void destroy(Skeleton* skeleton);
void destroy(Instance* instance);
/// Owning handles, so every error path that bails mid-construct still frees.
struct SkeletonDeleter {
void operator()(Skeleton* p) const { destroy(p); }
};
struct InstanceDeleter {
void operator()(Instance* p) const { destroy(p); }
};
using SkeletonPtr = std::unique_ptr<Skeleton, SkeletonDeleter>;
using InstancePtr = std::unique_ptr<Instance, InstanceDeleter>;
enum class ConstraintKind { Ik, Transform, Path };
/**
* Constraint mix weights, always per-axis. 4.0 split the old single rotate /
* translate / scale / shear mixes into these; a runtime that predates the split
* folds them back on the way in and mirrors them on the way out, so the SDK sees
* one shape whatever it loaded.
*/
struct TransformMix {
float rotate = 0.0f, x = 0.0f, y = 0.0f;
float scaleX = 0.0f, scaleY = 0.0f, shearY = 0.0f;
};
struct PathMix {
float position = 0.0f, spacing = 0.0f;
float rotate = 0.0f, x = 0.0f, y = 0.0f;
};
/**
* Animation-state events, numbered as the SDK decodes them (SPINE_TYPE_MAP in
* SpinePlugin.ts). The numbering is 4.x's; runtimes that number their own enum
* differently translate onto this rather than making the SDK guess which
* dialect it is talking to.
*/
enum class EventKind {
Start = 0,
Interrupt = 1,
End = 2,
Complete = 3,
Dispose = 4,
Event = 5,
};
struct Event {
const void* source = nullptr;
EventKind kind = EventKind::Event;
int track = 0;
float floatValue = 0.0f;
int intValue = 0;
/// Borrowed from the runtime's own data — valid until the skeleton unloads.
const char* animation = nullptr;
const char* name = nullptr;
const char* stringValue = nullptr;
};
/// The module is a singleton, so its collector is process-wide rather than per instance.
using EventSink = void (*)(const Event&);
const void* eventSource(Instance* instance);
/**
* Where a backend pours the triangles it posed. The sink batches: it decides when
* a texture or blend change starts a new batch and when one has filled up, so that
* policy is written once instead of once per runtime.
*
* `positions` and `uvs` are x,y / u,v interleaved; `indices` index into them. One
* colour covers the emission — Spine's colour is per attachment (skeleton × slot ×
* attachment), so a per-vertex array would carry the same value repeated.
*
* `blendMode` is 0 normal, 1 additive, 2 multiply, 3 screen, and 4 / 5 for the
* premultiplied twins of the first two, which is how the engine's renderer reads it.
*/
/// The shared one (SkeletalModule.hpp): batching is not a Spine idea, and the
/// backends below name this type, so it stays spelled `es::ES_SPINE_NS::TriangleSink`.
using TriangleSink = es::skeletal::TriangleSink;
/**
* How PREMULTIPLIED artwork changes what a slot emits — one rule, because both
* backends below face the same question and used to answer it separately.
*
* An atlas page declares `pma: true` when its pixels are stored premultiplied.
* Two things follow, and Spine's own runtimes (spine-libgdx SkeletonRenderer,
* spine-glfw) settle both:
*
* 1. THE BLEND FUNCTION, but only for two of the four modes. Normal and Additive
* have premultiplied twins — their source factor becomes ONE, which is what
* blend codes 4 and 5 are. Multiply and Screen use the SAME function either
* way (DST_COLOR / ONE already ignore the source alpha), so they pass through
* unchanged; that is Spine's table, not a simplification of it.
*
* 2. THE TINT, for EVERY mode. The shader multiplies a premultiplied texel by
* the emitted colour, and that product is only itself premultiplied when the
* colour is — so the tint's rgb must carry its alpha. Gating this on the
* blend code instead (the two modes that got a twin) leaves a Multiply or
* Screen slot with a straight tint over premultiplied pixels, and it stops
* fading correctly as its alpha animates.
*/
inline bool blendHasPremultipliedTwin(int slotBlend) {
return slotBlend == 0 || slotBlend == 1; // normal, additive
}
/// The blend code to emit for a slot's mode on a page of the given kind (see above).
inline int blendForPage(int slotBlend, bool pagePremultiplied) {
return pagePremultiplied && blendHasPremultipliedTwin(slotBlend) ? slotBlend + 4 : slotBlend;
}
/// Fold the tint's alpha into its rgb — required for every slot on a premultiplied
/// page, and a no-op on any other. Call with the SAME flag `blendForPage` got.
inline void premultiplyTint(float rgba[4], bool pagePremultiplied) {
if (!pagePremultiplied) return;
rgba[0] *= rgba[3];
rgba[1] *= rgba[3];
rgba[2] *= rgba[3];
}
// --- resources -------------------------------------------------------------
/** Returns null and fills `error` when the atlas or the skeleton data is unreadable. */
Skeleton* loadSkeleton(const void* skeletonData, int length,
const char* atlasText, int atlasLength,
bool binary, std::string& error);
int atlasPageCount(const Skeleton* skeleton);
const char* atlasPageName(const Skeleton* skeleton, int page);
void setAtlasPageTexture(Skeleton* skeleton, int page, uint32_t texture, int width, int height);
void setDefaultMix(Skeleton* skeleton, float seconds);
void setMixDuration(Skeleton* skeleton, const char* from, const char* to, float seconds);
// --- instances -------------------------------------------------------------
Instance* createInstance(Skeleton* skeleton);
/**
* Advance the animation clock onto the bones' LOCAL transforms — track time,
* mixing, events, attachment and draw-order timelines, none of it world space.
* A fifth of a pose, so nothing that skips frames should skip this.
*/
void advanceAndApply(Instance* instance, float dt);
/**
* Resolve the bones' WORLD transforms from the local ones, constraints and all:
* four fifths of a pose, and the only part a frame nobody sees has no use for.
* `dt` is read only where the skeleton carries stateful physics — see
* {@link requiresContinuousWorldPose} for when deferring this is the same thing.
*/
void materializeWorldPose(Instance* instance, float dt);
/** {@link advanceAndApply} then {@link materializeWorldPose} — a whole frame. */
void update(Instance* instance, float dt);
/**
* Whether this skeleton's world pose carries state from the last one, so it may
* never be deferred. The runtime answers for its own version rather than a
* caller reasoning about which constraints a Spine release has: IK, transform
* and path solve the current local pose; physics integrates, and cannot.
*/
bool requiresContinuousWorldPose(const Skeleton* skeleton);
/** How long one animation runs, so a scan over it can know when it is done
* rather than sampling for a while and hoping. Negative if there is no such
* animation. */
float animationDuration(const Skeleton* skeleton, const char* animation);
/**
* Put the skeleton back where its data says it starts, and clear every track.
*
* `playAnimation` resets nothing, so a bone the new animation does not key keeps
* what the last pose left — and replaying to one time twice gives two poses.
* This is the one state a run is reproducible from.
*/
void setToSetupPose(Instance* instance);
bool playAnimation(Instance* instance, const char* animation, bool loop, int track);
bool addAnimation(Instance* instance, const char* animation, bool loop, float delay, int track);
/** Null or empty restores the default skin. */
void setSkin(Instance* instance, const char* skin);
void setTrackAlpha(Instance* instance, int track, float alpha);
void setEventSink(EventSink sink);
void enableEvents(Instance* instance);
// --- queries ---------------------------------------------------------------
int animationCount(const Instance* instance);
const char* animationName(const Instance* instance, int index);
int skinCount(const Instance* instance);
const char* skinName(const Instance* instance, int index);
bool bonePosition(const Instance* instance, const char* bone, float* x, float* y);
bool boneRotation(const Instance* instance, const char* bone, float* degrees);
/**
* The skeleton as a tree: how many bones, each one's name, and which one is its parent
* (-1 for a root). Indices are the skeleton's own order, which puts a parent before every
* child, so a caller may walk it once without recursion.
*/
int boneCount(const Instance* instance);
const char* boneName(const Instance* instance, int index);
int boneParent(const Instance* instance, int index);
/**
* One bone as drawn this frame: where it starts (skeleton space), the direction it points
* in degrees, and how long it is. The applied pose, so constraints are in it.
*/
bool bonePose(const Instance* instance, int index, float* x, float* y, float* degrees, float* length);
void bounds(const Instance* instance, float* x, float* y, float* width, float* height);
/**
* The bounds the skeleton was AUTHORED with — from the data, before any instance
* exists and without posing one. A weaker promise than {@link bounds}, being the
* setup pose's extent, which an animation reaches outside of; what it can do
* that a posed extent cannot is decide whether a pose is worth computing.
*/
bool skeletonBounds(const Skeleton* skeleton, float* x, float* y, float* width, float* height);
int constraintCount(const Instance* instance, ConstraintKind kind);
const char* constraintName(const Instance* instance, ConstraintKind kind, int index);
bool transformMix(const Instance* instance, const char* name, TransformMix* out);
bool setTransformMix(Instance* instance, const char* name, const TransformMix& mix);
bool pathMix(const Instance* instance, const char* name, PathMix* out);
bool setPathMix(Instance* instance, const char* name, const PathMix& mix);
// --- posing ----------------------------------------------------------------
bool setAttachment(Instance* instance, const char* slot, const char* attachment);
bool setIkTarget(Instance* instance, const char* constraint, float x, float y, float mix);
bool setSlotColor(Instance* instance, const char* slot, float r, float g, float b, float a);
bool setSkeletonColor(Instance* instance, float r, float g, float b, float a);
// --- geometry --------------------------------------------------------------
/** Poses the skeleton's attachments into `sink`, applying clip regions when asked. */
void render(Instance* instance, TriangleSink& sink, bool clipping);
/** How far {@link renderStage} runs. Each includes the ones before it, so what a
* stage costs is the difference between two runs — the only way to price a step
* of this walk without a clock inside it. */
enum RenderStage {
STAGE_SETUP = 0, ///< The instance and the clipper; the loop does not run.
STAGE_TRAVERSE = 1, ///< Walk the draw order, resolving what each slot holds.
STAGE_VERTICES = 2, ///< …and compute world vertices and tint.
STAGE_CLIP_START = 3, ///< …and open each clip region: its polygon, made
///< clockwise and decomposed into convex pieces.
STAGE_CLIP = 4, ///< …and cut the triangles against those pieces.
STAGE_EMIT = 5, ///< …and hand them to the sink. The full extraction.
};
/** What the walk did, so a time can be explained rather than only reported. */
struct ProbeCounts {
std::uint32_t slots;
std::uint32_t regionAttachments;
std::uint32_t meshAttachments;
std::uint32_t clipStarts;
std::uint32_t clippedEmits;
std::uint32_t verticesGenerated;
std::uint32_t verticesEmitted;
std::uint32_t indicesEmitted;
std::uint32_t emits;
/// Convex pieces the clip polygons decomposed into. One per clip region says
/// the polygon was convex; more is what a concave one costs before any
/// triangle is cut, and every piece re-runs the cut.
std::uint32_t clipPolygons;
std::uint32_t clipPolygonVertices;
/// Edges summed over those pieces — what a cut actually costs per triangle,
/// since the clip runs one pass per edge, per piece, per triangle.
std::uint32_t clipPolygonEdges;
std::uint32_t clipInputTriangles;
std::uint32_t clipOutputTriangles;
/// Attachments the two fast paths answered without cutting anything: one
/// whose bounds miss the region entirely, one wholly inside a convex one.
std::uint32_t clipBoundsRejects;
std::uint32_t clipInsideAccepts;
/// The same three answers counted in triangles rather than attachments,
/// which is what a budget is charged in.
std::uint32_t clipCandidateTriangles;
std::uint32_t clipRejectedTriangles;
std::uint32_t clipBypassedTriangles;
/// Σ over charged attachments of triangles × the edges of the region they
/// were charged against — accumulated per region rather than multiplied at
/// the end, so a skeleton with two regions is priced against both.
std::uint32_t clipEdgeWork;
std::uint32_t clipInputVertices;
std::uint32_t clipOutputVertices;
/// Regions opened without triangulating, and regions that had to. A convex
/// polygon is its own only convex piece; proving that is linear, and
/// deriving it through an ear clip is quadratic.
std::uint32_t clipConvexBypasses;
std::uint32_t clipDecompositions;
};
/** BENCHMARK ONLY — the clipper's own scratch arrays, so a second storage
* problem inside it cannot hide behind the first one having been fixed. */
struct ClipStorage {
std::uint32_t polygon;
std::uint32_t output;
std::uint32_t vertices;
std::uint32_t uvs;
std::uint32_t triangles;
std::uint32_t scratch;
};
/** False where a backend has no clipper of its own to report on. */
bool clipStorage(ClipStorage* out);
/** How far {@link clipStartStage} runs. The shipped `clipStart` is a sequence of
* separable calls, and each depth here is a prefix of it: nothing later feeds
* anything earlier, so stopping short prices a step without a clock inside it. */
enum ClipStartStage {
CLIP_START_RESET = 0, ///< The scratch sized for the polygon.
CLIP_START_WORLD = 1, ///< …and its world vertices computed.
CLIP_START_WINDING = 2, ///< …made clockwise.
CLIP_START_TRIANGULATE = 3, ///< …triangulated.
CLIP_START_DECOMPOSE = 4, ///< …decomposed into convex pieces.
CLIP_START_PIECES = 5, ///< …each piece wound and closed. spine ends here.
CLIP_START_PUBLISH = 6, ///< …and this module's bounds and edges captured.
};
/** What opening a region had to do, so its time can be explained. */
struct ClipStartCounts {
std::uint32_t rawVertices;
std::uint32_t triangulationTriangles;
std::uint32_t pieces;
std::uint32_t effectiveEdges;
/// The triangulator's own arrays, so a second storage problem inside the
/// preparation cannot hide the way the collector's did.
std::uint32_t triangulatorScratch;
float minX, minY, maxX, maxY;
};
/**
* BENCHMARK ONLY — open the instance's first clip region to `stage`. False when
* the instance has no clipping attachment or the backend has no staged open.
*/
bool clipStartStage(Instance* instance, int stage, ClipStartCounts* counts);
/**
* The whole walk with its counters on — what a diagnostic asks for, as opposed
* to {@link renderStage}, which stops short and is for pricing steps. False
* where a backend has no counted walk.
*/
bool renderCounted(Instance* instance, TriangleSink& sink, bool clipping, ProbeCounts* counts);
/**
* BENCHMARK ONLY — the same walk as {@link render}, stopped at `stage`, so its
* cost can be decomposed without a clock inside the loop being decomposed.
* False where a backend has no instrumented walk (2.1, spine-cpp), so a
* measurement cannot quietly report zeros for one.
*/
bool renderStage(Instance* instance, TriangleSink& sink, bool clipping,
int stage, ProbeCounts* counts);
/** How far {@link poseStage} runs. Each includes the ones before it, so a step
* costs the difference between two runs. Unlike the render stages these MUTATE,
* and a short run is still a legitimate prefix: advancing does not read the
* skeleton, and resolving reads only what applying wrote. */
enum PoseStage {
POSE_SETUP = 0, ///< The instance lookup; nothing advances.
POSE_ADVANCE = 1, ///< Advance the tracks: time, mixing, queued entries.
POSE_APPLY = 2, ///< …and evaluate their timelines onto the bones.
POSE_WORLD = 3, ///< …and resolve world transforms and constraints — a whole pose.
};
/** What a pose had to do, so its time can be explained rather than only reported. */
struct PoseCounts {
std::uint32_t tracks;
std::uint32_t entries; ///< Track entries applied, `mixingFrom` chains included.
std::uint32_t timelines;
std::uint32_t bones;
std::uint32_t ikConstraints;
std::uint32_t transformConstraints;
std::uint32_t pathConstraints;
std::uint32_t physicsConstraints;
std::uint32_t events;
};
/**
* BENCHMARK ONLY — the same pose as {@link update}, stopped at `stage`.
* False where a backend has no instrumented pose (2.1, spine-cpp), so a
* measurement cannot quietly report zeros for one.
*/
bool poseStage(Instance* instance, float dt, int stage, PoseCounts* counts);
/** 21 / 38 / 41 / 42 / 43 — whatever `spine_runtimeVersion()` should report. */
int version();
} // namespace es::ES_SPINE_NS