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.

18.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    SpineModuleLoader.ts
 * @brief   Loads and initializes the standalone Spine WASM module
 */

import { log } from '../util/logger';

export interface SpineWasmModule {
    _spine_loadSkeleton(skelDataPtr: number, skelDataLen: number, atlasPtr: number, atlasLen: number, isBinary: number): number;
    _spine_unloadSkeleton(handle: number): void;
    _spine_getAtlasPageCount(handle: number): number;
    _spine_getAtlasPageTextureName(handle: number, pageIndex: number): number;
    _spine_setAtlasPageTexture(handle: number, pageIndex: number, textureId: number, width: number, height: number): void;

    _spine_createInstance(skeletonHandle: number): number;
    _spine_destroyInstance(instanceId: number): void;

    _spine_playAnimation(instanceId: number, name: number, loop: number, track: number): number;
    _spine_setToSetupPose(instanceId: number): void;
    _spine_addAnimation(instanceId: number, name: number, loop: number, delay: number, track: number): number;
    _spine_setSkin(instanceId: number, name: number): void;
    _spine_update(instanceId: number, dt: number): void;
    _spine_advanceAndApply(instanceId: number, dt: number): void;
    _spine_materializeWorldPose(instanceId: number, dt: number): void;
    _spine_requiresContinuousWorldPose(skeletonHandle: number): number;
    _spine_getAnimationDuration(skeletonHandle: number, animation: number): number;

    _spine_getAnimations(instanceId: number): number;
    _spine_getSkins(instanceId: number): number;
    _spine_getBonePosition(instanceId: number, bone: number, outXPtr: number, outYPtr: number): number;
    _spine_getBoneRotation(instanceId: number, bone: number): number;
    _spine_getBones?(instanceId: number): number;
    _spine_getBonePoses?(instanceId: number, outPtr: number, capacity: number): number;
    _spine_getBounds(instanceId: number, outXPtr: number, outYPtr: number, outWPtr: number, outHPtr: number): void;
    _spine_getSkeletonBounds(skeletonHandle: number, outXPtr: number, outYPtr: number, outWPtr: number, outHPtr: number): number;

    _spine_getMeshBatchColorPremultiplied?(instanceId: number, batchIndex: number): number;
    _spine_getMeshBatchCount(instanceId: number): number;
    _spine_getMeshBatchVertexCount(instanceId: number, batchIndex: number): number;
    _spine_getMeshBatchIndexCount(instanceId: number, batchIndex: number): number;
    _spine_getMeshBatchData(instanceId: number, batchIndex: number,
        outVerticesPtr: number, outIndicesPtr: number,
        outTextureIdPtr: number, outBlendModePtr: number): void;
    /** Toggle clip-region processing (default on) — perf escape hatch for clip-free scenes. */
    _spine_setClippingEnabled(enabled: number): void;

    _spine_setDefaultMix(skeletonHandle: number, duration: number): void;
    _spine_setMixDuration(skeletonHandle: number, fromAnim: number, toAnim: number, duration: number): void;
    _spine_setTrackAlpha(instanceId: number, track: number, alpha: number): void;

    _spine_enableEvents(instanceId: number): void;
    _spine_getEventCount(instanceId: number): number;
    _spine_getEventBuffer(): number;
    _spine_clearEvents(): void;
    _spine_getEventAnimationName(index: number): number;
    _spine_getEventName(index: number): number;
    _spine_getEventStringValue(index: number): number;

    _spine_setAttachment(instanceId: number, slotName: number, attachmentName: number): number;
    _spine_setIKTarget(instanceId: number, constraintName: number, targetX: number, targetY: number, mix: number): number;
    _spine_setSlotColor(instanceId: number, slotName: number, r: number, g: number, b: number, a: number): number;
    _spine_setSkeletonColor(instanceId: number, r: number, g: number, b: number, a: number): number;
    _spine_listConstraints(instanceId: number): number;
    _spine_getTransformConstraintMix(instanceId: number, name: number): number;
    _spine_setTransformConstraintMix(instanceId: number, name: number, rotate: number, x: number, y: number, scaleX: number, scaleY: number, shearY: number): number;
    _spine_getPathConstraintMix(instanceId: number, name: number): number;
    _spine_setPathConstraintMix(instanceId: number, name: number, position: number, spacing: number, rotate: number, x: number, y: number): number;
    _spine_probe_extract(instanceId: number, stage: number, useCollector: number): number;
    _spine_probe_counts(out: number): void;
    _spine_probe_clip_storage(out: number): void;
    _spine_clipBudget(instanceId: number, out: number): number;
    _spine_probe_clip_start(instanceId: number, stage: number): number;
    _spine_probe_clip_start_counts(out: number): void;
    _spine_probe_storage(out: number): void;
    _spine_probe_pose(instanceId: number, dt: number, stage: number): number;
    _spine_probe_pose_counts(out: number): void;

