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
feat(spine): a skeleton an editor can pose without the frame posing it
esengine1e88ee0f414f
diff --git a/desktop b/desktopindex ceeb57be8..fd428f521 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit ceeb57be83c75da1825482c6b188dfeb84cb2730+Subproject commit fd428f521583d2cba5fdaa4c8c970319d54c63c2diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.mdindex 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) => Probserve: (on: boolean) => voidobservedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | nullobserving: boolean+openPreview: (era: SpineEraBinding) => Promise<SpinePreviewInstance | null>removeEntity: (entity: Entity) => voidsetAnimation: (entity: Entity, animation: string, loop: boolean) => voidsetAttachment: (entity: Entity, slotName: string, attachmentName: string) => boolean@@ -291,6 +292,19 @@ worldAlreadyCurrent: numberworldMaterializations: 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) => booleanmetrics: () => SpineFrameMetrics | nullobserve: (on: boolean) => voidobservedBounds: (entity: Entity, sampleStep?: number) => SpineCullingEnvelope | null+openPreview: (era: SpineEraBinding) => SpinePreviewInstance | nullposeEligibility: (entity: Entity) => { culling: SpineCullingEnvelope; requiresContinuousWorldPose: boolean; } | nullremoveEntity: (entity: Entity) => voidresidencies: () => SpineResidencyFacts[]diff --git a/sdk/src/spine/SpineManager.ts b/sdk/src/spine/SpineManager.tsindex 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.tsindex 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.tsindex af6416bd8..62c190c85 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -24,6 +24,7 @@ export { spineSceneDiagnostics, formatSpineDiagnostics } from './spineSceneDiagnexport 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.tsindex 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;+}