Skip to content

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.

21.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    SpineRuntimeCpp.cpp
 * @brief   The SpineRuntime backend for spine-cpp, which 4.3 made the only runtime.
 *
 * @details 4.3 retired the hand-written C runtime and regenerated spine-c as a
 *          wrapper over the C++ one. Binding the wrapper would buy nothing here —
 *          this TU is already C++ — so it binds spine-cpp directly.
 *
 *          The release also brought `SkeletonRenderer`, which walks the draw order,
 *          poses every attachment and applies clip regions. That is the whole of what
 *          the spine-c backend does by hand, so `render()` below is a translation of
 *          its RenderCommand list rather than a second copy of the traversal.
 *
 *          4.3 also moved a bone's world transform and a slot's colour onto pose
 *          objects, and reordered EventType so Dispose precedes Complete. The seam's
 *          normalized EventKind is why that reordering stops here instead of reaching
 *          the SDK.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */

#include "./SpineRuntime.hpp"

#include <spine/spine.h>
#include <spine/PhysicsConstraintData.h>
#include <spine/SkeletonRenderer.h>

#include <vector>

#ifndef ES_SPINE_VERSION
#error "ES_SPINE_VERSION must name the vendored spine-cpp release (43)."
#endif

namespace sp = ::spine;

// spine-cpp asks its host for the allocator it should use, the way spine-c asks for
// its file and texture hooks. The default one is malloc/free, which is what the
// module wants: on the web its heap is the wasm heap, and on a device the host's
// allocator already routes through the engine's arena.
sp::SpineExtension* spine::getDefaultExtension() {
    return new sp::DefaultSpineExtension();
}

namespace es::ES_SPINE_NS {

namespace {

/**
 * Atlas pages are uploaded by the SDK, not by us: it reads the page names back,
 * loads the images and registers texture ids through setAtlasPageTexture. So the
 * loader spine-cpp insists on exists and does nothing.
 */
class UnloadedTextures : public sp::TextureLoader {
public:
    void load(sp::AtlasPage& page, const sp::String& path) override {
        (void)page;
        (void)path;
    }
    void unload(void* texture) override { (void)texture; }
};

EventSink g_eventSink = nullptr;

/// Reused across instances and frames: one render() consumes its commands at once.
sp::SkeletonRenderer g_renderer;

int blendModeOf(sp::BlendMode mode) {
    switch (mode) {
        case sp::BlendMode_Additive: return 1;
        case sp::BlendMode_Multiply: return 2;
        case sp::BlendMode_Screen: return 3;
        default: return 0;
    }
}

const char* cstr(const sp::String& text) {
    return text.buffer();
}

}  // namespace

// =============================================================================
// Resources
// =============================================================================

struct Skeleton {
    UnloadedTextures loader;
    sp::Atlas* atlas = nullptr;
    sp::SkeletonData* data = nullptr;
    sp::AnimationStateData* stateData = nullptr;

    /// Texture ids whose atlas page is premultiplied, so render() can pick the
    /// premultiplied blend modes. The renderer hands back a texture, not a page.
    std::vector<void*> premultiplied;

    Skeleton() = default;
    Skeleton(const Skeleton&) = delete;
    Skeleton& operator=(const Skeleton&) = delete;

    // The atlas unloads its pages through the loader, so it goes first.
    ~Skeleton() {
        delete stateData;
        delete data;
        delete atlas;
    }

    bool isPremultiplied(void* texture) const {
        for (void* t : premultiplied) {
            if (t == texture) return true;
        }
        return false;
    }
};

struct Instance {
    Skeleton* owner = nullptr;
    sp::Skeleton* skeleton = nullptr;
    sp::AnimationState* state = nullptr;

    Instance() = default;
    Instance(const Instance&) = delete;
    Instance& operator=(const Instance&) = delete;

