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
test(spine): how many of a frame's poses anyone asked for
esengine032cce845bb8
diff --git a/sdk/benchmarks/spine-pose-demand.bench.ts b/sdk/benchmarks/spine-pose-demand.bench.tsnew file mode 100644index 000000000..c834b9810--- /dev/null+++ b/sdk/benchmarks/spine-pose-demand.bench.ts@@ -0,0 +1,131 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spine-pose-demand.bench.ts+ * @brief What a frame would keep if only the entities someone can see were+ * given a world pose.+ *+ * @details Every bound entity is posed, extracted and submitted, whatever the+ * camera can see — asserted in tests/spine-pose-demand, which is the+ * baseline this is measured against. So the question is not whether+ * skipping is possible but what it is worth, and the answer has to be+ * measured rather than projected from a per-entity number.+ *+ * Three tiers, run over the same entities:+ *+ * full what the runtime does now: advance, apply, world+ * transform, extract, submit+ * logical advance and apply only — the animation clock keeps its+ * meaning, no world pose is materialised, nothing is drawn+ * frozen nothing advances at all+ *+ * `logical` is what an offscreen entity would cost under demand-driven+ * posing, and it is measured through the staged pose rather than+ * guessed: depth 2 IS advance-and-apply. The gap between it and `full`+ * is the ceiling on what visibility scheduling can recover, before any+ * of the correctness questions — events owed, bones read, constraints+ * that cannot take one big step — are answered.+ *+ * ms per frame, 1000 entities, min of the run:+ *+ * scene today demand-driven frozen+ * all visible 3.14 3.14 3.16+ * 200 visible, 800 not 3.14 1.01 0.62+ * none visible 3.14 0.49 0.00+ *+ * A scene where four fifths of the skeletons are off camera pays the+ * same 3.14 ms as one where none of them are, and would pay 1.01 —+ * 2.13 ms a frame, 3.1x, for a decision nothing currently makes.+ *+ * What the third column is for: freezing the clock as well buys only+ * another 0.39 ms of that 2.52. Keeping every animation's time+ * meaning — events, mixes, track positions — costs 15% of the win,+ * which is what says the thing worth skipping is the world transform+ * and never the animation state.+ */+import { describe, bench, beforeAll } from 'vitest';+import { existsSync, readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import { WASM_DIR } from '../tests/helpers/loadWasm';+import { wrapSpineModule } from '../src/spine/SpineModuleLoader';+import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';+import { withScratch } from '../src/wasm/wasmScratch';++const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');+const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');+const FIXTURES = resolve(__dirname, 'fixtures/spine');+const HAS_WASM = existsSync(SPINE38_WASM)+ && existsSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel'));++const ENTITIES = 1000;+const FRAMES = 20;+const DT = 1 / 60;+const POSE_APPLY = 2;++/** How many of the thousand a camera can see. */+const SCENES = [+ { name: 'all visible', visible: ENTITIES },+ { name: '200 visible, 800 not', visible: 200 },+ { name: 'none visible', visible: 0 },+];++let raw: SpineWasmModule;+let api: SpineWrappedAPI;+const instances: number[] = [];++beforeAll(async () => {+ if (!HAS_WASM) return;+ const factory = (await import(SPINE38_JS)).default as (opts: unknown) => Promise<SpineWasmModule>;+ const bytes = readFileSync(SPINE38_WASM);+ raw = await factory({+ instantiateWasm(imports: WebAssembly.Imports, cb: (i: WebAssembly.Instance, m: WebAssembly.Module) => void) {+ void WebAssembly.instantiate(bytes, imports).then((r) => cb(r.instance, r.module));+ return {};+ },+ });+ api = wrapSpineModule(raw);++ const skelData = new Uint8Array(readFileSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel')));+ const atlasText = readFileSync(resolve(FIXTURES, 'spineboy-38/spineboy.atlas'), 'utf-8');+ const handle = withScratch(raw, (alloc) => {+ const ptr = alloc(skelData.length);+ raw.HEAPU8.set(skelData, ptr);+ return api.loadSkeleton(ptr, skelData.length, atlasText, atlasText.length, true);+ });+ if (handle < 0) throw new Error(api.getLastError());+ api.setAtlasPageTexture(handle, 0, 1, 2048, 2048);+ for (let i = 0; i < ENTITIES; i++) {+ const id = api.createInstance(handle);+ if (!api.playAnimation(id, 'walk', true, 0)) throw new Error('no walk');+ api.update(id, 0.1 + i * 0.001);+ instances.push(id);+ }+});++/** What a visible entity costs: the whole thing, extraction included. */+function full(from: number, to: number): void {+ for (let i = from; i < to; i++) {+ api.update(instances[i], DT);+ api.getMeshBatchCount(instances[i]);+ }+}++/** What an unseen one would cost: the clock keeps running, nothing is posed. */+function logical(from: number, to: number): void {+ for (let i = from; i < to; i++) api.probePose(instances[i], DT, POSE_APPLY);+}++function scene(visible: number, unseen: (from: number, to: number) => void): void {+ for (let f = 0; f < FRAMES; f++) {+ full(0, visible);+ unseen(visible, ENTITIES);+ }+}++describe.skipIf(!HAS_WASM)(`Spine pose demand: ${ENTITIES} entities x${FRAMES}`, () => {+ for (const s of SCENES) {+ bench(`today — ${s.name}`, () => { scene(s.visible, full); });+ bench(`demand-driven — ${s.name}`, () => { scene(s.visible, logical); });+ bench(`frozen — ${s.name}`, () => { scene(s.visible, () => {}); });+ }+});diff --git a/sdk/src/spine/SpineModuleLoader.ts b/sdk/src/spine/SpineModuleLoader.tsindex bfa334592..3c5848ea8 100644--- a/sdk/src/spine/SpineModuleLoader.ts+++ b/sdk/src/spine/SpineModuleLoader.ts@@ -27,6 +27,7 @@ export interface SpineWasmModule {_spine_getBonePosition(instanceId: number, bone: number, outXPtr: number, outYPtr: number): number;_spine_getBoneRotation(instanceId: number, bone: 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_getMeshBatchCount(instanceId: number): number;_spine_getMeshBatchVertexCount(instanceId: number, batchIndex: number): number;@@ -97,6 +98,8 @@ export interface SpineWrappedAPI {getBonePosition(instanceId: number, bone: string, outXPtr: number, outYPtr: number): boolean;getBoneRotation(instanceId: number, bone: string): 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;getMeshBatchVertexCount(instanceId: number, batchIndex: number): number;getMeshBatchIndexCount(instanceId: number, batchIndex: number): number;@@ -167,6 +170,7 @@ export function wrapSpineModule(raw: SpineWasmModule): SpineWrappedAPI {getBonePosition: cw('spine_getBonePosition', 'number', ['number', 'string', 'number', 'number']) as SpineWrappedAPI['getBonePosition'],getBoneRotation: cw('spine_getBoneRotation', 'number', ['number', 'string']) as SpineWrappedAPI['getBoneRotation'],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'],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'],diff --git a/sdk/tests/spine-pose-demand.test.ts b/sdk/tests/spine-pose-demand.test.tsnew file mode 100644index 000000000..6520b3c52--- /dev/null+++ b/sdk/tests/spine-pose-demand.test.ts@@ -0,0 +1,209 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spine-pose-demand.test.ts+ * @brief How many of a frame's poses anyone asked for.+ *+ * @details Posing is the largest thing left in a Spine frame and it is spent+ * per bound entity, unconditionally. Before anything is skipped, the+ * waste has to be a number and the structure has to be checked: a+ * visibility test that needs THIS frame's pose to decide whether to+ * compute this frame's pose saves nothing.+ *+ * So this freezes two facts. What the runtime does today — every bound+ * entity, every frame, whatever the camera can see — and what could+ * decide otherwise: the authored extent, answerable from the data with+ * no instance and no pose, against which the posed extent is measured+ * here so its conservatism is a number rather than a hope.+ */+import { describe, it, expect, beforeAll } from 'vitest';+import { existsSync, readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import { WASM_DIR } from './helpers/loadWasm';+import { wrapSpineModule } from '../src/spine/SpineModuleLoader';+import type { SpineWasmModule, SpineWrappedAPI } from '../src/spine/SpineModuleLoader';+import { SpineRuntime } from '../src/spine/SpineRuntime';+import type { SpineEraBinding } from '../src/spine/prepareSpine';+import type { Entity } from '../src/types';+import { withScratch } from '../src/wasm/wasmScratch';++const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');+const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');+const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine');+const HAS_WASM = existsSync(SPINE38_WASM)+ && existsSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel'));++let raw: SpineWasmModule;+let api: SpineWrappedAPI;+let skelData: Uint8Array;+let atlasText: string;++beforeAll(async () => {+ if (!HAS_WASM) return;+ const factory = (await import(SPINE38_JS)).default as (opts: unknown) => Promise<SpineWasmModule>;+ const bytes = readFileSync(SPINE38_WASM);+ raw = await factory({+ instantiateWasm(imports: WebAssembly.Imports, cb: (i: WebAssembly.Instance, m: WebAssembly.Module) => void) {+ void WebAssembly.instantiate(bytes, imports).then((r) => cb(r.instance, r.module));+ return {};+ },+ });+ api = wrapSpineModule(raw);+ skelData = new Uint8Array(readFileSync(resolve(FIXTURES, 'spineboy-38/spineboy-pro.skel')));+ atlasText = readFileSync(resolve(FIXTURES, 'spineboy-38/spineboy.atlas'), 'utf-8');+});++function loadSkeleton(): number {+ const handle = withScratch(raw, (alloc) => {+ const ptr = alloc(skelData.length);+ raw.HEAPU8.set(skelData, ptr);+ return api.loadSkeleton(ptr, skelData.length, atlasText, atlasText.length, true);+ });+ if (handle < 0) throw new Error(api.getLastError());+ api.setAtlasPageTexture(handle, 0, 1, 2048, 2048);+ return handle;+}++interface Rect { x: number; y: number; width: number; height: number }++function authoredBounds(skeletonHandle: number): Rect | null {+ return withScratch(raw, (alloc) => {+ const ptr = alloc(16);+ const ok = api.getSkeletonBounds(skeletonHandle, ptr, ptr + 4, ptr + 8, ptr + 12);+ if (!ok) return null;+ const f32 = raw.HEAPF32;+ const at = ptr >> 2;+ return { x: f32[at], y: f32[at + 1], width: f32[at + 2], height: f32[at + 3] };+ });+}++function posedBounds(instanceId: number): Rect {+ return withScratch(raw, (alloc) => {+ const ptr = alloc(16);+ api.getBounds(instanceId, ptr, ptr + 4, ptr + 8, ptr + 12);+ const f32 = raw.HEAPF32;+ const at = ptr >> 2;+ return { x: f32[at], y: f32[at + 1], width: f32[at + 2], height: f32[at + 3] };+ });+}++/** A runtime whose per-entity work can be counted from the outside. */+function countingRuntime(): { runtime: SpineRuntime; calls: Record<string, number> } {+ const calls: Record<string, number> = { update: 0, batchCount: 0, submit: 0 };+ const cwrap = raw.cwrap.bind(raw);+ const watched = Object.create(raw) as SpineWasmModule;+ watched.cwrap = ((name: string, ret: unknown, args: unknown) => {+ const fn = cwrap(name, ret as never, args as never);+ return (...called: unknown[]) => {+ if (name === 'spine_update') calls.update++;+ if (name === 'spine_getMeshBatchCount') calls.batchCount++;+ return (fn as (...a: unknown[]) => unknown)(...called);+ };+ }) as never;+ return { runtime: new SpineRuntime('3.8', watched), calls };+}++function era(id: string): SpineEraBinding {+ return {+ id,+ value: { skelData, atlasText, isBinary: true, textures: new Map() },+ retain: () => ({ release: () => {} }),+ };+}++const core = {+ renderer_submitSkeletalBatchByEntity: () => {},+ _malloc: () => 0, _free: () => {}, HEAPU8: new Uint8Array(1 << 20),+} as never;++describe.skipIf(!HAS_WASM)('what a spine frame poses, and who asked', () => {+ it('every bound entity is posed and extracted, whatever the camera can see', () => {+ // The baseline the next cut is measured against. There is no visibility+ // test on this path at all — not one that needs the pose first, none.+ const { runtime, calls } = countingRuntime();+ const entities = 50;+ for (let i = 0; i < entities; i++) {+ runtime.loadEntity(i as Entity, era('demand#1'));+ runtime.setAnimation(i as Entity, 'walk', true);+ }+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(core, {} as never);++ expect(calls.update, 'a pose was skipped for some entity').toBe(entities);+ expect(calls.batchCount, 'an extraction was skipped for some entity').toBe(entities);+ runtime.dispose();+ });++ it('the two policies that do skip are the only ones there are', () => {+ // `disabled` leaves the frame entirely; `playing=false` freezes the pose+ // but is still extracted and submitted, because a frozen skeleton is+ // still drawn. Nothing else can decline.+ const { runtime, calls } = countingRuntime();+ for (let i = 0; i < 6; i++) {+ runtime.loadEntity(i as Entity, era('demand#2'));+ runtime.setAnimation(i as Entity, 'walk', true);+ }+ runtime.setEntityProps(0 as Entity, { playing: false });+ runtime.setEntityProps(1 as Entity, { playing: false });+ runtime.setEnabled(2 as Entity, false);++ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(core, {} as never);++ expect(calls.update, 'frozen and disabled entities did not both decline a pose').toBe(3);+ expect(calls.batchCount, 'a frozen entity stopped being drawn').toBe(5);+ runtime.dispose();+ });++ it('the extent a frame is culled by today is the one the pose produced', () => {+ // The circularity a demand-driven pose has to break: this answer costs+ // exactly the world transform it would be consulted to avoid.+ const handle = loadSkeleton();+ const instanceId = api.createInstance(handle);+ api.playAnimation(instanceId, 'walk', true, 0);++ api.update(instanceId, 0.4);+ const walking = posedBounds(instanceId);+ api.update(instanceId, 0.4);+ const later = posedBounds(instanceId);++ expect(walking.width).toBeGreaterThan(0);+ expect(later, 'the posed extent does not move with the pose').not.toEqual(walking);+ });++ it('the authored extent answers before any instance exists', () => {+ const handle = loadSkeleton();+ const authored = authoredBounds(handle);+ expect(authored, 'the runtime cannot report an authored extent').not.toBeNull();+ expect(authored!.width).toBeGreaterThan(0);+ expect(authored!.height).toBeGreaterThan(0);+ });++ it('the authored extent is not conservative on its own', () => {+ // It is the SETUP pose's, so an animation reaches outside it. Reported+ // rather than assumed, because a visibility test built on it needs to+ // know by how much — this is the padding the next cut has to justify.+ const handle = loadSkeleton();+ const authored = authoredBounds(handle)!;+ const instanceId = api.createInstance(handle);+ api.playAnimation(instanceId, 'walk', true, 0);++ let worst = 0;+ for (let frame = 0; frame < 60; frame++) {+ api.update(instanceId, 1 / 60);+ const posed = posedBounds(instanceId);+ worst = Math.max(worst,+ authored.x - posed.x,+ authored.y - posed.y,+ (posed.x + posed.width) - (authored.x + authored.width),+ (posed.y + posed.height) - (authored.y + authored.height));+ }+ const overshoot = worst / Math.max(authored.width, authored.height);+ if (process.env.SPINE_DEMAND_REPORT) {+ console.log(`authored ${JSON.stringify(authored)} worst overshoot ${worst.toFixed(1)}`+ + ` (${(overshoot * 100).toFixed(1)}% of the authored extent)`);+ }+ expect(worst, 'a walk cycle stayed inside the setup extent').toBeGreaterThan(0);+ expect(overshoot, 'the authored extent is too far off to pad').toBeLessThan(1);+ });+});diff --git a/src/esengine/bindings/modules/spine/SpineBindings.hpp b/src/esengine/bindings/modules/spine/SpineBindings.hppindex e9c092154..99ef8dc1c 100644--- a/src/esengine/bindings/modules/spine/SpineBindings.hpp+++ b/src/esengine/bindings/modules/spine/SpineBindings.hpp@@ -89,6 +89,10 @@ int spine_probe_extract(int instanceId, int stage, int useCollector);// The twenty-four counters of the last probe run, into as many u32 slots.void spine_probe_counts(uint32_t* out);+// The skeleton's authored extent, into four floats. No instance, no pose.+int spine_getSkeletonBounds(int skeletonHandle, uintptr_t outXPtr, uintptr_t outYPtr,+ uintptr_t outWPtr, uintptr_t outHPtr);+// BENCHMARK ONLY — open the first clip region to `stage` (es::spine::ClipStartStage).int spine_probe_clip_start(int instanceId, int stage);diff --git a/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp b/src/esengine/bindings/modules/spine/SpineModuleEntry.cppindex 9613fc0f7..00146318e 100644--- a/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp+++ b/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp@@ -262,6 +262,23 @@ void spine_getBounds(int instanceId, uintptr_t outXPtr, uintptr_t outYPtr,reinterpret_cast<float*>(outWPtr), reinterpret_cast<float*>(outHPtr));}+/**+ * The skeleton's AUTHORED extent, into four floats. Answerable from the data+ * alone — no instance, no pose — which is what makes it usable for deciding+ * whether a pose is worth computing. Zero and false where the runtime cannot+ * report it.+ */+EMSCRIPTEN_KEEPALIVE+int spine_getSkeletonBounds(int skeletonHandle, uintptr_t outXPtr, uintptr_t outYPtr,+ uintptr_t outWPtr, uintptr_t outHPtr) {+ auto* x = reinterpret_cast<float*>(outXPtr);+ auto* y = reinterpret_cast<float*>(outYPtr);+ auto* w = reinterpret_cast<float*>(outWPtr);+ auto* h = reinterpret_cast<float*>(outHPtr);+ *x = *y = *w = *h = 0.0f;+ return es::spine::skeletonBounds(g_ctx.skeletonOf(skeletonHandle), x, y, w, h) ? 1 : 0;+}+// =============================================================================// Mesh Extraction// =============================================================================diff --git a/src/esengine/bindings/modules/spine/SpineRuntime.hpp b/src/esengine/bindings/modules/spine/SpineRuntime.hppindex 96c8bb705..da914c16f 100644--- a/src/esengine/bindings/modules/spine/SpineRuntime.hpp+++ b/src/esengine/bindings/modules/spine/SpineRuntime.hpp@@ -197,6 +197,14 @@ bool bonePosition(const Instance* instance, const char* bone, float* x, float* ybool boneRotation(const Instance* instance, const char* bone, float* degrees);void bounds(const Instance* instance, float* x, float* y, float* width, float* height);+/**+ * The bounds the skeleton was AUTHORED with — from the data, before any instance+ * exists and without posing one. A weaker promise than {@link bounds}, being the+ * setup pose's extent, which an animation reaches outside of; what it can do+ * that a posed extent cannot is decide whether a pose is worth computing.+ */+bool skeletonBounds(const Skeleton* skeleton, float* x, float* y, float* width, float* height);+int constraintCount(const Instance* instance, ConstraintKind kind);const char* constraintName(const Instance* instance, ConstraintKind kind, int index);bool transformMix(const Instance* instance, const char* name, TransformMix* out);diff --git a/src/esengine/bindings/modules/spine/SpineRuntime21.cpp b/src/esengine/bindings/modules/spine/SpineRuntime21.cppindex e0f3fd99c..6eae5ed99 100644--- a/src/esengine/bindings/modules/spine/SpineRuntime21.cpp+++ b/src/esengine/bindings/modules/spine/SpineRuntime21.cpp@@ -569,6 +569,10 @@ bool clipStartStage(Instance*, int, ClipStartCounts*) {return false;}+bool skeletonBounds(const Skeleton*, float*, float*, float*, float*) {+ return false;+}+int version() {return ES_SPINE_VERSION;}diff --git a/src/esengine/bindings/modules/spine/SpineRuntimeC.cpp b/src/esengine/bindings/modules/spine/SpineRuntimeC.cppindex f599e561d..eb66b8fb5 100644--- a/src/esengine/bindings/modules/spine/SpineRuntimeC.cpp+++ b/src/esengine/bindings/modules/spine/SpineRuntimeC.cpp@@ -439,6 +439,15 @@ bool boneRotation(const Instance* instance, const char* bone, float* degrees) {return true;}+bool skeletonBounds(const Skeleton* skeleton, float* x, float* y, float* width, float* height) {+ if (!skeleton || !skeleton->data) return false;+ *x = skeleton->data->x;+ *y = skeleton->data->y;+ *width = skeleton->data->width;+ *height = skeleton->data->height;+ return true;+}+void bounds(const Instance* instance, float* x, float* y, float* width, float* height) {*x = *y = *width = *height = 0.0f;if (!instance) return;diff --git a/src/esengine/bindings/modules/spine/SpineRuntimeCpp.cpp b/src/esengine/bindings/modules/spine/SpineRuntimeCpp.cppindex ad99f713c..2b21d8c9a 100644--- a/src/esengine/bindings/modules/spine/SpineRuntimeCpp.cpp+++ b/src/esengine/bindings/modules/spine/SpineRuntimeCpp.cpp@@ -550,6 +550,10 @@ bool clipStartStage(Instance*, int, ClipStartCounts*) {return false;}+bool skeletonBounds(const Skeleton*, float*, float*, float*, float*) {+ return false;+}+int version() {return ES_SPINE_VERSION;}