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.

feat(spine): a skeleton an editor can pose without the frame posing it

esengine1e88ee0f414f
diff --git a/desktop b/desktop
index ceeb57be8..fd428f521 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit ceeb57be83c75da1825482c6b188dfeb84cb2730
+Subproject commit fd428f521583d2cba5fdaa4c8c970319d54c63c2
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 04d86eee0..13bb698fd 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 91,
- "experimental": 1672,
+ "experimental": 1673,
"deprecated": 3
},
- "total": 1876,
+ "total": 1877,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index f3612eec5..7d1e7228a 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: 0 public · 1 beta · 47 experimental · 0 deprecated
+Symbols: 0 public · 1 beta · 48 experimental · 0 deprecated
## ConstraintList — interface @experimental
```
@@ -193,6 +193,7 @@ loadEntity: (entity: Entity, era: SpineEraBinding, _registry: CppRegistry) => Pr
observe: (on: boolean) => void
observedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | null
observing: boolean
+openPreview: (era: SpineEraBinding) => Promise<SpinePreviewInstance | null>
removeEntity: (entity: Entity) => void
setAnimation: (entity: Entity, animation: string, loop: boolean) => void
setAttachment: (entity: Entity, slotName: string, attachmentName: string) => boolean
@@ -291,6 +292,19 @@ worldAlreadyCurrent: number
worldMaterializations: number
```
+## SpinePreviewInstance — interface @experimental
+```
+advance: (dt: number) => void
+animations: () => string[]
+clipBudget: () => SpineClipBudget | null
+dispose: () => void
+duration: (animation: string) => number
+forEachMeshBatch: (visit: MeshBatchVisitor) => void
+play: (animation: string) => void
+setSkin: (skin: string) => void
+skins: () => string[]
+```
+
## SpineResidencyFacts — interface @experimental
```
culling: SpineCullingEnvelope
@@ -321,6 +335,7 @@ mayDefer: (entity: Entity) => boolean
metrics: () => SpineFrameMetrics | null
observe: (on: boolean) => void
observedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | null
+openPreview: (era: SpineEraBinding) => SpinePreviewInstance | null
poseEligibility: (entity: Entity) => { culling: SpineCullingEnvelope; requiresContinuousWorldPose: boolean; } | null
removeEntity: (entity: Entity) => void
residencies: () => SpineResidencyFacts[]
diff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.ts
index 35cb848ed..be90bbfbc 100644
--- a/sdk/src/spine/SpineManager.ts
+++ b/sdk/src/spine/SpineManager.ts
@@ -10,7 +10,7 @@ import { SpineRuntime } from './SpineRuntime';
import type { SpineEraBinding } from './prepareSpine';
import type { SpineClipBudget } from './spineMetrics';
import { spineSceneDiagnostics } from './spineSceneDiagnostics';
-import type { SpineSceneDiagnostics } from './spineSceneDiagnostics';
+import type { SpineSceneDiagnostics, SpinePreviewInstance } from './spineSceneDiagnostics';
import type { SpineCullingEnvelope } from './spineBounds';
import { log } from '../util/logger';
@@ -164,6 +164,21 @@ export class SpineManager {
for (const runtime of this.runtimes_.values()) runtime.observe(on);
}
+ /**
+ * Open a skeleton for an editor to pose itself, outside this manager's
+ * bindings: it is never advanced by `updateAnimations` and never drawn by
+ * `submitMeshes`. Null when the era's version has no runtime here.
+ */
+ async openPreview(era: SpineEraBinding): Promise<SpinePreviewInstance | null> {
+ const { skelData } = era.value;
+ const version = typeof skelData === 'string'
+ ? SpineManager.detectVersionJson(skelData)
+ : SpineManager.detectVersion(skelData);
+ if (!version) return null;
+ const runtime = await this.ensureRuntime(version);
+ return runtime ? runtime.openPreview(era) : null;
+ }
+
/** Whether anything is counting. */
get observing(): boolean {
return this.observing_;
diff --git a/sdk/src/spine/SpineRuntime.ts b/sdk/src/spine/SpineRuntime.ts
index 7c5e42d13..a9036f11b 100644
--- a/sdk/src/spine/SpineRuntime.ts
+++ b/sdk/src/spine/SpineRuntime.ts
@@ -31,7 +31,7 @@ import { mayDeferWorldPose, scanObservedBounds } from './spineBounds';
import type { SpineBoundsSource } from './spineBounds';
import type { SpineCullingEnvelope } from './spineBounds';
import { withScratch } from '../wasm/wasmScratch';
-import type { SpineResidencyFacts } from './spineSceneDiagnostics';
+import type { SpineResidencyFacts, SpinePreviewInstance } from './spineSceneDiagnostics';
/**
* What a camera said about an entity. `unknown` is not a no — it is the absence
@@ -405,6 +405,43 @@ export class SpineRuntime {
};
}
+ /**
+ * A skeleton posed by nobody but its caller.
+ *
+ * Outside `entities_` on purpose — the map `updateAll` and the submit both
+ * walk — so a preview is never advanced or drawn by the frame. What it gives
+ * back is the same instance and the same batch walk a scene entity gets.
+ */
+ openPreview(era: SpineEraBinding): SpinePreviewInstance | null {
+ const skelHandle = this.claimSkeleton_(era);
+ if (skelHandle < 0) return null;
+ const instanceId = this.controller_.createInstance(skelHandle);
+ if (instanceId < 0) {
+ log.error('spine', `Failed to create preview instance: ${this.controller_.getLastError()}`);
+ this.releaseSkeleton_({ skelHandle, era: era.id } as EntityInfo);
+ return null;
+ }
+ const controller = this.controller_;
+ let open = true;
+ return {
+ animations: () => (open ? controller.getAnimations(instanceId) : []),
+ skins: () => (open ? controller.getSkins(instanceId) : []),
+ play: (animation) => { if (open) controller.play(instanceId, animation, false); },
+ setSkin: (skin) => { if (open) controller.setSkin(instanceId, skin); },
+ advance: (dt) => { if (open) controller.advanceAndApply(instanceId, dt); },
+ duration: (animation) =>
+ (open ? Math.max(0, controller.animationDuration(skelHandle, animation)) : 0),
+ clipBudget: () => (open ? controller.clipBudget(instanceId) : null),
+ forEachMeshBatch: (cb) => { if (open) controller.forEachMeshBatch(instanceId, cb); },
+ dispose: () => {
+ if (!open) return;
+ open = false;
+ controller.destroyInstance(instanceId);
+ this.releaseSkeleton_({ skelHandle, era: era.id } as EntityInfo);
+ },
+ };
+ }
+
/** Every residency this runtime holds, for a scene-level diagnostic. */
residencies(): SpineResidencyFacts[] {
const out: SpineResidencyFacts[] = [];
diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.ts
index af6416bd8..62c190c85 100644
--- a/sdk/src/spine/index.ts
+++ b/sdk/src/spine/index.ts
@@ -24,6 +24,7 @@ export { spineSceneDiagnostics, formatSpineDiagnostics } from './spineSceneDiagn
export type {
SpineSceneDiagnostics, SpineAssetDiagnostic, SpineFinding, SpineFindingCode,
SpineDeferralBlocker, SpinePoseTotals, SpineResidencyFacts, SpineDiagnosticRuntime,
+ SpinePreviewInstance,
} from './spineSceneDiagnostics';
// Shared spine scene loader — the editor loads spine entities through the same
// single implementation the builder runtime uses (see ./loadSpineScene).
diff --git a/sdk/src/spine/spineSceneDiagnostics.ts b/sdk/src/spine/spineSceneDiagnostics.ts
index 6842c072c..4455ac3ef 100644
--- a/sdk/src/spine/spineSceneDiagnostics.ts
+++ b/sdk/src/spine/spineSceneDiagnostics.ts
@@ -28,6 +28,8 @@
import type { SpineVersion } from '../sideModules/registry';
import type { SpineCullingEnvelope } from './spineBounds';
import type { SpinePair } from './prepareSpine';
+import type { SpineClipBudget } from './spineMetrics';
+import type { MeshBatchVisitor } from '../skeletal/meshBatches';
import type { SpineAbiCounts, SpineByteCounts, SpineFrameMetrics,
SpineTimeWindow } from './spineMetrics';
@@ -393,3 +395,22 @@ export function formatSpineDiagnostics(d: SpineSceneDiagnostics): string {
for (const finding of d.findings) lines.push(...wrapped(' * ', sentence(finding)));
return lines.join('\n');
}
+
+/**
+ * One skeleton an editor poses itself: outside the frame's tick and its submit,
+ * driven only by whoever opened it. The batch walk is the SAME one a scene
+ * entity's geometry crosses — a preview posed another way draws another thing.
+ */
+export interface SpinePreviewInstance {
+ animations(): string[];
+ skins(): string[];
+ /** Start `animation` from its beginning, unlooped — the caller owns the clock. */
+ play(animation: string): void;
+ setSkin(skin: string): void;
+ advance(dt: number): void;
+ duration(animation: string): number;
+ /** What clipping costs in the pose it is standing in. */
+ clipBudget(): SpineClipBudget | null;
+ forEachMeshBatch(visit: MeshBatchVisitor): void;
+ dispose(): void;
+}