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.

perf(spine): batch slots that outlive the frame — and what that did not buy

esengineeb8e87c413d4
diff --git a/sdk/benchmarks/spine-extract-stages.bench.ts b/sdk/benchmarks/spine-extract-stages.bench.ts
index b6a401256..1a59ced12 100644
--- a/sdk/benchmarks/spine-extract-stages.bench.ts
+++ b/sdk/benchmarks/spine-extract-stages.bench.ts
@@ -14,6 +14,12 @@
* (SpineRuntimeC.cpp, `renderImpl<STAGE, COUNT>`); the one a frame runs
* has no stage check and no counter in it. Every depth costs exactly
* one crossing per instance, so the boundary cancels in the differences.
+ *
+ * S4c minus S4 is the storage, and it is not what it looks like. Making
+ * the batch slots outlive the frame — proven to reallocate nothing in a
+ * steady scene, tests/spine-batch-storage — did not move this number at
+ * all. What is left in the gap is the writing itself: eight pushes per
+ * vertex, three thousand per skeleton, a million per frame.
*/
import { describe, bench, beforeAll } from 'vitest';
import { existsSync, readFileSync } from 'node:fs';
diff --git a/sdk/src/spine/SpineModuleLoader.ts b/sdk/src/spine/SpineModuleLoader.ts
index 38870f4b7..f5aae2195 100644
--- a/sdk/src/spine/SpineModuleLoader.ts
+++ b/sdk/src/spine/SpineModuleLoader.ts
@@ -60,6 +60,7 @@ export interface SpineWasmModule {
_spine_setPathConstraintMix(instanceId: number, name: number, position: number, spacing: number, rotate: number, x: number, y: number): number;
_spine_probe_extract(instanceId: number, stage: number, useCollector: number): number;
_spine_probe_counts(out: number): void;
+ _spine_probe_storage(out: number): void;
cwrap(ident: string, returnType: string | null, argTypes: string[]): (...args: unknown[]) => unknown;
UTF8ToString(ptr: number): string;
@@ -126,6 +127,7 @@ export interface SpineWrappedAPI {
*/
probeExtract(instanceId: number, stage: number, useCollector: number): number;
probeCounts(out: number): void;
+ probeStorage(out: number): void;
}
export function wrapSpineModule(raw: SpineWasmModule): SpineWrappedAPI {
@@ -177,6 +179,7 @@ export function wrapSpineModule(raw: SpineWasmModule): SpineWrappedAPI {
probeExtract: cw('spine_probe_extract', 'number', ['number', 'number', 'number']) as SpineWrappedAPI['probeExtract'],
probeCounts: cw('spine_probe_counts', null, ['number']) as SpineWrappedAPI['probeCounts'],
+ probeStorage: cw('spine_probe_storage', null, ['number']) as SpineWrappedAPI['probeStorage'],
};
}
diff --git a/sdk/tests/spine-batch-storage.test.ts b/sdk/tests/spine-batch-storage.test.ts
new file mode 100644
index 000000000..c72043a74
--- /dev/null
+++ b/sdk/tests/spine-batch-storage.test.ts
@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spine-batch-storage.test.ts
+ * @brief The batch slots outlive the frame that fills them — and hand back
+ * exactly what the frame-scoped ones did.
+ *
+ * @details A frame poses the skeletons the last frame posed, so it writes the
+ * same vectors to the same sizes. Destroying them in between made every
+ * frame grow back into the capacity it had just freed. Keeping them is
+ * only safe if two things stay true, and neither is visible in a wall
+ * clock: a slot the last frame filled must not be readable as this
+ * one's, and a slot reopened must carry nothing of what it held.
+ *
+ * So the geometry is held to a digest taken from a build that did not
+ * have them — a parity claim is worth what its witness is independent
+ * of — and the storage itself is read through `spine_probe_storage`,
+ * because "it stopped reallocating" is a statement about capacity and
+ * not about time.
+ */
+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 { 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');
+
+/**
+ * `hash` is FNV-1a over every batch's vertex bytes, index bytes and state, in
+ * order — recorded from the build before this change, at the pose below.
+ */
+const ASSETS = [
+ {
+ name: 'spineboy', skel: 'spineboy-38/spineboy-pro.skel', atlas: 'spineboy-38/spineboy.atlas',
+ hash: 'eb4af120', batches: [{ vertices: 274, indices: 1017, texture: 1, blend: 0 }],
+ },
+ {
+ name: 'raptor', skel: 'raptor-38/raptor-pro.skel', atlas: 'raptor-38/raptor.atlas',
+ hash: 'b0eae4ed', batches: [{ vertices: 592, indices: 2091, texture: 1, blend: 0 }],
+ },
+ {
+ name: 'coin', skel: 'coin-38/coin-pro.skel', atlas: 'coin-38/coin.atlas',
+ hash: '86e9d8d9',
+ batches: [
+ { vertices: 12, indices: 18, texture: 1, blend: 0 },
+ { vertices: 4, indices: 6, texture: 1, blend: 1 },
+ ],
+ },
+] as const;
+
+const HAS_ASSETS = existsSync(SPINE38_WASM)
+ && ASSETS.every((a) => existsSync(resolve(FIXTURES, a.skel)));
+
+/** The four u32 counters `spine_probe_storage` writes, in order. */
+const STORAGE = ['slots', 'active', 'vertexFloats', 'indices'] as const;
+type Storage = Record<(typeof STORAGE)[number], number>;
+
+/** Every slot of coin's but the additive one, so that batch lands in slot 0. */
+const COIN_NORMAL_SLOTS = ['clipping', 'coin-side', 'coin-front-texture', 'coin-side-round', 'shine'];
+const COIN_ADDITIVE_SLOT = 'coin-front-shine';
+
+let raw: SpineWasmModule;
+let api: SpineWrappedAPI;
+/** The pool as it was before anything had ever extracted through it. */
+let atRest: Storage;
+
+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);
+ atRest = storage();
+});
+
+function storage(): Storage {
+ return withScratch(raw, (alloc) => {
+ const ptr = alloc(STORAGE.length * 4);
+ api.probeStorage(ptr);
+ const out = {} as Storage;
+ STORAGE.forEach((name, i) => { out[name] = raw.HEAPU32[(ptr >> 2) + i]; });
+ return out;
+ });
+}
+
+/** A skeleton whose atlas page is bound to `texture`, and one instance of it. */
+function posed(asset: { skel: string; atlas: string }, texture = 1): number {
+ const skelData = new Uint8Array(readFileSync(resolve(FIXTURES, asset.skel)));
+ const atlasText = readFileSync(resolve(FIXTURES, asset.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);
+ });
+ for (let i = 0, pages = api.getAtlasPageCount(skelHandle); i < pages; i++) {
+ api.setAtlasPageTexture(skelHandle, i, texture, 1024, 1024);
+ }
+ const instanceId = api.createInstance(skelHandle);
+ const first = api.getAnimations(instanceId).split(',')[0];
+ if (first) api.playAnimation(instanceId, first, 1, 0);
+ api.update(instanceId, 0.35);
+ return instanceId;
+}
+
+interface Batch { vertices: number; indices: number; texture: number; blend: number }
+
+/** Every batch of one extraction: its state, its extent, and its bytes. */
+function read(instanceId: number): { batches: Batch[]; hash: string } {
+ const count = api.getMeshBatchCount(instanceId);
+ const batches: Batch[] = [];
+ let hash = 0x811c9dc5;
+ for (let b = 0; b < count; b++) {
+ const vertices = api.getMeshBatchVertexCount(instanceId, b);
+ const indices = api.getMeshBatchIndexCount(instanceId, b);
+ withScratch(raw, (alloc) => {
+ const vp = alloc(vertices * 8 * 4 + 4);
+ const ip = alloc(indices * 2 + 2);
+ const tp = alloc(4);
+ const bp = alloc(4);
+ api.getMeshBatchData(instanceId, b, vp, ip, tp, bp);
+ const texture = raw.HEAPU32[tp >> 2];
+ const blend = raw.HEAPU32[bp >> 2] | 0;
+ hash = fnv1a(hash, new Uint8Array(raw.HEAPU8.buffer, vp, vertices * 8 * 4));
+ hash = fnv1a(hash, new Uint8Array(raw.HEAPU8.buffer, ip, indices * 2));
+ hash = fnv1a(hash, new Uint8Array(new Uint32Array([vertices, indices, texture, blend]).buffer));
+ batches.push({ vertices, indices, texture, blend });
+ });
+ }
+ return { batches, hash: (hash >>> 0).toString(16).padStart(8, '0') };
+}
+
+function fnv1a(seed: number, bytes: Uint8Array): number {
+ let hash = seed;
+ for (let i = 0; i < bytes.length; i++) {
+ hash = Math.imul(hash ^ bytes[i], 0x01000193) >>> 0;
+ }
+ return hash >>> 0;
+}
+
+describe.skipIf(!HAS_ASSETS)('spine batch storage outlives the frame', () => {
+ it('a steady pose reallocates nothing after the first frame', () => {
+ expect(atRest, 'the pool held storage before anything extracted through it')
+ .toEqual({ slots: 0, active: 0, vertexFloats: 0, indices: 0 });
+
+ // Warmed by the BIGGER skeleton on purpose: a pool sized to the frame it
+ // is about to run reads the same whether it kept its storage or freed it
+ // and grew back. Warmed above, rebuilding shows up as capacity dropping.
+ const big = posed(ASSETS[1]);
+ const steady = posed(ASSETS[0]);
+ api.getMeshBatchCount(big);
+ const warm = storage();
+ expect(warm.vertexFloats, 'the warm-up frame did not size the pool')
+ .toBeGreaterThanOrEqual(592 * 8);
+
+ for (let frame = 1; frame <= 6; frame++) {
+ api.getMeshBatchCount(steady);
+ expect(storage(), `frame ${frame} rebuilt storage the pool already held`)
+ .toEqual(warm);
+ }
+ });
+
+ it('persistent slots hand back the geometry the frame-scoped ones did', () => {
+ for (const asset of ASSETS) {
+ const instanceId = posed(asset);
+ const got = read(instanceId);
+ expect(got.batches, `${asset.name}: the batches a frame reads changed`)
+ .toEqual(asset.batches.map((b) => ({ ...b })));
+ expect(got.hash, `${asset.name}: same batches, different bytes`).toBe(asset.hash);
+ }
+ });
+
+ it('a frame with fewer batches does not show the ones it did not fill', () => {
+ const coin = posed(ASSETS[2]);
+ const spineboy = posed(ASSETS[0]);
+
+ expect(api.getMeshBatchCount(coin)).toBe(2);
+ expect(api.getMeshBatchCount(spineboy)).toBe(1);
+ expect(storage().active, 'the slot coin filled is still counted as this frame\'s').toBe(1);
+ // The slot coin's second batch left behind is still allocated; a reader
+ // that went by the pool rather than by the frame would find it here.
+ expect(api.getMeshBatchVertexCount(spineboy, 1)).toBe(0);
+ expect(api.getMeshBatchIndexCount(spineboy, 1)).toBe(0);
+ });
+
+ it('a reopened slot keeps nothing of the batch it last held', () => {
+ const coin = posed(ASSETS[2], 1);
+ const before = read(coin);
+ expect(before.hash).toBe(ASSETS[2].hash);
+
+ // One additive batch, bound to another texture: slot 0 now holds every
+ // field coin's own first batch must overwrite — state, extent and bytes.
+ const shineOnly = posed(ASSETS[2], 9);
+ for (const slot of COIN_NORMAL_SLOTS) api.setAttachment(shineOnly, slot, '');
+ const shine = read(shineOnly);
+ expect(shine.batches, 'the fixture no longer produces one additive batch in slot 0')
+ .toEqual([{ vertices: 4, indices: 6, texture: 9, blend: 1 }]);
+
+ expect(read(coin), 'coin read back what the slot held before it').toEqual(before);
+ expect(api.setAttachment(shineOnly, COIN_ADDITIVE_SLOT, '')).toBe(1);
+ });
+
+ it('capacity is scoped to the module, not to the frame', () => {
+ const raptor = posed(ASSETS[1]);
+ const spineboy = posed(ASSETS[0]);
+
+ api.getMeshBatchCount(raptor);
+ const high = storage();
+ expect(high.vertexFloats).toBeGreaterThanOrEqual(592 * 8);
+
+ // The smaller frame keeps the larger one's storage rather than trimming
+ // it: giving it back is the per-frame free this change removed.
+ api.getMeshBatchCount(spineboy);
+ expect(storage().vertexFloats).toBe(high.vertexFloats);
+ expect(storage().indices).toBe(high.indices);
+ });
+});
diff --git a/src/esengine/bindings/modules/dragonbones/DragonBonesModuleEntry.cpp b/src/esengine/bindings/modules/dragonbones/DragonBonesModuleEntry.cpp
index 5491c35cb..aa8c34125 100644
--- a/src/esengine/bindings/modules/dragonbones/DragonBonesModuleEntry.cpp
+++ b/src/esengine/bindings/modules/dragonbones/DragonBonesModuleEntry.cpp
@@ -73,7 +73,7 @@ struct Context {
es::skeletal::HandleTable<LoadedSkeleton> skeletons;
es::skeletal::HandleTable<LiveInstance> instances;
- std::vector<es::skeletal::MeshBatch> batches;
+ es::skeletal::BatchList batches;
es::skeletal::StringBuffer strings;
es::skeletal::EventBuffer events;
@@ -97,7 +97,7 @@ std::string skeletonName(int handle) { return "es_db_" + std::to_string(handle);
* advanceTime — so painter order is the walk order and needs no sort here.
*/
void extractBatches(int instanceId) {
- g_ctx.batches.clear();
+ g_ctx.batches.reset();
auto* live = g_ctx.instances.find(instanceId);
if (!live || !live->armature) return;
diff --git a/src/esengine/bindings/modules/spine/SkeletalModule.hpp b/src/esengine/bindings/modules/spine/SkeletalModule.hpp
index a17d49abf..29ffc95c7 100644
--- a/src/esengine/bindings/modules/spine/SkeletalModule.hpp
+++ b/src/esengine/bindings/modules/spine/SkeletalModule.hpp
@@ -58,16 +58,76 @@ struct TriangleSink {
std::uint32_t texture, int blendMode, const float rgba[4]) = 0;
};
+/**
+ * The batches of one extraction, in slots that outlive it: a slot is reopened
+ * rather than destroyed, so a frame writes into the capacity the last one grew.
+ * That capacity is the high-water mark of the largest extraction ever run here,
+ * held until the module goes — trimming it on a small frame is a per-frame free.
+ */
+class BatchList {
+public:
+ /// What the list can take before it allocates again.
+ struct Capacity {
+ std::size_t slots = 0;
+ std::size_t vertexFloats = 0;
+ std::size_t indices = 0;
+ };
+
+ /// Reopens the list for another extraction. A slot is emptied when it is
+ /// opened, not here, so a slot past the new extent cannot be read as this
+ /// extraction's either — nothing reaches one but `open`.
+ void reset() { active_ = 0; }
+
+ /// Starts a batch in this state, in the next slot's storage. The reference
+ /// is good until the next `open`, which may move every slot.
+ MeshBatch& open(std::uint32_t texture, int blendMode) {
+ if (active_ == slots_.size()) slots_.emplace_back();
+ MeshBatch& fresh = slots_[active_++];
+ fresh.vertices.clear();
+ fresh.indices.clear();
+ fresh.texture = texture;
+ fresh.blendMode = blendMode;
+ return fresh;
+ }
+
+ /// The batch still open — meaningful only while `size()` is nonzero.
+ MeshBatch& back() { return slots_[active_ - 1]; }
+
+ std::size_t size() const { return active_; }
+ const MeshBatch& operator[](std::size_t index) const { return slots_[index]; }
+ const MeshBatch* begin() const { return slots_.data(); }
+ const MeshBatch* end() const { return slots_.data() + active_; }
+
+ /// The whole pool, not what this extraction used: an idle slot keeps its
+ /// storage, which is the point.
+ Capacity capacity() const {
+ Capacity total;
+ total.slots = slots_.size();
+ for (const MeshBatch& slot : slots_) {
+ total.vertexFloats += slot.vertices.capacity();
+ total.indices += slot.indices.capacity();
+ }
+ return total;
+ }
+
+private:
+ std::vector<MeshBatch> slots_;
+ std::size_t active_ = 0;
+};
+
/**
* Batches what a runtime emits: a texture or blend change starts a new batch, so
* does filling one, and incoming indices are rebased onto what is already written.
*
* Bound to its list rather than reaching for a global, so a module can pose into
- * a scratch list without disturbing the one its getters are serving.
+ * a scratch list without disturbing the one its getters are serving. A slot is
+ * reused for its storage only: batching stays sequential, so a state that comes
+ * back after another one starts a new batch rather than rejoining its own, which
+ * is what keeps the draw order.
*/
class BatchCollector final : public TriangleSink {
public:
- explicit BatchCollector(std::vector<MeshBatch>& into) : batches_(into) {}
+ explicit BatchCollector(BatchList& into) : batches_(into) {}
void emit(const float* positions, const float* uvs, int vertexCount,
const std::uint16_t* indices, int indexCount,
@@ -93,27 +153,19 @@ public:
}
private:
- // Indexed rather than pointed at: the list reallocates as it grows, and an
- // index survives that.
MeshBatch& batchFor(std::uint32_t texture, int blendMode, int incomingVertices) {
- if (current_ < batches_.size()) {
- MeshBatch& open = batches_[current_];
+ if (batches_.size() > 0) {
+ MeshBatch& open = batches_.back();
const bool sameState = texture == open.texture && blendMode == open.blendMode;
const bool fits =
open.vertices.size() / VERTEX_FLOATS + static_cast<std::size_t>(incomingVertices)
<= MAX_BATCH_VERTICES;
if (sameState && fits) return open;
}
- current_ = batches_.size();
- batches_.emplace_back();
- MeshBatch& fresh = batches_.back();
- fresh.texture = texture;
- fresh.blendMode = blendMode;
- return fresh;
+ return batches_.open(texture, blendMode);
}
- std::vector<MeshBatch>& batches_;
- std::size_t current_ = static_cast<std::size_t>(-1);
+ BatchList& batches_;
};
/**
diff --git a/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp b/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp
index c6fb905ed..f3f79a016 100644
--- a/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp
+++ b/src/esengine/bindings/modules/spine/SpineModuleEntry.cpp
@@ -60,7 +60,7 @@ struct Context {
es::skeletal::HandleTable<SkeletonPtr> skeletons;
es::skeletal::HandleTable<LiveInstance> instances;
- std::vector<es::skeletal::MeshBatch> batches;
+ es::skeletal::BatchList batches;
es::skeletal::StringBuffer strings;
es::skeletal::EventBuffer events;
@@ -102,7 +102,7 @@ struct CountingSink final : es::skeletal::TriangleSink {
es::spine::ProbeCounts g_probeCounts{};
void extractBatches(int instanceId) {
- g_ctx.batches.clear();
+ g_ctx.batches.reset();
auto* instance = g_ctx.instanceOf(instanceId);
if (!instance) return;
@@ -276,7 +276,7 @@ int spine_probe_extract(int instanceId, int stage, int useCollector) {
auto* instance = g_ctx.instanceOf(instanceId);
if (!instance) return 0;
if (useCollector) {
- g_ctx.batches.clear();
+ g_ctx.batches.reset();
es::skeletal::BatchCollector collector(g_ctx.batches);
return es::spine::renderStage(instance, collector, g_ctx.clippingEnabled,
stage, &g_probeCounts) ? 1 : 0;
@@ -301,6 +301,22 @@ void spine_probe_counts(std::uint32_t* out) {
out[8] = g_probeCounts.emits;
}
+/**
+ * BENCHMARK ONLY — what the batch pool holds, into four u32 slots: slots ever
+ * opened, slots this extraction used, and the vertex floats and indices it can
+ * take without allocating again. Capacity that stops growing is what says a
+ * steady scene stopped reallocating; a wall clock can only suggest it.
+ */
+EMSCRIPTEN_KEEPALIVE
+void spine_probe_storage(std::uint32_t* out) {
+ if (!out) return;
+ const es::skeletal::BatchList::Capacity held = g_ctx.batches.capacity();
+ out[0] = static_cast<std::uint32_t>(held.slots);
+ out[1] = static_cast<std::uint32_t>(g_ctx.batches.size());
+ out[2] = static_cast<std::uint32_t>(held.vertexFloats);
+ out[3] = static_cast<std::uint32_t>(held.indices);
+}
+
EMSCRIPTEN_KEEPALIVE
int spine_getMeshBatchCount(int instanceId) {
extractBatches(instanceId);
diff --git a/tools/check-spine-lifetimes.mjs b/tools/check-spine-lifetimes.mjs
index 575ac483c..472c6535e 100644
--- a/tools/check-spine-lifetimes.mjs
+++ b/tools/check-spine-lifetimes.mjs
@@ -2,7 +2,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file check-spine-lifetimes.mjs — the five spine lifetime invariants, frozen.
+ * @file check-spine-lifetimes.mjs — the spine lifetime invariants, frozen.
*
* Spine spent four cuts becoming one lifetime model instead of two: an era owns
* what its preparation acquired, a native skeleton retains the era it was parsed
@@ -27,10 +27,16 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
const RUNTIME = 'sdk/src/spine/SpineRuntime.ts';
const MANAGER = 'sdk/src/spine/SpineManager.ts';
+const BATCHES = 'src/esengine/bindings/modules/spine/SkeletalModule.hpp';
+const SKELETAL_ENTRIES = [
+ 'src/esengine/bindings/modules/spine/SpineModuleEntry.cpp',
+ 'src/esengine/bindings/modules/dragonbones/DragonBonesModuleEntry.cpp',
+];
const SRC = 'sdk/src';
const TESTS = 'sdk/tests';
-const missing = [RUNTIME, MANAGER].filter((f) => !existsSync(path.join(ROOT, f)));
+const missing = [RUNTIME, MANAGER, BATCHES, ...SKELETAL_ENTRIES]
+ .filter((f) => !existsSync(path.join(ROOT, f)));
if (missing.length) {
console.error(`check-spine-lifetimes is stale: ${missing.join(', ')} does not exist.`);
process.exit(1);
@@ -75,8 +81,8 @@ const runtime = strip(read(RUNTIME));
const manager = strip(read(MANAGER));
/**
- * The five. `proof` is the judgment that fails when the invariant does; `holds`
- * is the structural half, where a regression has a shape a reader can grep for.
+ * `proof` is the judgment that fails when the invariant does; `holds` is the
+ * structural half, where a regression has a shape a reader can grep for.
*/
const INVARIANTS = [
{
@@ -116,6 +122,21 @@ const INVARIANTS = [
: `${RUNTIME}.loadEntity retires the old binding before the new one exists`;
},
},
+ {
+ rule: 'A frame\'s batch storage outlives the frame: slots are reopened, never destroyed, so what one frame grew into is what the next one writes into.',
+ proof: 'a steady pose reallocates nothing after the first frame',
+ holds: () => {
+ const list = strip(read(BATCHES));
+ const reset = list.slice(list.indexOf('void reset()'), list.indexOf('MeshBatch& open('));
+ if (/slots_\.(clear|resize|shrink_to_fit)/.test(reset)) {
+ return `${BATCHES}: reset() gives the slots back; capacity is scoped to the module, not the frame`;
+ }
+ const destroyed = SKELETAL_ENTRIES.filter((f) => /batches\.clear\s*\(/.test(strip(read(f))));
+ return destroyed.length === 0
+ ? null
+ : `${destroyed.join(', ')} destroys its batch list per frame rather than reopening it`;
+ },
+ },
{
rule: 'SpineManager is the sole authority for which runtime poses an entity: a runtime can only see its own entities, so nothing else may hold one.',
proof: 'moving to another spine version leaves nothing behind in the old one',