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.

test(spine): what the 2.31ms pose is made of — and what would make it smaller

esengine447224b04253
diff --git a/sdk/benchmarks/fixtures/spine/stretchyman-38/stretchyman-pro.skel b/sdk/benchmarks/fixtures/spine/stretchyman-38/stretchyman-pro.skel
new file mode 100644
index 000000000..e77129e27
Binary files /dev/null and b/sdk/benchmarks/fixtures/spine/stretchyman-38/stretchyman-pro.skel differ
diff --git a/sdk/benchmarks/fixtures/spine/stretchyman-38/stretchyman.atlas b/sdk/benchmarks/fixtures/spine/stretchyman-38/stretchyman.atlas
new file mode 100644
index 000000000..19a3e78a5
--- /dev/null
+++ b/sdk/benchmarks/fixtures/spine/stretchyman-38/stretchyman.atlas
@@ -0,0 +1,41 @@
+
+stretchyman.png
+size: 1024,256
+format: RGBA8888
+filter: Linear,Linear
+repeat: none
+back-arm
+ rotate: true
+ xy: 679, 173
+ size: 72, 202
+ orig: 72, 202
+ offset: 0, 0
+ index: -1
+back-leg
+ rotate: true
+ xy: 2, 2
+ size: 100, 318
+ orig: 100, 318
+ offset: 0, 0
+ index: -1
+body
+ rotate: true
+ xy: 2, 104
+ size: 141, 452
+ orig: 141, 452
+ offset: 0, 0
+ index: -1
+front-arm
+ rotate: true
+ xy: 456, 100
+ size: 145, 221
+ orig: 145, 221
+ offset: 0, 0
+ index: -1
+head
+ rotate: true
+ xy: 322, 15
+ size: 87, 102
+ orig: 87, 102
+ offset: 0, 0
+ index: -1
diff --git a/sdk/benchmarks/fixtures/spine/tank-38/tank-pro.skel b/sdk/benchmarks/fixtures/spine/tank-38/tank-pro.skel
new file mode 100644
index 000000000..14354b45a
Binary files /dev/null and b/sdk/benchmarks/fixtures/spine/tank-38/tank-pro.skel differ
diff --git a/sdk/benchmarks/fixtures/spine/tank-38/tank.atlas b/sdk/benchmarks/fixtures/spine/tank-38/tank.atlas
new file mode 100644
index 000000000..71cdf9a19
--- /dev/null
+++ b/sdk/benchmarks/fixtures/spine/tank-38/tank.atlas
@@ -0,0 +1,174 @@
+
+tank.png
+size: 1024,1024
+format: RGBA8888
+filter: Linear,Linear
+repeat: none
+antenna
+ rotate: true
+ xy: 650, 857
+ size: 11, 152
+ orig: 11, 152
+ offset: 0, 0
+ index: -1
+cannon
+ rotate: true
+ xy: 434, 376
+ size: 466, 29
+ orig: 466, 29
+ offset: 0, 0
+ index: -1
+cannon-connector
+ rotate: true
+ xy: 349, 241
+ size: 56, 68
+ orig: 56, 68
+ offset: 0, 0
+ index: -1
+ground
+ rotate: true
+ xy: 255, 330
+ size: 512, 177
+ orig: 512, 177
+ offset: 0, 0
+ index: -1
+guntower
+ rotate: false
+ xy: 650, 870
+ size: 365, 145
+ orig: 365, 145
+ offset: 0, 0
+ index: -1
+machinegun
+ rotate: false
+ xy: 255, 299
+ size: 166, 29
+ orig: 166, 29
+ offset: 0, 0
+ index: -1
+machinegun-mount
+ rotate: true
+ xy: 2, 2
+ size: 36, 48
+ orig: 36, 48
+ offset: 0, 0
+ index: -1
+rock
+ rotate: true
+ xy: 465, 552
+ size: 290, 64
+ orig: 290, 64
+ offset: 0, 0
+ index: -1
+smoke-glow
+ rotate: false
+ xy: 531, 563
+ size: 50, 50
+ orig: 50, 50
+ offset: 0, 0
+ index: -1
+smoke-puff01-bg
+ rotate: true
+ xy: 465, 458
+ size: 92, 62
+ orig: 92, 62
+ offset: 0, 0
+ index: -1
+smoke-puff01-fg
+ rotate: false
+ xy: 115, 138
+ size: 88, 59
+ orig: 88, 59
+ offset: 0, 0
+ index: -1
+smoke-puff02-fg
+ rotate: false
+ xy: 255, 235
+ size: 92, 62
+ orig: 92, 62
+ offset: 0, 0
+ index: -1
+smoke-puff03-fg
+ rotate: false
+ xy: 531, 685
+ size: 92, 62
+ orig: 92, 62
+ offset: 0, 0
+ index: -1
+smoke-puff04-fg
+ rotate: true
+ xy: 465, 378
+ size: 78, 48
+ orig: 78, 48
+ offset: 0, 0
+ index: -1
+tank-bottom
+ rotate: true
+ xy: 115, 199
+ size: 643, 138
+ orig: 643, 138
+ offset: 0, 0
+ index: -1
+tank-bottom-shadow
+ rotate: false
+ xy: 2, 844
+ size: 646, 171
+ orig: 646, 171
+ offset: 0, 0
+ index: -1
+tank-top
+ rotate: true
+ xy: 2, 138
+ size: 704, 111
+ orig: 704, 111
+ offset: 0, 0
+ index: -1
+tread
+ rotate: true
+ xy: 626, 794
+ size: 48, 15
+ orig: 48, 15
+ offset: 0, 0
+ index: -1
+tread-inside
+ rotate: false
+ xy: 434, 360
+ size: 13, 14
+ orig: 13, 14
+ offset: 0, 0
+ index: -1
+wheel-big
+ rotate: false
+ xy: 2, 40
+ size: 96, 96
+ orig: 96, 96
+ offset: 0, 0
+ index: -1
+wheel-big-overlay
+ rotate: false
+ xy: 531, 749
+ size: 93, 93
+ orig: 93, 93
+ offset: 0, 0
+ index: -1
+wheel-mid
+ rotate: false
+ xy: 100, 68
+ size: 68, 68
+ orig: 68, 68
+ offset: 0, 0
+ index: -1
+wheel-mid-overlay
+ rotate: false
+ xy: 531, 615
+ size: 68, 68
+ orig: 68, 68
+ offset: 0, 0
+ index: -1
+wheel-small
+ rotate: false
+ xy: 205, 161
+ size: 36, 36
+ orig: 36, 36
+ offset: 0, 0
+ index: -1
diff --git a/sdk/benchmarks/fixtures/spine/windmill-38/windmill-ess.skel b/sdk/benchmarks/fixtures/spine/windmill-38/windmill-ess.skel
new file mode 100644
index 000000000..335dae799
Binary files /dev/null and b/sdk/benchmarks/fixtures/spine/windmill-38/windmill-ess.skel differ
diff --git a/sdk/benchmarks/fixtures/spine/windmill-38/windmill.atlas b/sdk/benchmarks/fixtures/spine/windmill-38/windmill.atlas
new file mode 100644
index 000000000..50205bcf0
--- /dev/null
+++ b/sdk/benchmarks/fixtures/spine/windmill-38/windmill.atlas
@@ -0,0 +1,188 @@
+
+windmill.png
+size: 1024,512
+format: RGBA8888
+filter: Linear,Linear
+repeat: none
+bush1
+ rotate: true
+ xy: 558, 70
+ size: 56, 38
+ orig: 56, 38
+ offset: 0, 0
+ index: -1
+bush2
+ rotate: true
+ xy: 831, 358
+ size: 67, 45
+ orig: 67, 45
+ offset: 0, 0
+ index: -1
+flower-leaf-back
+ rotate: false
+ xy: 364, 35
+ size: 16, 11
+ orig: 16, 11
+ offset: 0, 0
+ index: -1
+flower-leaf-front
+ rotate: false
+ xy: 795, 212
+ size: 16, 11
+ orig: 16, 11
+ offset: 0, 0
+ index: -1
+flower-shadow
+ rotate: false
+ xy: 999, 501
+ size: 23, 9
+ orig: 23, 9
+ offset: 0, 0
+ index: -1
+flower-stem
+ rotate: false
+ xy: 2, 4
+ size: 5, 27
+ orig: 5, 27
+ offset: 0, 0
+ index: -1
+flower1
+ rotate: false
+ xy: 599, 149
+ size: 22, 19
+ orig: 22, 19
+ offset: 0, 0
+ index: -1
+flower2
+ rotate: true
+ xy: 878, 405
+ size: 20, 17
+ orig: 20, 17
+ offset: 0, 0
+ index: -1
+flower3
+ rotate: false
+ xy: 558, 52
+ size: 15, 16
+ orig: 15, 16
+ offset: 0, 0
+ index: -1
+heat
+ rotate: false
+ xy: 949, 458
+ size: 48, 52
+ orig: 48, 52
+ offset: 0, 0
+ index: -1
+rooster
+ rotate: false
+ xy: 897, 430
+ size: 27, 25
+ orig: 27, 25
+ offset: 0, 0
+ index: -1
+tree1-leaves1
+ rotate: false
+ xy: 599, 170
+ size: 49, 53
+ orig: 49, 53
+ offset: 0, 0
+ index: -1
+tree1-leaves2
+ rotate: false
+ xy: 650, 173
+ size: 48, 50
+ orig: 48, 50
+ offset: 0, 0
+ index: -1
+tree1-leaves3
+ rotate: false
+ xy: 831, 314
+ size: 43, 42
+ orig: 43, 42
+ offset: 0, 0
+ index: -1
+tree1-leaves4
+ rotate: false
+ xy: 319, 4
+ size: 43, 42
+ orig: 43, 42
+ offset: 0, 0
+ index: -1
+tree1-trunk
+ rotate: false
+ xy: 831, 427
+ size: 64, 83
+ orig: 64, 83
+ offset: 0, 0
+ index: -1
+tree2-leaves1
+ rotate: false
+ xy: 897, 457
+ size: 50, 53
+ orig: 50, 53
+ offset: 0, 0
+ index: -1
+tree2-leaves2
+ rotate: false
+ xy: 700, 173
+ size: 48, 50
+ orig: 48, 50
+ offset: 0, 0
+ index: -1
+tree2-leaves3
+ rotate: true
+ xy: 275, 2
+ size: 44, 42
+ orig: 44, 42
+ offset: 0, 0
+ index: -1
+tree2-leaves4
+ rotate: false
+ xy: 750, 181
+ size: 43, 42
+ orig: 43, 42
+ offset: 0, 0
+ index: -1
+tree2-leaves5
+ rotate: false
+ xy: 831, 270
+ size: 42, 42
+ orig: 42, 42
+ offset: 0, 0
+ index: -1
+tree2-trunk
+ rotate: false
+ xy: 558, 128
+ size: 39, 95
+ orig: 39, 95
+ offset: 0, 0
+ index: -1
+windmill-base
+ rotate: false
+ xy: 2, 48
+ size: 554, 462
+ orig: 554, 462
+ offset: 0, 0
+ index: -1
+windmill-blades
+ rotate: false
+ xy: 558, 240
+ size: 271, 270
+ orig: 271, 270
+ offset: 0, 0
+ index: -1
+windmill-blades-wood-h
+ rotate: false
+ xy: 2, 33
+ size: 271, 13
+ orig: 271, 13
+ offset: 0, 0
+ index: -1
+windmill-blades-wood-v
+ rotate: true
+ xy: 558, 225
+ size: 13, 270
+ orig: 13, 270
+ offset: 0, 0
+ index: -1
diff --git a/sdk/benchmarks/spine-pose-stages.bench.ts b/sdk/benchmarks/spine-pose-stages.bench.ts
new file mode 100644
index 000000000..94307dd59
--- /dev/null
+++ b/sdk/benchmarks/spine-pose-stages.bench.ts
@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spine-pose-stages.bench.ts
+ * @brief What a pose is made of, and which complexity it scales with.
+ *
+ * @details Once the collector stopped being the frame's first cost, posing was:
+ * 2.31 ms of a 4.36 ms thousand-entity frame. This prices its steps the
+ * way the extraction was priced — by running it to four depths and
+ * subtracting — and then varies the SKELETON rather than the entity
+ * count, because "pose = 2.31 ms" is not a model and cannot say what
+ * would make it smaller.
+ *
+ * The counters each row reports come from the same probe, so a
+ * millisecond is always next to the timelines, bones and constraints it
+ * was spent on. Depth and counters are asserted in
+ * tests/spine-pose-stages; nothing here is on a frame path.
+ *
+ * `SPINE_POSE_REPORT=1` prints the counters each row was measured on.
+ *
+ * What it answered, ms per frame at a thousand entities (min of two
+ * runs, differences between adjacent depths):
+ *
+ * case advance apply world+constraints
+ * spineboy, nothing playing 0.005 0.045 1.623
+ * coin, 7 bones 0.010 0.147 0.127
+ * spineboy, walk 0.010 0.438 1.649
+ * spineboy, walk into run 0.010 0.490 1.660
+ * stretchyman, 4 ik 4 path 0.011 0.409 2.203
+ * raptor, 9 ik 74 bones 0.011 0.883 2.091
+ * windmill, 93 bones 0.012 0.986 1.848
+ * tank, 115 bones 0.010 0.472 4.713
+ *
+ * Advancing the tracks is flat and negligible whatever is playing.
+ * Applying is ~10 ns per timeline per entity over a fixed 0.045 ms —
+ * except under a mix, where it is half that per DECLARED timeline,
+ * because the entry mixing out skips what the one on top overrides.
+ * Resolving world transforms is the body of a pose: ~20 ns per bone per
+ * entity with no constraints, and it is the same 1.6 ms whether the
+ * skeleton is walking or playing nothing at all.
+ */
+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');
+
+/**
+ * The axes. `animation` empty means the instance plays nothing — the floor a
+ * skeleton costs for existing; `mix` sets a default mix so the second animation
+ * enters with the first still applying.
+ */
+const CASES = [
+ { name: 'spineboy, nothing playing', skel: 'spineboy-38/spineboy-pro.skel', atlas: 'spineboy-38/spineboy.atlas', animation: '' },
+ { name: 'coin, 7 bones', skel: 'coin-38/coin-pro.skel', atlas: 'coin-38/coin.atlas', animation: 'animation' },
+ { name: 'windmill, 93 bones no constraints', skel: 'windmill-38/windmill-ess.skel', atlas: 'windmill-38/windmill.atlas', animation: 'animation' },
+ { name: 'stretchyman, 4 ik 2 transform 4 path', skel: 'stretchyman-38/stretchyman-pro.skel', atlas: 'stretchyman-38/stretchyman.atlas', animation: 'sneak' },
+ { name: 'raptor, 9 ik 74 bones', skel: 'raptor-38/raptor-pro.skel', atlas: 'raptor-38/raptor.atlas', animation: 'walk' },
+ { name: 'tank, 115 bones 6 transform', skel: 'tank-38/tank-pro.skel', atlas: 'tank-38/tank.atlas', animation: 'drive' },
+ { name: 'spineboy, walk', skel: 'spineboy-38/spineboy-pro.skel', atlas: 'spineboy-38/spineboy.atlas', animation: 'walk' },
+ { name: 'spineboy, walk mixing into run', skel: 'spineboy-38/spineboy-pro.skel', atlas: 'spineboy-38/spineboy.atlas', animation: 'walk', mix: 'run' },
+] as const;
+
+const HAS_ASSETS = existsSync(SPINE38_WASM)
+ && CASES.every((c) => existsSync(resolve(FIXTURES, c.skel)));
+
+const ENTITIES = 1000;
+const FRAMES = 20;
+const DT = 1 / 60;
+const COUNTERS = [
+ 'tracks', 'entries', 'timelines', 'bones',
+ 'ik', 'transform', 'path', 'physics', 'events',
+] as const;
+
+let raw: SpineWasmModule;
+let api: SpineWrappedAPI;
+const instances = new Map<string, number[]>();
+
+beforeAll(async () => {
+ if (!HAS_ASSETS) 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);
+
+ for (const test of CASES) {
+ const skelData = new Uint8Array(readFileSync(resolve(FIXTURES, test.skel)));
+ const atlasText = readFileSync(resolve(FIXTURES, test.atlas), 'utf-8');
+ const skelHandle = withScratch(raw, (alloc) => {
+ const ptr = alloc(skelData.length);
+ raw.HEAPU8.set(skelData, ptr);
+ return api.loadSkeleton(ptr, skelData.length, atlasText, atlasText.length, true);
+ });
+ if (skelHandle < 0) throw new Error(`${test.name}: ${api.getLastError()}`);
+ for (let i = 0, pages = api.getAtlasPageCount(skelHandle); i < pages; i++) {
+ api.setAtlasPageTexture(skelHandle, i, 1, 2048, 2048);
+ }
+ if ('mix' in test) api.setDefaultMix(skelHandle, 10);
+
+ const ids: number[] = [];
+ for (let i = 0; i < ENTITIES; i++) {
+ const id = api.createInstance(skelHandle);
+ if (test.animation) {
+ if (!api.playAnimation(id, test.animation, true, 0)) {
+ throw new Error(`${test.name}: no animation "${test.animation}"`);
+ }
+ if ('mix' in test) {
+ // spine replaces an entry that was never applied rather
+ // than mixing out of it, so the first poses once before the
+ // second arrives; the mix is held open for the whole run.
+ api.probePose(id, DT, 3);
+ if (!api.playAnimation(id, test.mix, true, 0)) {
+ throw new Error(`${test.name}: no animation "${test.mix}"`);
+ }
+ }
+ }
+ api.probePose(id, DT, 3);
+ ids.push(id);
+ }
+ instances.set(test.name, ids);
+ }
+
+ if (process.env.SPINE_POSE_REPORT) report();
+});
+
+function countsOf(): Record<string, number> {
+ return withScratch(raw, (alloc) => {
+ const ptr = alloc(COUNTERS.length * 4);
+ api.probePoseCounts(ptr);
+ const out: Record<string, number> = {};
+ COUNTERS.forEach((name, i) => { out[name] = raw.HEAPU32[(ptr >> 2) + i]; });
+ return out;
+ });
+}
+
+/** What each case's skeleton is, so a millisecond can be read against it. */
+function report(): void {
+ const rows = CASES.map((test) => {
+ const id = instances.get(test.name)![0];
+ api.probePose(id, DT, 3);
+ return { case: test.name, ...countsOf() };
+ });
+ const keys = Object.keys(rows[0]);
+ const width = (k: string) => Math.max(k.length, ...rows.map((r) => String((r as never)[k]).length));
+ const line = (cells: unknown[]) => cells.map((c, i) => String(c).padStart(width(keys[i]))).join(' ');
+ console.log(line(keys));
+ for (const row of rows) console.log(line(keys.map((k) => (row as never)[k])));
+}
+
+function pass(name: string, stage: number): void {
+ const ids = instances.get(name)!;
+ for (let f = 0; f < FRAMES; f++) {
+ for (const id of ids) api.probePose(id, DT, stage);
+ }
+}
+
+describe.skipIf(!HAS_ASSETS)(`Spine pose stages: ${ENTITIES} entities x${FRAMES}`, () => {
+ for (const test of CASES) {
+ bench(`P0 crossing only — ${test.name}`, () => { pass(test.name, 0); });
+ bench(`P1 + advance tracks — ${test.name}`, () => { pass(test.name, 1); });
+ bench(`P2 + apply timelines — ${test.name}`, () => { pass(test.name, 2); });
+ bench(`P3 + world transforms — ${test.name}`, () => { pass(test.name, 3); });
+ }
+});