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.

fix(spine): color / timeScale / playing take effect from the inspector

esenginea4438b3c350f
diff --git a/desktop/src/engine/spineSync.ts b/desktop/src/engine/spineSync.ts
index ed5e63eb4..13ea193d6 100644
--- a/desktop/src/engine/spineSync.ts
+++ b/desktop/src/engine/spineSync.ts
@@ -21,6 +21,7 @@
* spine themselves, once).
*/
import { getComponentSpineFieldDescriptor } from 'esengine';
+import { spineEntityProps } from 'esengine/spine';
import type { SceneData } from 'esengine';
import { SceneModel, type ModelEvent } from './SceneModel';
import { SceneStore } from './SceneStore';
@@ -155,12 +156,7 @@ function syncEntity(sourceId: number): void {
// Same binding — apply the editable spine state in place. Props are
// idempotent; skin/animation only on change so scrubbing an unrelated
// field never restarts the animation.
- spine.setEntityProps(rt as never, {
- skeletonScale: typeof sc.d.skeletonScale === 'number' ? sc.d.skeletonScale : 1,
- flipX: sc.d.flipX === true,
- flipY: sc.d.flipY === true,
- layer: typeof sc.d.layer === 'number' ? sc.d.layer : 0,
- });
+ spine.setEntityProps(rt as never, spineEntityProps(sc.d));
if (prev.skin !== next.skin && next.skin) spine.setSkin(rt as never, next.skin);
if (prev.animation !== next.animation || prev.loop !== next.loop) {
if (next.animation) spine.setAnimation(rt as never, next.animation, next.loop);
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 0260e5567..4c0dc1596 100644
--- a/sdk/etc/spine.api.md
+++ b/sdk/etc/spine.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/spine
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 20 stable · 0 beta · 0 deprecated
+Symbols: 21 stable · 0 beta · 0 deprecated
## ConstraintList — interface
```
@@ -29,7 +29,7 @@ setAnimation: (entity: Entity, animation: string, loop: boolean) => void
setAttachment: (entity: Entity, slotName: string, attachmentName: string) => boolean
setDefaultMix: (entity: Entity, duration: number) => void
setEnabled: (entity: Entity, enabled: boolean) => void
-setEntityProps: (entity: Entity, props: { skeletonScale?: number; flipX?: boolean; flipY?: boolean; layer?: number; }) => void
+setEntityProps: (entity: Entity, props: { skeletonScale?: number; flipX?: boolean; flipY?: boolean; layer?: number; timeScale?: number; playing?: boolean; color?: { r: number; g: number; b: number; a: number; }; }) => void
setIKTarget: (entity: Entity, constraintName: string, targetX: number, targetY: number, mix: number) => boolean
setMixDuration: (entity: Entity, fromAnim: string, toAnim: string, duration: number) => void
setPathConstraintMix: (entity: Entity, name: string, mix: PathMixData) => boolean
@@ -117,7 +117,7 @@ setAnimation: (entity: Entity, animation: string, loop: boolean) => void
setAttachment: (entity: Entity, slotName: string, attachmentName: string) => boolean
setDefaultMix: (entity: Entity, duration: number) => void
setEnabled: (entity: Entity, enabled: boolean) => void
-setEntityProps: (entity: Entity, props: { skeletonScale?: number; flipX?: boolean; flipY?: boolean; layer?: number; }) => void
+setEntityProps: (entity: Entity, props: { skeletonScale?: number; flipX?: boolean; flipY?: boolean; layer?: number; timeScale?: number; playing?: boolean; color?: { r: number; g: number; b: number; a: number; }; }) => void
setIKTarget: (entity: Entity, constraintName: string, targetX: number, targetY: number, mix: number) => boolean
setMixDuration: (entity: Entity, fromAnim: string, toAnim: string, duration: number) => void
setPathConstraintMix: (entity: Entity, name: string, mix: PathMixData) => boolean
@@ -165,6 +165,7 @@ setDefaultMix: (skeletonHandle: number, duration: number) => void
setIKTarget: (instanceId: number, constraintName: string, targetX: number, targetY: number, mix: number) => boolean
setMixDuration: (skeletonHandle: number, fromAnim: string, toAnim: string, duration: number) => void
setPathConstraintMix: (instanceId: number, name: string, mix: PathMixData) => boolean
+setSkeletonColor: (instanceId: number, r: number, g: number, b: number, a: number) => boolean
setSkin: (instanceId: number, skinName: string) => void
setSlotColor: (instanceId: number, slotName: string, r: number, g: number, b: number, a: number) => boolean
setTrackAlpha: (instanceId: number, track: number, alpha: number) => void
@@ -222,6 +223,11 @@ mixY: number
(opts: { module: ESEngineModule; source: RuntimeAssetSource; spineManager: SpineManager; sceneData: SceneData; entityMap: Map<number, Entity>; registry: CppRegistry; transcoderProvider?: TranscoderProvider; }): Promise<void>
```
+## spineEntityProps — function
+```
+(d: Record<string, unknown>): { skeletonScale: number; flipX: boolean; flipY: boolean; layer: number; timeScale: number; playing: boolean; color?: { r: number; g: number; b: number; a: number; }; }
+```
+
## wrapSpineModule — function
```
(raw: SpineWasmModule): SpineWrappedAPI
diff --git a/sdk/src/spine/ModuleBackend.ts b/sdk/src/spine/ModuleBackend.ts
index d1278f46f..4261e35a0 100644
--- a/sdk/src/spine/ModuleBackend.ts
+++ b/sdk/src/spine/ModuleBackend.ts
@@ -14,6 +14,8 @@ interface EntityInfo {
flipX: boolean;
flipY: boolean;
layer: number;
+ timeScale: number;
+ playing: boolean;
/** Dedup key (asset ref). Entities sharing a key share one loaded skeleton. */
assetKey?: string;
}
@@ -74,13 +76,14 @@ export class ModuleBackend {
const instanceId = this.controller_.createInstance(skelHandle);
this.entities_.set(entity, {
skelHandle, instanceId, assetKey,
- skeletonScale: 1, flipX: false, flipY: false, layer: 0,
+ skeletonScale: 1, flipX: false, flipY: false, layer: 0, timeScale: 1, playing: true,
});
return true;
}
setEntityProps(entity: Entity, props: {
skeletonScale?: number; flipX?: boolean; flipY?: boolean; layer?: number;
+ timeScale?: number; playing?: boolean; color?: { r: number; g: number; b: number; a: number };
}): void {
const info = this.entities_.get(entity);
if (!info) return;
@@ -88,6 +91,11 @@ export class ModuleBackend {
if (props.flipX !== undefined) info.flipX = props.flipX;
if (props.flipY !== undefined) info.flipY = props.flipY;
if (props.layer !== undefined) info.layer = props.layer;
+ if (props.timeScale !== undefined) info.timeScale = props.timeScale;
+ if (props.playing !== undefined) info.playing = props.playing;
+ // Whole-skeleton tint applied straight to skeleton->color (persists there until
+ // changed; re-applied on every sync so a reload/rebuild restores it).
+ if (props.color) this.controller_.setSkeletonColor(info.instanceId, props.color.r, props.color.g, props.color.b, props.color.a);
}
setAnimation(entity: Entity, animation: string, loop: boolean): void {
@@ -207,7 +215,9 @@ export class ModuleBackend {
updateAll(dt: number): void {
for (const info of this.entities_.values()) {
- this.controller_.update(info.instanceId, dt);
+ // playing=false freezes the pose (skip advance, still submitted);
+ // timeScale scales the advance (update() takes an arbitrary dt).
+ if (info.playing) this.controller_.update(info.instanceId, dt * info.timeScale);
}
}
diff --git a/sdk/src/spine/SpineController.ts b/sdk/src/spine/SpineController.ts
index 68ad82649..ad9a781f6 100644
--- a/sdk/src/spine/SpineController.ts
+++ b/sdk/src/spine/SpineController.ts
@@ -312,6 +312,11 @@ export class SpineModuleController {
return !!this.api_.setSlotColor(instanceId, slotName, r, g, b, a);
}
+ /** Whole-skeleton tint, multiplied into every vertex — backs SpineAnimation.color. */
+ setSkeletonColor(instanceId: number, r: number, g: number, b: number, a: number): boolean {
+ return !!this.api_.setSkeletonColor(instanceId, r, g, b, a);
+ }
+
// =========================================================================
// Events
// =========================================================================
diff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.ts
index 43d77760c..a0246113d 100644
--- a/sdk/src/spine/SpineManager.ts
+++ b/sdk/src/spine/SpineManager.ts
@@ -142,6 +142,7 @@ export class SpineManager {
setEntityProps(entity: Entity, props: {
skeletonScale?: number; flipX?: boolean; flipY?: boolean; layer?: number;
+ timeScale?: number; playing?: boolean; color?: { r: number; g: number; b: number; a: number };
}): void {
const version = this.entityVersions_.get(entity);
if (!version) return;
diff --git a/sdk/src/spine/SpineModuleLoader.ts b/sdk/src/spine/SpineModuleLoader.ts
index 3b52be2f7..72fc962a5 100644
--- a/sdk/src/spine/SpineModuleLoader.ts
+++ b/sdk/src/spine/SpineModuleLoader.ts
@@ -52,6 +52,7 @@ export interface SpineWasmModule {
_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;
@@ -109,6 +110,7 @@ export interface SpineWrappedAPI {
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;
@@ -156,6 +158,7 @@ export function wrapSpineModule(raw: SpineWasmModule): SpineWrappedAPI {
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'],
diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.ts
index edd795b8a..4a8635015 100644
--- a/sdk/src/spine/index.ts
+++ b/sdk/src/spine/index.ts
@@ -11,5 +11,5 @@ export type { SpineModuleFactory } from './SpineModuleLoader';
export { wrapSpineModule } from './SpineModuleLoader';
// Shared spine scene loader — the editor loads spine entities through the same
// single implementation the builder runtime uses (see ./loadSpineScene).
-export { loadSpineSceneEntities, loadSpineAssets, applySpineEntities } from './loadSpineScene';
+export { loadSpineSceneEntities, loadSpineAssets, applySpineEntities, spineEntityProps } from './loadSpineScene';
export type { RuntimeAssetSource } from '../runtimeAssets';
diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.ts
index 44fc95515..192628d78 100644
--- a/sdk/src/spine/loadSpineScene.ts
+++ b/sdk/src/spine/loadSpineScene.ts
@@ -28,6 +28,29 @@ import { parseSpineAtlasPages } from './atlasPages';
import { createTextureFromPixels, type RuntimeAssetSource } from '../runtimeAssets';
import { isKtx2Path, type BasisTranscoder } from '../asset/compressed';
+/**
+ * The in-place editable spine props from a SpineAnimation component's data — the
+ * SINGLE extraction both the scene loader and the editor's live-sync feed to
+ * `setEntityProps`, so a new prop (color/timeScale/playing/...) is carried by both
+ * paths from one place instead of being hand-listed twice.
+ */
+export function spineEntityProps(d: Record<string, unknown>): {
+ skeletonScale: number; flipX: boolean; flipY: boolean; layer: number;
+ timeScale: number; playing: boolean; color?: { r: number; g: number; b: number; a: number };
+} {
+ const num = (v: unknown, dflt: number) => (typeof v === 'number' ? v : dflt);
+ const color = d.color;
+ return {
+ skeletonScale: num(d.skeletonScale, 1),
+ flipX: d.flipX === true,
+ flipY: d.flipY === true,
+ layer: num(d.layer, 0),
+ timeScale: num(d.timeScale, 1),
+ playing: d.playing !== false,
+ color: color && typeof color === 'object' ? (color as { r: number; g: number; b: number; a: number }) : undefined,
+ };
+}
+
/** Lazily yields the realm's Basis transcoder (KTX2 atlas pages), or null where
* compressed textures can't occur (editor, uncooked dev). Same seam as the
* TextureLoader's transcoder provider. */
@@ -157,12 +180,7 @@ export async function applySpineEntities(opts: {
entity, info.skelData, info.atlasText, info.textures, registry,
`${skelRef}:${atlasRef}`);
- spineManager.setEntityProps(entity, {
- skeletonScale: (comp.data.skeletonScale as number) ?? 1,
- flipX: (comp.data.flipX as boolean) ?? false,
- flipY: (comp.data.flipY as boolean) ?? false,
- layer: (comp.data.layer as number) ?? 0,
- });
+ spineManager.setEntityProps(entity, spineEntityProps(comp.data as Record<string, unknown>));
const skin = comp.data.skin as string;
if (skin) spineManager.setSkin(entity, skin);
const animation = comp.data.animation as string;
diff --git a/src/esengine/bindings/SpineModuleEntry.cpp b/src/esengine/bindings/SpineModuleEntry.cpp
index 18a34a389..742931cda 100644
--- a/src/esengine/bindings/SpineModuleEntry.cpp
+++ b/src/esengine/bindings/SpineModuleEntry.cpp
@@ -1109,6 +1109,21 @@ int spine_setSlotColor(int instanceId, const char* slotName,
return 1;
}
+// Whole-skeleton tint: extraction already multiplies skeleton->color into every
+// vertex (skelColor * slotColor * attachColor), so this is all the wiring a
+// SpineAnimation.color needs — the skeleton-level analogue of setSlotColor.
+EMSCRIPTEN_KEEPALIVE
+int spine_setSkeletonColor(int instanceId, float r, float g, float b, float a) {
+ auto it = g_ctx.instances.find(instanceId);
+ if (it == g_ctx.instances.end()) return 0;
+
+ it->second.skeleton->color.r = r;
+ it->second.skeleton->color.g = g;
+ it->second.skeleton->color.b = b;
+ it->second.skeleton->color.a = a;
+ return 1;
+}
+
} // extern "C"
int main() {