    ~Instance() {
        delete state;
        delete skeleton;
    }
};

void destroy(Skeleton* skeleton) { delete skeleton; }
void destroy(Instance* instance) { delete instance; }

Skeleton* loadSkeleton(const void* skeletonData, int length,
                       const char* atlasText, int atlasLength,
                       bool binary, std::string& error) {
    auto skeleton = std::make_unique<Skeleton>();

    skeleton->atlas = new sp::Atlas(atlasText, atlasLength, "", &skeleton->loader);
    if (skeleton->atlas->getPages().size() == 0) {
        error = "Failed to create atlas (invalid atlas text or no pages)";
        return nullptr;
    }

    if (binary) {
        sp::SkeletonBinary reader(*skeleton->atlas);
        reader.setScale(1.0f);
        skeleton->data = reader.readSkeletonData(
            static_cast<const unsigned char*>(skeletonData), length);
        if (!skeleton->data) error = cstr(reader.getError());
    } else {
        sp::SkeletonJson reader(*skeleton->atlas);
        reader.setScale(1.0f);
        skeleton->data = reader.readSkeletonData(static_cast<const char*>(skeletonData));
        if (!skeleton->data) error = cstr(reader.getError());
    }

    if (!skeleton->data) return nullptr;

    skeleton->stateData = new sp::AnimationStateData(*skeleton->data);
    skeleton->stateData->setDefaultMix(0.2f);
    return skeleton.release();
}

int atlasPageCount(const Skeleton* skeleton) {
    if (!skeleton) return 0;
    return static_cast<int>(skeleton->atlas->getPages().size());
}

const char* atlasPageName(const Skeleton* skeleton, int page) {
    if (!skeleton || page < 0 || page >= atlasPageCount(skeleton)) return nullptr;
    return cstr(skeleton->atlas->getPages()[page]->name);
}

void setAtlasPageTexture(Skeleton* skeleton, int page, uint32_t texture, int width, int height) {
    if (!skeleton || page < 0 || page >= atlasPageCount(skeleton)) return;

    sp::AtlasPage* target = skeleton->atlas->getPages()[page];
    void* handle = reinterpret_cast<void*>(static_cast<uintptr_t>(texture));
    target->texture = handle;
    target->width = width;
    target->height = height;

    // Regions copied the page's texture when the atlas parsed, which was before the
    // SDK had one to give; attachments read it from the region, so refresh them.
    sp::Array<sp::AtlasRegion*>& regions = skeleton->atlas->getRegions();
    for (size_t i = 0; i < regions.size(); ++i) {
        if (regions[i]->getPage() == target) regions[i]->setRendererObject(handle);
    }

    if (target->pma && !skeleton->isPremultiplied(handle)) {
        skeleton->premultiplied.push_back(handle);
    }
}

void setDefaultMix(Skeleton* skeleton, float seconds) {
    if (skeleton) skeleton->stateData->setDefaultMix(seconds);
}

void setMixDuration(Skeleton* skeleton, const char* from, const char* to, float seconds) {
    if (!skeleton) return;
    sp::Animation* a = skeleton->data->findAnimation(from);
    sp::Animation* b = skeleton->data->findAnimation(to);
    if (a && b) skeleton->stateData->setMix(*a, *b, seconds);
}

// =============================================================================
// Instances
// =============================================================================

Instance* createInstance(Skeleton* skeleton) {
    if (!skeleton) return nullptr;

    auto instance = std::make_unique<Instance>();
    instance->owner = skeleton;
    instance->skeleton = new sp::Skeleton(*skeleton->data);
    instance->state = new sp::AnimationState(*skeleton->stateData);

    instance->skeleton->setupPose();
    instance->skeleton->updateWorldTransform(sp::Physics_Update);
    return instance.release();
}

void advanceAndApply(Instance* instance, float dt) {
    if (!instance) return;
    instance->state->update(dt);
    instance->state->apply(*instance->skeleton);
}

void materializeWorldPose(Instance* instance, float dt) {
    if (!instance) return;
    instance->skeleton->update(dt);
    instance->skeleton->updateWorldTransform(sp::Physics_Update);
}

void update(Instance* instance, float dt) {
    advanceAndApply(instance, dt);
    materializeWorldPose(instance, dt);
}

float animationDuration(const Skeleton* skeleton, const char* animation) {
    if (!skeleton || !skeleton->data) return -1.0f;
    sp::Animation* found = skeleton->data->findAnimation(animation);
    return found ? found->getDuration() : -1.0f;
}

bool requiresContinuousWorldPose(const Skeleton* skeleton) {
    if (!skeleton || !skeleton->data) return false;
    // 4.3 keeps one constraint list and tells them apart by spine's own RTTI,
    // which is what this build has instead of the compiler's.
    sp::Array<sp::ConstraintData*>& constraints = skeleton->data->getConstraints();
    for (size_t i = 0; i < constraints.size(); ++i) {
        if (constraints[i]->getRTTI().instanceOf(sp::PhysicsConstraintData::rtti)) return true;
    }
    return false;
}

void setToSetupPose(Instance* instance) {
    if (!instance) return;
    instance->state->clearTracks();
    // 4.3 renamed it; this file is the 4.3 backend.
    instance->skeleton->setupPose();
}

bool playAnimation(Instance* instance, const char* animation, bool loop, int track) {
    if (!instance) return false;
    // setAnimation takes a reference and asserts on a missing name, so look first.
    sp::Animation* found = instance->skeleton->getData().findAnimation(animation);
    if (!found) return false;
    instance->state->setAnimation(static_cast<size_t>(track), *found, loop);
    return true;
}

bool addAnimation(Instance* instance, const char* animation, bool loop, float delay, int track) {
    if (!instance) return false;
    sp::Animation* found = instance->skeleton->getData().findAnimation(animation);
    if (!found) return false;
    instance->state->addAnimation(static_cast<size_t>(track), *found, loop, delay);
    return true;
}

void setSkin(Instance* instance, const char* skin) {
    if (!instance) return;
    if (!skin || skin[0] == '\0') {
        instance->skeleton->setSkin(static_cast<sp::Skin*>(nullptr));
    } else {
        sp::Skin* found = instance->skeleton->getData().findSkin(skin);
        if (!found) return;
        instance->skeleton->setSkin(found);
    }
    instance->skeleton->setupPoseSlots();
}

void setTrackAlpha(Instance* instance, int track, float alpha) {
    if (!instance) return;
    sp::TrackEntry* entry = instance->state->getTrack(static_cast<size_t>(track));
    if (entry) entry->setAlpha(alpha);
}

void setEventSink(EventSink sink) {
    g_eventSink = sink;
}

namespace {

/// 4.3 numbers Dispose before Complete; the SDK reads 4.x's original order.
EventKind kindOf(sp::EventType type) {
    switch (type) {
        case sp::EventType_Start: return EventKind::Start;
        case sp::EventType_Interrupt: return EventKind::Interrupt;
        case sp::EventType_End: return EventKind::End;
        case sp::EventType_Complete: return EventKind::Complete;
        case sp::EventType_Dispose: return EventKind::Dispose;
        default: return EventKind::Event;
    }
}

void eventListener(sp::AnimationState* state, sp::EventType type,
                   sp::TrackEntry* entry, sp::Event* event, void* userData) {
    (void)state;
    (void)userData;
    if (!g_eventSink) return;

    Event out;
    out.source = state;
    out.kind = kindOf(type);
    out.track = entry ? static_cast<int>(entry->getTrackIndex()) : 0;
    if (entry) out.animation = cstr(entry->getAnimation().getName());
    if (type == sp::EventType_Event && event) {
        out.floatValue = event->getFloat();
        out.intValue = event->getInt();
        out.name = cstr(event->getData().getName());
        out.stringValue = cstr(event->getString());
    }
    g_eventSink(out);
}

}  // namespace

const void* eventSource(Instance* instance) {
    return instance ? instance->state : nullptr;
}

void enableEvents(Instance* instance) {
    if (instance) instance->state->setListener(eventListener);
}

// =============================================================================
// Queries
// =============================================================================

int animationCount(const Instance* instance) {
    if (!instance) return 0;
    return static_cast<int>(instance->skeleton->getData().getAnimations().size());
}

const char* animationName(const Instance* instance, int index) {
    if (!instance || index < 0 || index >= animationCount(instance)) return nullptr;
    return cstr(instance->skeleton->getData().getAnimations()[index]->getName());
}

int skinCount(const Instance* instance) {
    if (!instance) return 0;
    return static_cast<int>(instance->skeleton->getData().getSkins().size());
}

const char* skinName(const Instance* instance, int index) {
    if (!instance || index < 0 || index >= skinCount(instance)) return nullptr;
    return cstr(instance->skeleton->getData().getSkins()[index]->getName());
}

bool bonePosition(const Instance* instance, const char* bone, float* x, float* y) {
    if (!instance) return false;
    sp::Bone* found = instance->skeleton->findBone(bone);
    if (!found) return false;
    // The applied pose is what rendering used — constraints included.
    *x = found->getAppliedPose().getWorldX();
    *y = found->getAppliedPose().getWorldY();
    return true;
}

bool boneRotation(const Instance* instance, const char* bone, float* degrees) {
    if (!instance) return false;
    sp::Bone* found = instance->skeleton->findBone(bone);
    if (!found) return false;
    *degrees = found->getAppliedPose().getWorldRotationX();
    return true;
}

int boneCount(const Instance* instance) {
    return instance ? static_cast<int>(instance->skeleton->getBones().size()) : 0;
}

const char* boneName(const Instance* instance, int index) {
    if (!instance || index < 0 || index >= boneCount(instance)) return nullptr;
    return cstr(instance->skeleton->getBones()[index]->getData().getName());
}

int boneParent(const Instance* instance, int index) {
    if (!instance || index < 0 || index >= boneCount(instance)) return -1;
    sp::Bone* parent = instance->skeleton->getBones()[index]->getParent();
    return parent ? parent->getData().getIndex() : -1;
}

bool bonePose(const Instance* instance, int index, float* x, float* y, float* degrees, float* length) {
    if (!instance || index < 0 || index >= boneCount(instance)) return false;
    sp::Bone* b = instance->skeleton->getBones()[index];
    *x = b->getAppliedPose().getWorldX();
    *y = b->getAppliedPose().getWorldY();
    *degrees = b->getAppliedPose().getWorldRotationX();
    *length = b->getData().getLength();
    return true;
}

void bounds(const Instance* instance, float* x, float* y, float* width, float* height) {
    *x = *y = *width = *height = 0.0f;
    if (!instance) return;
    instance->skeleton->getBounds(*x, *y, *width, *height);
}

namespace {

bool isKind(sp::Constraint* constraint, ConstraintKind kind) {
    switch (kind) {
        case ConstraintKind::Ik: return constraint->getRTTI().isExactly(sp::IkConstraint::rtti);
        case ConstraintKind::Transform:
            return constraint->getRTTI().isExactly(sp::TransformConstraint::rtti);
        case ConstraintKind::Path: return constraint->getRTTI().isExactly(sp::PathConstraint::rtti);
    }
    return false;
}

}  // namespace

int constraintCount(const Instance* instance, ConstraintKind kind) {
    if (!instance) return 0;
    sp::Array<sp::Constraint*>& constraints = instance->skeleton->getConstraints();
    int count = 0;
    for (size_t i = 0; i < constraints.size(); ++i) {
        if (isKind(constraints[i], kind)) ++count;
    }
    return count;
}

const char* constraintName(const Instance* instance, ConstraintKind kind, int index) {
    if (!instance || index < 0) return nullptr;
    sp::Array<sp::Constraint*>& constraints = instance->skeleton->getConstraints();
    int seen = 0;
    for (size_t i = 0; i < constraints.size(); ++i) {
        if (!isKind(constraints[i], kind)) continue;
        if (seen == index) return cstr(constraints[i]->getData().getName());
        ++seen;
    }
    return nullptr;
}

bool transformMix(const Instance* instance, const char* name, TransformMix* out) {
    if (!instance) return false;
    auto* c = instance->skeleton->findConstraint<sp::TransformConstraint>(name);
    if (!c) return false;
    out->rotate = c->getPose().getMixRotate();
    out->x = c->getPose().getMixX();
    out->y = c->getPose().getMixY();
    out->scaleX = c->getPose().getMixScaleX();
    out->scaleY = c->getPose().getMixScaleY();
    out->shearY = c->getPose().getMixShearY();
    return true;
}

bool setTransformMix(Instance* instance, const char* name, const TransformMix& mix) {
    if (!instance) return false;
    auto* c = instance->skeleton->findConstraint<sp::TransformConstraint>(name);
    if (!c) return false;
    c->getPose().setMixRotate(mix.rotate);
    c->getPose().setMixX(mix.x);
    c->getPose().setMixY(mix.y);
    c->getPose().setMixScaleX(mix.scaleX);
    c->getPose().setMixScaleY(mix.scaleY);
    c->getPose().setMixShearY(mix.shearY);
    return true;
}

bool pathMix(const Instance* instance, const char* name, PathMix* out) {
    if (!instance) return false;
    auto* c = instance->skeleton->findConstraint<sp::PathConstraint>(name);
    if (!c) return false;
    out->position = c->getPose().getPosition();
    out->spacing = c->getPose().getSpacing();
    out->rotate = c->getPose().getMixRotate();
    out->x = c->getPose().getMixX();
    out->y = c->getPose().getMixY();
    return true;
}

bool setPathMix(Instance* instance, const char* name, const PathMix& mix) {
    if (!instance) return false;
    auto* c = instance->skeleton->findConstraint<sp::PathConstraint>(name);
    if (!c) return false;
    c->getPose().setPosition(mix.position);
    c->getPose().setSpacing(mix.spacing);
    c->getPose().setMixRotate(mix.rotate);
    c->getPose().setMixX(mix.x);
    c->getPose().setMixY(mix.y);
    return true;
}

// =============================================================================
// Posing
// =============================================================================

bool setAttachment(Instance* instance, const char* slot, const char* attachment) {
    if (!instance) return false;
    sp::Slot* found = instance->skeleton->findSlot(slot);
    if (!found) return false;

    if (!attachment || attachment[0] == '\0') {
        found->getPose().setAttachment(nullptr);
        return true;
    }

    sp::Attachment* wanted = instance->skeleton->getAttachment(found->getData().getIndex(), attachment);
    if (!wanted) return false;
    found->getPose().setAttachment(wanted);
    return true;
}

bool setIkTarget(Instance* instance, const char* constraint, float x, float y, float mix) {
    if (!instance) return false;
    auto* c = instance->skeleton->findConstraint<sp::IkConstraint>(constraint);
    if (!c) return false;
    c->getTarget().getPose().setX(x);
    c->getTarget().getPose().setY(y);
    c->getPose().setMix(mix);
    return true;
}

bool setSlotColor(Instance* instance, const char* slot, float r, float g, float b, float a) {
    if (!instance) return false;
    sp::Slot* found = instance->skeleton->findSlot(slot);
    if (!found) return false;
    found->getPose().getColor().set(r, g, b, a);
    return true;
}

bool setSkeletonColor(Instance* instance, float r, float g, float b, float a) {
    if (!instance) return false;
    instance->skeleton->getColor().set(r, g, b, a);
    return true;
}

// =============================================================================
// Geometry
// =============================================================================

void render(Instance* instance, TriangleSink& sink, bool clipping) {
    if (!instance) return;

    // SkeletonRenderer always clips; when the caller asked for no clipping there is
    // nothing to turn off, so the flag only matters to backends that clip by hand.
    (void)clipping;

    for (sp::RenderCommand* command = g_renderer.render(*instance->skeleton);
         command != nullptr; command = command->next) {
        if (command->numVertices <= 0 || command->numIndices <= 0) continue;

        // Every vertex of a command carries the same colour: the renderer writes one
        // colour per attachment and only merges commands whose colours already match.
        const uint32_t packed = command->colors[0];
        float rgba[4] = {
            static_cast<float>((packed >> 16) & 0xFF) / 255.0f,
            static_cast<float>((packed >> 8) & 0xFF) / 255.0f,
            static_cast<float>(packed & 0xFF) / 255.0f,
            static_cast<float>((packed >> 24) & 0xFF) / 255.0f,
        };

        // Both consequences of premultiplied artwork, from the one rule the C
        // backend also reads (SpineRuntime.hpp): the blend code gains a twin for
        // two of the four modes, and the tint carries its alpha for ALL of them.
        const bool pma = instance->owner->isPremultiplied(command->texture);
        sink.setPremultipliedColor(pma);
        premultiplyTint(rgba, pma);

        sink.emit(command->positions, command->uvs, command->numVertices,
                  command->indices, command->numIndices,
                  static_cast<uint32_t>(reinterpret_cast<uintptr_t>(command->texture)),
                  blendForPage(blendModeOf(command->blendMode), pma), rgba);
    }
}

/** Not instrumented: the cost decomposition is measured on the spine-c walk
 *  (3.8 / 4.1 / 4.2). False rather than zeros, so a measurement cannot report
 *  this backend as free. */
bool renderStage(Instance*, TriangleSink&, bool, int, ProbeCounts*) {
    return false;
}

bool poseStage(Instance*, float, int, PoseCounts*) {
    return false;
}

bool clipStorage(ClipStorage*) {
    return false;
}

bool renderCounted(Instance*, TriangleSink&, bool, ProbeCounts*) {
    return false;
}

bool clipStartStage(Instance*, int, ClipStartCounts*) {
    return false;
}

bool skeletonBounds(const Skeleton*, float*, float*, float*, float*) {
    return false;
}

int version() {
    return ES_SPINE_VERSION;
}

}  // namespace es::ES_SPINE_NS