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): the runtime's cost baseline — crossings first, then time
esengine2abaa0851c82
diff --git a/sdk/benchmarks/spine-runtime.bench.ts b/sdk/benchmarks/spine-runtime.bench.tsnew file mode 100644index 000000000..9d531f423--- /dev/null+++ b/sdk/benchmarks/spine-runtime.bench.ts@@ -0,0 +1,124 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spine-runtime.bench.ts+ * @brief What a frame of spine costs through the RUNTIME, not the ABI adapter.+ *+ * @details spine.bench.ts times the module: parse, pose, read back. This times+ * the pass a scene actually runs — `updateAll` and+ * `extractAndSubmitMeshes` over a runtime's entities, with the+ * per-entity bookkeeping and the copy into the engine's heap included,+ * which is where a frame's cost is actually paid.+ *+ * Two axes beyond entity count: whether the entities share one era+ * (the residency the runtime keeps) and whether the frame reads poses+ * back. The crossing counts behind these numbers are asserted in+ * tests/spine-abi-cost.test.ts — this is how long they take.+ */+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 type { SpineWasmModule } from '../src/spine/SpineModuleLoader';+import { SpineRuntime } from '../src/spine/SpineRuntime';+import type { SpineEraBinding } from '../src/spine/prepareSpine';+import type { Entity } from '../src/types';++const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');+const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');+const FIXTURES = resolve(__dirname, 'fixtures/spine/spineboy-38');+const HAS_ASSETS = existsSync(SPINE38_WASM) && existsSync(resolve(FIXTURES, 'spineboy-pro.skel'));++let module38: SpineWasmModule;+let skelData: Uint8Array;+let atlasText: string;++beforeAll(async () => {+ if (!HAS_ASSETS) return;+ const factory = (await import(SPINE38_JS)).default as (opts: unknown) => Promise<SpineWasmModule>;+ const bytes = readFileSync(SPINE38_WASM);+ module38 = 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 {};+ },+ });+ skelData = new Uint8Array(readFileSync(resolve(FIXTURES, 'spineboy-pro.skel')));+ atlasText = readFileSync(resolve(FIXTURES, 'spineboy.atlas'), 'utf-8');+});++function era(id: string): SpineEraBinding {+ return {+ id,+ value: {+ skelData, atlasText, isBinary: true,+ textures: new Map([['spineboy.png', { glId: 1, w: 1024, h: 1024 }]]),+ },+ retain: () => ({ release: () => {} }),+ };+}++/** An engine core that takes the geometry and drops it: what is timed here is+ * the walk and the copy, not a renderer. */+function fakeCore() {+ const heap = new Uint8Array(1 << 24);+ let top = 0;+ return {+ renderer_submitSkeletalBatchByEntity: () => {},+ _malloc: (size: number) => { const at = top; top += size; return at; },+ _free: () => { top = 0; },+ HEAPU8: heap,+ };+}++function populated(entities: number, eras: number): SpineRuntime {+ const runtime = new SpineRuntime('3.8', module38);+ for (let i = 0; i < entities; i++) {+ const entity = (i + 1) as Entity;+ runtime.loadEntity(entity, era(`hero#${i % eras}`));+ runtime.setAnimation(entity, 'walk', true);+ }+ return runtime;+}++const DT = 1 / 60;+const FRAMES = 60;+const core = fakeCore();++/** One populated runtime per case, so the measured loop is only the frame. */+function frames(runtime: SpineRuntime, submit: boolean): void {+ for (let f = 0; f < FRAMES; f++) {+ runtime.updateAll(DT);+ if (submit) runtime.extractAndSubmitMeshes(core as never, {} as never);+ }+}++describe.skipIf(!HAS_ASSETS)('Spine runtime frame: pose only', () => {+ for (const entities of [100, 500, 1000]) {+ let runtime: SpineRuntime;+ bench(`${entities} entities x${FRAMES} frames`, () => { frames(runtime, false); }, {+ setup: () => { runtime = populated(entities, 1); },+ teardown: () => { runtime.dispose(); },+ });+ }+});++describe.skipIf(!HAS_ASSETS)('Spine runtime frame: pose + submit', () => {+ for (const entities of [100, 500, 1000]) {+ let runtime: SpineRuntime;+ bench(`${entities} entities x${FRAMES} frames`, () => { frames(runtime, true); }, {+ setup: () => { runtime = populated(entities, 1); },+ teardown: () => { runtime.dispose(); },+ });+ }+});++describe.skipIf(!HAS_ASSETS)('Spine runtime frame: residency sharing', () => {+ for (const [label, eras] of [['one era', 1], ['10 eras', 10], ['an era each', 500]] as const) {+ let runtime: SpineRuntime;+ bench(`500 entities, ${label}, x${FRAMES} frames`, () => { frames(runtime, true); }, {+ setup: () => { runtime = populated(500, eras); },+ teardown: () => { runtime.dispose(); },+ });+ }+});diff --git a/sdk/tests/spine-abi-cost.test.ts b/sdk/tests/spine-abi-cost.test.tsnew file mode 100644index 000000000..c7eaa9a9c--- /dev/null+++ b/sdk/tests/spine-abi-cost.test.ts@@ -0,0 +1,278 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spine-abi-cost.test.ts+ * @brief What one spine entity costs in crossings, per frame — the baseline.+ *+ * @details Now that lifetimes are trustworthy the numbers mean something: no+ * duplicate parses, no ghost instances, no leaked residency inflating+ * them. So the first thing to write down is not a time, it is the SHAPE+ * of the cost: how many times a frame crosses into the module, and what+ * that number is proportional to.+ *+ * These are judgments, not a report, because the shape is what a later+ * batch ABI would change on purpose — and a change nobody noticed is+ * how a per-entity crossing count grows a factor.+ *+ * Real module, real skeleton: a fake would answer whatever the harness+ * decided, including how many batches a pose has.+ */+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 type { SpineWasmModule } from '../src/spine/SpineModuleLoader';+import { SpineRuntime } from '../src/spine/SpineRuntime';+import type { SpineAssetValue, SpineEraBinding } from '../src/spine/prepareSpine';+import type { Entity } from '../src/types';++const SPINE38_JS = resolve(WASM_DIR, 'spine38.js');+const SPINE38_WASM = resolve(WASM_DIR, 'spine38.wasm');+const FIXTURES = resolve(__dirname, '../benchmarks/fixtures/spine/spineboy-38');+const SKEL = resolve(FIXTURES, 'spineboy-pro.skel');+const ATLAS = resolve(FIXTURES, 'spineboy.atlas');+const HAS_ASSETS = existsSync(SPINE38_WASM) && existsSync(SKEL) && existsSync(ATLAS);++/** Every export call, by name — the module's own `cwrap` is the one door. */+interface Crossings {+ counts: Map<string, number>;+ total(): number;+ reset(): void;+}++/** The module, with every ABI crossing counted. Nothing in the engine is+ * instrumented: what a runtime reaches for, it reaches for through here. */+function counting(module: SpineWasmModule): { module: SpineWasmModule; crossings: Crossings } {+ const counts = new Map<string, number>();+ const bump = (name: string): void => { counts.set(name, (counts.get(name) ?? 0) + 1); };+ const cwrap = module.cwrap.bind(module);+ const crossings: Crossings = {+ counts,+ total: () => [...counts.values()].reduce((a, b) => a + b, 0),+ reset: () => counts.clear(),+ };+ const wrapped = Object.create(module) as SpineWasmModule & {+ _malloc(size: number): number; _free(ptr: number): void;+ };+ wrapped.cwrap = ((name: string, ret: unknown, args: unknown) => {+ const fn = cwrap(name, ret as never, args as never);+ return (...called: unknown[]) => { bump(name); return (fn as (...a: unknown[]) => unknown)(...called); };+ }) as never;+ const malloc = module._malloc.bind(module);+ const free = module._free.bind(module);+ wrapped._malloc = (size: number) => { bump('_malloc'); return malloc(size); };+ wrapped._free = (ptr: number) => { bump('_free'); free(ptr); };+ return { module: wrapped, crossings };+}++let module38: SpineWasmModule;+let skelData: Uint8Array;+let atlasText: string;++beforeAll(async () => {+ if (!HAS_ASSETS) return;+ const factory = (await import(SPINE38_JS)).default as (opts: unknown) => Promise<SpineWasmModule>;+ const bytes = readFileSync(SPINE38_WASM);+ module38 = 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 {};+ },+ });+ skelData = new Uint8Array(readFileSync(SKEL));+ atlasText = readFileSync(ATLAS, 'utf-8');+});++/** One era, over the real spineboy documents. `id` is what a residency shares by. */+function era(id: string): SpineEraBinding {+ const value: SpineAssetValue = {+ skelData, atlasText, isBinary: true,+ // One page, faked: what an atlas page IS costs nothing per frame — the+ // module is told a texture id once, at parse.+ textures: new Map([['spineboy.png', { glId: 1, w: 1024, h: 1024 }]]),+ };+ return { id, value, retain: () => ({ release: () => {} }) };+}++/** N entities on `eras` distinct eras, posed for one frame so batches exist. */+function populate(runtime: SpineRuntime, entities: number, eras: number): Entity[] {+ const bound: Entity[] = [];+ for (let i = 0; i < entities; i++) {+ const entity = (i + 1) as Entity;+ runtime.loadEntity(entity, era(`hero#${i % eras}`));+ runtime.setAnimation(entity, 'walk', true);+ bound.push(entity);+ }+ return bound;+}++/**+ * An engine core that accepts geometry and counts it. What is measured is the+ * walk INTO the spine module, so the core's own heap is a scratch buffer and its+ * submit is a tally — a real core would cost the same on either side of this.+ */+function countingCore() {+ const seen = { batches: 0, vertices: 0 };+ const heap = new Uint8Array(1 << 22);+ let top = 0;+ return {+ seen,+ core: {+ renderer_submitSkeletalBatchByEntity: (+ _registry: unknown, _vp: number, vertexCount: number,+ ) => { seen.batches++; seen.vertices += vertexCount; },+ _malloc: (size: number) => { const at = top; top += size; return at; },+ _free: () => { top = 0; },+ HEAPU8: heap,+ },+ };+}++/** One frame of the pass a scene actually runs. */+function frame(+ runtime: SpineRuntime, core: ReturnType<typeof countingCore> | null,+): { batches: number; vertices: number } {+ runtime.updateAll(1 / 60);+ if (!core) return { batches: 0, vertices: 0 };+ core.seen.batches = 0;+ core.seen.vertices = 0;+ runtime.extractAndSubmitMeshes(core.core as never, {} as never);+ return { ...core.seen };+}++/** The table, printed on demand: `SPINE_ABI_REPORT=1 pnpm --filter ./sdk test+ * spine-abi-cost`. The judgments below are what holds the shape; this is for+ * reading the size of it. */+function report(rows: Array<Record<string, number | string>>): void {+ if (!process.env.SPINE_ABI_REPORT) return;+ const keys = Object.keys(rows[0]);+ const width = (k: string) => Math.max(k.length, ...rows.map((r) => String(r[k]).length));+ const line = (cells: Array<string | number>) =>+ 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[k])));+}++describe.skipIf(!HAS_ASSETS)('what a spine entity costs per frame', () => {+ it('the baseline, for reading', () => {+ const rows: Array<Record<string, number | string>> = [];+ for (const entities of [1, 10, 100, 500, 1000]) {+ for (const workload of ['pose', 'pose+submit'] as const) {+ const { module, crossings } = counting(module38);+ const runtime = new SpineRuntime('3.8', module);+ const core = countingCore();+ populate(runtime, entities, 1);+ const submit = workload === 'pose+submit' ? core : null;+ frame(runtime, submit);+ crossings.reset();+ const { batches, vertices } = frame(runtime, submit);+ rows.push({+ entities, workload,+ crossings: crossings.total(),+ 'per entity': +(crossings.total() / entities).toFixed(1),+ batches, vertices,+ 'scratch B': batches * 2 > 0 ? vertices * 8 * 4 + batches * 64 : 0,+ });+ runtime.dispose();+ }+ }+ report(rows);+ expect(rows).toHaveLength(10);+ });++ it('posing is one crossing per entity, whatever the entity count', () => {+ const { module, crossings } = counting(module38);+ const runtime = new SpineRuntime('3.8', module);+ populate(runtime, 10, 1);++ crossings.reset();+ frame(runtime, null);+ const ten = crossings.total();+ crossings.reset();+ populate(runtime, 100, 1);+ crossings.reset();+ frame(runtime, null);+ const hundred = crossings.total();++ expect(ten).toBe(10);+ expect(hundred, 'posing stopped being one call per entity').toBe(100);+ runtime.dispose();+ });++ it('reading a pose back is 2 + 3 per batch, per entity, per frame', () => {+ // The number a batch ABI would change: today the walk asks how many+ // batches, then three questions per batch, and allocates twice per batch+ // — all of it per entity.+ const { module, crossings } = counting(module38);+ const runtime = new SpineRuntime('3.8', module);+ const core = countingCore();+ populate(runtime, 1, 1);+ frame(runtime, core);++ crossings.reset();+ const { batches } = frame(runtime, core);+ const c = crossings.counts;++ expect(batches).toBeGreaterThan(0);+ expect(c.get('spine_update')).toBe(1);+ expect(c.get('spine_getMeshBatchCount')).toBe(1);+ expect(c.get('spine_getMeshBatchVertexCount')).toBe(batches);+ expect(c.get('spine_getMeshBatchIndexCount')).toBe(batches);+ expect(c.get('spine_getMeshBatchData')).toBe(batches);+ // Two allocations per batch (vertices + indices) plus the meta pair.+ expect(c.get('_malloc')).toBe(1 + batches * 2);+ // The formula, for the wall: 4 fixed + 7 per batch, per entity, per+ // frame. A batch ABI is a change to THIS.+ expect(crossings.total()).toBe(4 + 7 * batches);+ runtime.dispose();+ });++ it('the whole frame is linear in entities, and nothing amortizes', () => {+ // What the baseline is FOR: at 1000 entities this is the frame's shape.+ // Any per-frame saving has to come from crossing fewer times per entity,+ // because nothing here is shared between them.+ const { module, crossings } = counting(module38);+ const runtime = new SpineRuntime('3.8', module);+ const core = countingCore();++ populate(runtime, 1, 1);+ frame(runtime, core);+ crossings.reset();+ frame(runtime, core);+ const one = crossings.total();++ populate(runtime, 100, 1);+ frame(runtime, core);+ crossings.reset();+ frame(runtime, core);+ const hundred = crossings.total();++ expect(hundred).toBe(one * 100);+ runtime.dispose();+ });++ it('sharing an era saves parses and memory, not one crossing per frame', () => {+ // Worth knowing before optimising the wrong thing: residency sharing is+ // a load-time and footprint win. The frame costs the same either way.+ const { module, crossings } = counting(module38);+ const runtime = new SpineRuntime('3.8', module);+ const core = countingCore();++ populate(runtime, 50, 1);+ frame(runtime, core);+ crossings.reset();+ frame(runtime, core);+ const shared = crossings.total();+ runtime.dispose();++ const apart = counting(module38);+ const second = new SpineRuntime('3.8', apart.module);+ populate(second, 50, 50);+ frame(second, core);+ apart.crossings.reset();+ frame(second, core);++ expect(apart.crossings.total()).toBe(shared);+ second.dispose();+ });+});