    cwrap(ident: string, returnType: string | null, argTypes: string[]): (...args: unknown[]) => unknown;
    UTF8ToString(ptr: number): string;
    stringToNewUTF8(str: string): number;

    HEAPF32: Float32Array;
    HEAPU8: Uint8Array;
    HEAPU32: Uint32Array;
    _malloc(size: number): number;
    _free(ptr: number): void;
}

export interface SpineWrappedAPI {
    loadSkeleton(skelDataPtr: number, skelDataLen: number, atlasPtr: number, atlasLen: number, isBinary: boolean): number;
    getLastError(): string;
    unloadSkeleton(handle: number): void;
    getAtlasPageCount(handle: number): number;
    getAtlasPageTextureName(handle: number, pageIndex: number): string;
    setAtlasPageTexture(handle: number, pageIndex: number, textureId: number, width: number, height: number): void;
    createInstance(skeletonHandle: number): number;
    destroyInstance(instanceId: number): void;
    playAnimation(instanceId: number, name: string, loop: boolean, track: number): boolean;
    /** Back to the data's own starting pose, tracks cleared — what a replay starts from. */
    setToSetupPose(instanceId: number): void;
    addAnimation(instanceId: number, name: string, loop: boolean, delay: number, track: number): boolean;
    setSkin(instanceId: number, name: string): void;
    update(instanceId: number, dt: number): void;

    /**
     * The two halves {@link update} is made of. Advancing is what an animation
     * MEANS — track time, mixing, events, attachments — and materializing is
     * where those local transforms become world ones. Only the second is worth
     * skipping, and only where {@link requiresContinuousWorldPose} says it may be.
     */
    advanceAndApply(instanceId: number, dt: number): void;
    materializeWorldPose(instanceId: number, dt: number): void;
    requiresContinuousWorldPose(skeletonHandle: number): number;
    /** Seconds; negative where the skeleton has no such animation. */
    getAnimationDuration(skeletonHandle: number, animation: string): number;
    getAnimations(instanceId: number): string;
    getSkins(instanceId: number): string;
    getBonePosition(instanceId: number, bone: string, outXPtr: number, outYPtr: number): boolean;
    getBoneRotation(instanceId: number, bone: string): number;
    /** Bone names in skeleton order, a parent before its children; absent on a module built before the call existed. */
    getBones?(instanceId: number): string;
    /** Five floats a bone — parent index (-1 for a root), x, y, degrees, length — into `outPtr`; returns the count written. */
    getBonePoses?(instanceId: number, outPtr: number, capacity: number): number;
    getBounds(instanceId: number, outXPtr: number, outYPtr: number, outWPtr: number, outHPtr: number): void;
    /** The skeleton's authored extent — answerable without an instance or a pose. */
    getSkeletonBounds(skeletonHandle: number, outXPtr: number, outYPtr: number, outWPtr: number, outHPtr: number): number;
    getMeshBatchCount(instanceId: number): number;
    getMeshBatchColorPremultiplied?(instanceId: number, batchIndex: number): number;
    getMeshBatchVertexCount(instanceId: number, batchIndex: number): number;
    getMeshBatchIndexCount(instanceId: number, batchIndex: number): number;
    getMeshBatchData(instanceId: number, batchIndex: number,
        outVerticesPtr: number, outIndicesPtr: number,
        outTextureIdPtr: number, outBlendModePtr: number): void;

    setDefaultMix(skeletonHandle: number, duration: number): void;
    setMixDuration(skeletonHandle: number, fromAnim: string, toAnim: string, duration: number): void;
    setTrackAlpha(instanceId: number, track: number, alpha: number): void;

    enableEvents(instanceId: number): void;
    getEventCount(instanceId: number): number;
    getEventBuffer(): number;
    clearEvents(): void;
    getEventAnimationName(index: number): string;
    getEventName(index: number): string;
    getEventStringValue(index: number): string;

    setAttachment(instanceId: number, slotName: string, attachmentName: string): boolean;
    setIKTarget(instanceId: number, constraintName: string, targetX: number, targetY: number, mix: number): boolean;
    setSlotColor(instanceId: number, slotName: string, r: number, g: number, b: number, a: number): boolean;
    setSkeletonColor(instanceId: number, r: number, g: number, b: number, a: number): boolean;
    listConstraints(instanceId: number): string;
    getTransformConstraintMix(instanceId: number, name: string): string;
    setTransformConstraintMix(instanceId: number, name: string, rotate: number, x: number, y: number, scaleX: number, scaleY: number, shearY: number): boolean;
    getPathConstraintMix(instanceId: number, name: string): string;
    setPathConstraintMix(instanceId: number, name: string, position: number, spacing: number, rotate: number, x: number, y: number): boolean;

    /**
     * BENCHMARK ONLY — run the extraction to `stage` and report what the walk
     * did (see benchmarks/spine-extract-stages). Nothing on a frame path calls
     * these: a frame's crossings are asserted in tests/spine-extract-stages.
     */
    probeExtract(instanceId: number, stage: number, useCollector: number): number;
    probeCounts(out: number): void;
    probeClipStorage(out: number): void;
    probeClipStart(instanceId: number, stage: number): number;
    probeClipStartCounts(out: number): void;

    /**
     * What one instance's clipping costs this pose, in work rather than time.
     * Poses and extracts, so it is a diagnostic call and not a frame reading.
     */
    clipBudget(instanceId: number, out: number): number;
    probeStorage(out: number): void;
    probePose(instanceId: number, dt: number, stage: number): number;
    probePoseCounts(out: number): void;
}

export function wrapSpineModule(raw: SpineWasmModule): SpineWrappedAPI {
    const cw = raw.cwrap.bind(raw);
    return {
        loadSkeleton: cw('spine_loadSkeleton', 'number', ['number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['loadSkeleton'],
        getLastError: cw('spine_getLastError', 'string', []) as SpineWrappedAPI['getLastError'],
        unloadSkeleton: cw('spine_unloadSkeleton', null, ['number']) as SpineWrappedAPI['unloadSkeleton'],
        getAtlasPageCount: cw('spine_getAtlasPageCount', 'number', ['number']) as SpineWrappedAPI['getAtlasPageCount'],
        getAtlasPageTextureName: cw('spine_getAtlasPageTextureName', 'string', ['number', 'number']) as SpineWrappedAPI['getAtlasPageTextureName'],
        setAtlasPageTexture: cw('spine_setAtlasPageTexture', null, ['number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['setAtlasPageTexture'],
        createInstance: cw('spine_createInstance', 'number', ['number']) as SpineWrappedAPI['createInstance'],
        destroyInstance: cw('spine_destroyInstance', null, ['number']) as SpineWrappedAPI['destroyInstance'],
        playAnimation: cw('spine_playAnimation', 'number', ['number', 'string', 'number', 'number']) as SpineWrappedAPI['playAnimation'],
        setToSetupPose: cw('spine_setToSetupPose', null, ['number']) as SpineWrappedAPI['setToSetupPose'],
        addAnimation: cw('spine_addAnimation', 'number', ['number', 'string', 'number', 'number', 'number']) as SpineWrappedAPI['addAnimation'],
        setSkin: cw('spine_setSkin', null, ['number', 'string']) as SpineWrappedAPI['setSkin'],
        update: cw('spine_update', null, ['number', 'number']) as SpineWrappedAPI['update'],
        advanceAndApply: cw('spine_advanceAndApply', null, ['number', 'number']) as SpineWrappedAPI['advanceAndApply'],
        materializeWorldPose: cw('spine_materializeWorldPose', null, ['number', 'number']) as SpineWrappedAPI['materializeWorldPose'],
        requiresContinuousWorldPose: cw('spine_requiresContinuousWorldPose', 'number', ['number']) as SpineWrappedAPI['requiresContinuousWorldPose'],
        getAnimationDuration: cw('spine_getAnimationDuration', 'number', ['number', 'string']) as SpineWrappedAPI['getAnimationDuration'],
        getAnimations: cw('spine_getAnimations', 'string', ['number']) as SpineWrappedAPI['getAnimations'],
        getSkins: cw('spine_getSkins', 'string', ['number']) as SpineWrappedAPI['getSkins'],
        getBonePosition: cw('spine_getBonePosition', 'number', ['number', 'string', 'number', 'number']) as SpineWrappedAPI['getBonePosition'],
        getBoneRotation: cw('spine_getBoneRotation', 'number', ['number', 'string']) as SpineWrappedAPI['getBoneRotation'],
        getBones: typeof (raw as unknown as Record<string, unknown>)._spine_getBones === 'function'
            ? cw('spine_getBones', 'string', ['number']) as SpineWrappedAPI['getBones']
            : undefined,
        getBonePoses: typeof (raw as unknown as Record<string, unknown>)._spine_getBonePoses === 'function'
            ? cw('spine_getBonePoses', 'number', ['number', 'number', 'number']) as SpineWrappedAPI['getBonePoses']
            : undefined,
        getBounds: cw('spine_getBounds', null, ['number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['getBounds'],
        getSkeletonBounds: cw('spine_getSkeletonBounds', 'number', ['number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['getSkeletonBounds'],
        getMeshBatchColorPremultiplied: typeof (raw as unknown as Record<string, unknown>)._spine_getMeshBatchColorPremultiplied === 'function'
            ? cw('spine_getMeshBatchColorPremultiplied', 'number', ['number', 'number']) as SpineWrappedAPI['getMeshBatchColorPremultiplied'] : undefined,
        getMeshBatchCount: cw('spine_getMeshBatchCount', 'number', ['number']) as SpineWrappedAPI['getMeshBatchCount'],
        getMeshBatchVertexCount: cw('spine_getMeshBatchVertexCount', 'number', ['number', 'number']) as SpineWrappedAPI['getMeshBatchVertexCount'],
        getMeshBatchIndexCount: cw('spine_getMeshBatchIndexCount', 'number', ['number', 'number']) as SpineWrappedAPI['getMeshBatchIndexCount'],
        getMeshBatchData: cw('spine_getMeshBatchData', null, ['number', 'number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['getMeshBatchData'],

        setDefaultMix: cw('spine_setDefaultMix', null, ['number', 'number']) as SpineWrappedAPI['setDefaultMix'],
        setMixDuration: cw('spine_setMixDuration', null, ['number', 'string', 'string', 'number']) as SpineWrappedAPI['setMixDuration'],
        setTrackAlpha: cw('spine_setTrackAlpha', null, ['number', 'number', 'number']) as SpineWrappedAPI['setTrackAlpha'],

        enableEvents: cw('spine_enableEvents', null, ['number']) as SpineWrappedAPI['enableEvents'],
        getEventCount: cw('spine_getEventCount', 'number', ['number']) as SpineWrappedAPI['getEventCount'],
        getEventBuffer: cw('spine_getEventBuffer', 'number', []) as SpineWrappedAPI['getEventBuffer'],
        clearEvents: cw('spine_clearEvents', null, []) as SpineWrappedAPI['clearEvents'],
        getEventAnimationName: cw('spine_getEventAnimationName', 'string', ['number']) as SpineWrappedAPI['getEventAnimationName'],
        getEventName: cw('spine_getEventName', 'string', ['number']) as SpineWrappedAPI['getEventName'],
        getEventStringValue: cw('spine_getEventStringValue', 'string', ['number']) as SpineWrappedAPI['getEventStringValue'],

        setAttachment: cw('spine_setAttachment', 'number', ['number', 'string', 'string']) as SpineWrappedAPI['setAttachment'],
        setIKTarget: cw('spine_setIKTarget', 'number', ['number', 'string', 'number', 'number', 'number']) as SpineWrappedAPI['setIKTarget'],
        setSlotColor: cw('spine_setSlotColor', 'number', ['number', 'string', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['setSlotColor'],
        setSkeletonColor: cw('spine_setSkeletonColor', 'number', ['number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['setSkeletonColor'],
        listConstraints: cw('spine_listConstraints', 'string', ['number']) as SpineWrappedAPI['listConstraints'],
        getTransformConstraintMix: cw('spine_getTransformConstraintMix', 'string', ['number', 'string']) as SpineWrappedAPI['getTransformConstraintMix'],
        setTransformConstraintMix: cw('spine_setTransformConstraintMix', 'number', ['number', 'string', 'number', 'number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['setTransformConstraintMix'],
        getPathConstraintMix: cw('spine_getPathConstraintMix', 'string', ['number', 'string']) as SpineWrappedAPI['getPathConstraintMix'],
        setPathConstraintMix: cw('spine_setPathConstraintMix', 'number', ['number', 'string', 'number', 'number', 'number', 'number', 'number']) as SpineWrappedAPI['setPathConstraintMix'],

        probeExtract: cw('spine_probe_extract', 'number', ['number', 'number', 'number']) as SpineWrappedAPI['probeExtract'],
        probeCounts: cw('spine_probe_counts', null, ['number']) as SpineWrappedAPI['probeCounts'],
        probeClipStorage: cw('spine_probe_clip_storage', null, ['number']) as SpineWrappedAPI['probeClipStorage'],
        probeClipStart: cw('spine_probe_clip_start', 'number', ['number', 'number']) as SpineWrappedAPI['probeClipStart'],
        probeClipStartCounts: cw('spine_probe_clip_start_counts', null, ['number']) as SpineWrappedAPI['probeClipStartCounts'],
        clipBudget: cw('spine_clipBudget', 'number', ['number', 'number']) as SpineWrappedAPI['clipBudget'],
        probeStorage: cw('spine_probe_storage', null, ['number']) as SpineWrappedAPI['probeStorage'],
        probePose: cw('spine_probe_pose', 'number', ['number', 'number', 'number']) as SpineWrappedAPI['probePose'],
        probePoseCounts: cw('spine_probe_pose_counts', null, ['number']) as SpineWrappedAPI['probePoseCounts'],
    };
}

export type SpineModuleFactory = (config?: Record<string, unknown>) => Promise<SpineWasmModule>;