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.

feat(spine): a report names the asset it is about, by the pair it is

esengine08b90c40ac28
diff --git a/desktop b/desktop
index 2cc52ab98..d6d344bf0 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 2cc52ab9888a127a3b27c69fe6a5e403717d6f09
+Subproject commit d6d344bf0cf0b2fbdd74715f4d5605d7dee156a0
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index a1bb0057a..d5f48e904 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": 1663,
+ "experimental": 1664,
"deprecated": 3
},
- "total": 1867,
+ "total": 1868,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 2e60e500f..c1f5ebac9 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 · 45 experimental · 0 deprecated
+Symbols: 0 public · 1 beta · 46 experimental · 0 deprecated
## ConstraintList — interface @experimental
```
@@ -54,6 +54,7 @@ entities: number
envelope: "unknown" | "certified" | "observed"
era: string
mayDefer: boolean
+pair: SpinePair
version: SpineVersion
```
@@ -250,6 +251,12 @@ static prototype: SpineModuleController
(config?: Record<string, unknown>) => Promise<SpineWasmModule>
```
+## SpinePair — interface @experimental
+```
+atlas: string
+skeleton: string
+```
+
## SpinePlugin — class @experimental
```
build: (app: App) => void
@@ -277,6 +284,7 @@ culling: SpineCullingEnvelope
entities: number
era: string
mayDefer: boolean
+pair: SpinePair
requiresContinuousWorldPose: boolean
```
diff --git a/sdk/src/spine/SpineRuntime.ts b/sdk/src/spine/SpineRuntime.ts
index d29c5568d..7c5e42d13 100644
--- a/sdk/src/spine/SpineRuntime.ts
+++ b/sdk/src/spine/SpineRuntime.ts
@@ -20,7 +20,7 @@ import type { EngineApi } from '../ecs/bridge/engineApi';
import { SpineModuleController } from './SpineController';
import type { RawSpineEvent, ConstraintList, TransformMixData, PathMixData } from './SpineController';
import { wrapSpineModule, type SpineWasmModule } from './SpineModuleLoader';
-import type { SpineEraBinding, SpineEraClaim } from './prepareSpine';
+import type { SpineEraBinding, SpineEraClaim, SpinePair } from './prepareSpine';
import { beginSpineFrame, newSpineFrameMetrics, SpineTimeWindow,
type SpineFrameMetrics } from './spineMetrics';
import type { SpineVersion } from '../sideModules/registry';
@@ -70,6 +70,8 @@ interface SkeletonResidency {
skelHandle: number;
refcount: number;
claim: SpineEraClaim;
+ /** Which asset this era is a generation of, for anything naming it to a person. */
+ pair: SpinePair;
/**
* The two proofs a deferred world pose needs, both settled once when the
@@ -177,7 +179,7 @@ export class SpineRuntime {
// a new generation makes a new residency that asks again — the capability
// belongs to the skeleton this handle is, not to the name it came under.
this.skeletons_.set(era.id, {
- skelHandle, refcount: 1, claim,
+ skelHandle, refcount: 1, claim, pair: era.pair,
// A binding that carries no envelope promised nothing.
culling: era.culling ?? { kind: 'unknown' },
requiresContinuousWorldPose: this.controller_.requiresContinuousWorldPose(skelHandle),
@@ -408,7 +410,7 @@ export class SpineRuntime {
const out: SpineResidencyFacts[] = [];
for (const [era, residency] of this.skeletons_) {
out.push({
- era, entities: residency.refcount, culling: residency.culling,
+ era, pair: residency.pair, entities: residency.refcount, culling: residency.culling,
requiresContinuousWorldPose: residency.requiresContinuousWorldPose,
mayDefer: residencyMayDefer(residency),
});
diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.ts
index 75be76dcb..5f68ee842 100644
--- a/sdk/src/spine/index.ts
+++ b/sdk/src/spine/index.ts
@@ -9,6 +9,7 @@ export { SpineModuleController } from './SpineController';
export type { ConstraintList, TransformMixData, PathMixData } from './SpineController';
export type { SpineModuleFactory } from './SpineModuleLoader';
export { wrapSpineModule } from './SpineModuleLoader';
+export type { SpinePair } from './prepareSpine';
export type {
SpineAABB, SpineCullingEnvelope, SpineScanCoverage, SpineBoundsSource,
} from './spineBounds';
diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.ts
index 5f56a73a7..26641d5b5 100644
--- a/sdk/src/spine/loadSpineScene.ts
+++ b/sdk/src/spine/loadSpineScene.ts
@@ -24,7 +24,8 @@ import { getAssetTypeEntry } from '../assetTypes';
import { log } from '../util/logger';
import { SpineManager, type SpineVersion } from './SpineManager';
import { prepareSpine, spineEraOf, spinePairKey,
- type SpineAssetValue, type SpineEraBinding, type SpineEraClaim, type SpineIO } from './prepareSpine';
+ type SpineAssetValue, type SpineEraBinding, type SpineEraClaim, type SpineIO,
+ type SpinePair } from './prepareSpine';
import { requireResourceManager } from '../wasm/resourceManager';
import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimeAssets';
import type { BasisTranscoder } from '../asset/compressed';
@@ -119,14 +120,14 @@ export async function loadSpineAssets(
// scene's, so the pages go back when the scene does.
const lease = await owner.assets.acquireSpine(pair.skeleton, pair.atlas);
owner.scope.add(lease);
- era = spineEraOf(key, lease as never, certificates.envelopeFor(key));
+ era = spineEraOf(pair, lease as never, certificates.envelopeFor(key));
} else {
const pages: number[] = [];
const value = await prepareSpine(
hostSpineIo(module, source, pair.atlas, transcoderProvider, pages),
pair.skeleton, pair.atlas,
);
- const host = hostEra(`${key}#${++preparations}`, value, pages);
+ const host = hostEra(`${key}#${++preparations}`, pair, value, pages);
era = host.era;
preparation = host.preparation;
}
@@ -158,7 +159,7 @@ let preparations = 0;
* after which the runtimes posing it are the only holders.
*/
function hostEra(
- id: string, value: SpineAssetValue, pages: number[],
+ id: string, pair: SpinePair, value: SpineAssetValue, pages: number[],
): { era: SpineEraBinding; preparation: SpineEraClaim } {
let claims = 1;
const drop = (): void => {
@@ -169,7 +170,7 @@ function hostEra(
};
return {
// A host preparation has no project metadata to read a promise from.
- era: { id, value, culling: { kind: 'unknown' },
+ era: { id, pair, value, culling: { kind: 'unknown' },
retain: () => { claims++; return { release: drop }; } },
preparation: { release: drop },
};
diff --git a/sdk/src/spine/prepareSpine.ts b/sdk/src/spine/prepareSpine.ts
index c58005f14..dde3c5854 100644
--- a/sdk/src/spine/prepareSpine.ts
+++ b/sdk/src/spine/prepareSpine.ts
@@ -61,6 +61,17 @@ export interface SpineIO {
isBinary(ref: string): boolean;
}
+/**
+ * A spine asset's identity: the skeleton document and the atlas it is drawn
+ * with. Carried rather than composed into a key and split back out — a ref can
+ * be `@uuid:...` and a path can be `C:/...`, so a string with a separator in it
+ * is not something the pair can be recovered from.
+ */
+export interface SpinePair {
+ skeleton: string;
+ atlas: string;
+}
+
/** A claim on an era, held by something derived from it. */
export interface SpineEraClaim {
release(): void;
@@ -76,6 +87,8 @@ export interface SpineEraClaim {
export interface SpineEraBinding {
/** Which era — what a runtime keys its native residency by. */
readonly id: string;
+ /** Which ASSET, for anything that has to name it back to a person. */
+ readonly pair: SpinePair;
readonly value: SpineAssetValue;
/**
* A claim on THIS generation. Never a fresh acquisition by name: after an
@@ -95,11 +108,12 @@ export interface SpineEraBinding {
/** The era binding for an acquired spine asset: identity is the pair plus the
* generation, and the claim is a retain of exactly that generation. */
export function spineEraOf(
- key: string, lease: AssetLease<SpineAssetValue>,
+ pair: SpinePair, lease: AssetLease<SpineAssetValue>,
culling: SpineCullingEnvelope = { kind: 'unknown' },
): SpineEraBinding {
return {
- id: `${key}#${lease.generation}`,
+ id: `${spinePairKey(pair.skeleton, pair.atlas)}#${lease.generation}`,
+ pair,
value: lease.value,
retain: () => lease.retain(),
culling,
diff --git a/sdk/src/spine/spineSceneDiagnostics.ts b/sdk/src/spine/spineSceneDiagnostics.ts
index 302de36c6..6842c072c 100644
--- a/sdk/src/spine/spineSceneDiagnostics.ts
+++ b/sdk/src/spine/spineSceneDiagnostics.ts
@@ -27,6 +27,7 @@
*/
import type { SpineVersion } from '../sideModules/registry';
import type { SpineCullingEnvelope } from './spineBounds';
+import type { SpinePair } from './prepareSpine';
import type { SpineAbiCounts, SpineByteCounts, SpineFrameMetrics,
SpineTimeWindow } from './spineMetrics';
@@ -38,6 +39,8 @@ import type { SpineAbiCounts, SpineByteCounts, SpineFrameMetrics,
*/
export interface SpineResidencyFacts {
era: string;
+ /** The asset this era is a generation of. */
+ pair: SpinePair;
/** Its refcount — entities posed by it, disabled ones included. */
entities: number;
culling: SpineCullingEnvelope;
@@ -68,6 +71,12 @@ export interface SpineAssetDiagnostic {
version: SpineVersion;
/** The era — one generation of one skeleton+atlas pair. */
era: string;
+ /**
+ * The asset, as the two refs it is made of. Carried rather than split back
+ * out of `era`: a ref can be `@uuid:...` and a path can be `C:/...`, so
+ * anything routing a person to this asset has to be handed the pair.
+ */
+ pair: SpinePair;
/** Entities posed by it, disabled ones included: it is the residency's refcount. */
entities: number;
mayDefer: boolean;
@@ -205,7 +214,8 @@ export function spineSceneDiagnostics(
for (const facts of runtime.residencies()) {
if (facts.mayDefer) deferrable += facts.entities;
assets.push({
- version: runtime.version, era: facts.era, entities: facts.entities,
+ version: runtime.version, era: facts.era, pair: facts.pair,
+ entities: facts.entities,
mayDefer: facts.mayDefer, envelope: facts.culling.kind,
blockedBy: blockersOf(facts),
});
diff --git a/sdk/tests/helpers/fakeSpineModule.ts b/sdk/tests/helpers/fakeSpineModule.ts
index f3c1e0e86..094fd3ec1 100644
--- a/sdk/tests/helpers/fakeSpineModule.ts
+++ b/sdk/tests/helpers/fakeSpineModule.ts
@@ -11,7 +11,7 @@
*/
import { vi } from 'vitest';
import type { SpineWasmModule } from '../../src/spine/SpineModuleLoader';
-import type { SpineEraBinding } from '../../src/spine/prepareSpine';
+import type { SpineEraBinding, SpinePair } from '../../src/spine/prepareSpine';
import type { SpineCullingEnvelope } from '../../src/spine/spineBounds';
export interface FakeSpineModule {
@@ -93,10 +93,12 @@ export function fakeSpineModule(): FakeSpineModule {
export function fakeSpineEra(
id: string, skelData: Uint8Array | string = new Uint8Array([1]),
culling: SpineCullingEnvelope = { kind: 'unknown' },
+ pair: SpinePair = { skeleton: `${id}.skel`, atlas: `${id}.atlas` },
): SpineEraBinding & { claims: { retained: number; released: number } } {
const claims = { retained: 0, released: 0 };
return {
id,
+ pair,
claims,
culling,
value: {
diff --git a/sdk/tests/spine-abi-cost.test.ts b/sdk/tests/spine-abi-cost.test.ts
index 7b5de93e4..2db306b12 100644
--- a/sdk/tests/spine-abi-cost.test.ts
+++ b/sdk/tests/spine-abi-cost.test.ts
@@ -91,7 +91,8 @@ function era(id: string): SpineEraBinding {
// 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: () => {} }) };
+ return { id, pair: { skeleton: `${id}.skel`, atlas: `${id}.atlas` },
+ value, retain: () => ({ release: () => {} }) };
}
/** N entities on `eras` distinct eras, posed for one frame so batches exist. */
diff --git a/sdk/tests/spine-clip-start.test.ts b/sdk/tests/spine-clip-start.test.ts
index 4efaab6df..88757d852 100644
--- a/sdk/tests/spine-clip-start.test.ts
+++ b/sdk/tests/spine-clip-start.test.ts
@@ -184,6 +184,7 @@ describe.skipIf(!HAS_WASM)('the staged open is the shipped open', () => {
const era: SpineEraBinding = {
id: 'clip-start#1',
value: { skelData, atlasText, isBinary: true, textures: new Map() },
+ pair: { skeleton: 'clip-start.skel', atlas: 'clip-start.atlas' },
retain: () => ({ release: () => {} }),
};
const runtime = new SpineRuntime('3.8', watched);
diff --git a/sdk/tests/spine-demand-driven-pose.test.ts b/sdk/tests/spine-demand-driven-pose.test.ts
index 0792badd7..2ac3f2bb6 100644
--- a/sdk/tests/spine-demand-driven-pose.test.ts
+++ b/sdk/tests/spine-demand-driven-pose.test.ts
@@ -59,6 +59,7 @@ function era(id: string, culling: SpineCullingEnvelope): SpineEraBinding {
return {
id, culling,
value: { skelData, atlasText, isBinary: true, textures: new Map() },
+ pair: { skeleton: `${id}.skel`, atlas: `${id}.atlas` },
retain: () => ({ release: () => {} }),
};
}
diff --git a/sdk/tests/spine-era-retention.test.ts b/sdk/tests/spine-era-retention.test.ts
index e54709f2b..d2c658655 100644
--- a/sdk/tests/spine-era-retention.test.ts
+++ b/sdk/tests/spine-era-retention.test.ts
@@ -21,7 +21,7 @@ import { AssetScope } from '../src/asset/AssetLease';
import type { Backend } from '../src/asset/Backend';
import type { Entity } from '../src/types';
import { SpineRuntime } from '../src/spine/SpineRuntime';
-import { spineEraOf, spinePairKey, type SpineAssetValue, type SpineEraBinding } from '../src/spine/prepareSpine';
+import { spineEraOf, type SpineAssetValue, type SpineEraBinding } from '../src/spine/prepareSpine';
import { fakeSpineModule } from './helpers/fakeSpineModule';
function createPoolFake() {
@@ -98,7 +98,7 @@ function realm(docs: Record<string, string>): Assets {
async function acquired(assets: Assets, scope: AssetScope): Promise<SpineEraBinding> {
const lease = await assets.acquireSpine(SKEL, ATLAS);
scope.add(lease);
- return spineEraOf(spinePairKey(SKEL, ATLAS), lease as never);
+ return spineEraOf({ skeleton: SKEL, atlas: ATLAS }, lease as never);
}
/** The binding, with its retains and releases counted (and ordered). */
@@ -108,6 +108,7 @@ function counted(era: SpineEraBinding) {
claims,
era: {
id: era.id,
+ pair: era.pair,
value: era.value,
retain: () => {
claims.retained++;
diff --git a/sdk/tests/spine-extract-stages.test.ts b/sdk/tests/spine-extract-stages.test.ts
index 712f71bea..316abcef6 100644
--- a/sdk/tests/spine-extract-stages.test.ts
+++ b/sdk/tests/spine-extract-stages.test.ts
@@ -154,6 +154,7 @@ describe.skipIf(!HAS_ASSETS)('the staged walk is the shipped walk', () => {
const era: SpineEraBinding = {
id: 'probe#1',
value: { skelData, atlasText, isBinary: true, textures: new Map() },
+ pair: { skeleton: 'probe.skel', atlas: 'probe.atlas' },
retain: () => ({ release: () => {} }),
};
const runtime = new SpineRuntime('3.8', watched);
diff --git a/sdk/tests/spine-observability.test.ts b/sdk/tests/spine-observability.test.ts
index 7c76e8b45..8dfe0f35b 100644
--- a/sdk/tests/spine-observability.test.ts
+++ b/sdk/tests/spine-observability.test.ts
@@ -55,6 +55,7 @@ function era(id: string): SpineEraBinding {
skelData, atlasText, isBinary: true,
textures: new Map([['spineboy.png', { glId: 1, w: 1024, h: 1024 }]]),
},
+ pair: { skeleton: `${id}.skel`, atlas: `${id}.atlas` },
retain: () => ({ release: () => {} }),
};
}
diff --git a/sdk/tests/spine-pose-demand.test.ts b/sdk/tests/spine-pose-demand.test.ts
index 7d6c37c84..83e3e9c29 100644
--- a/sdk/tests/spine-pose-demand.test.ts
+++ b/sdk/tests/spine-pose-demand.test.ts
@@ -108,6 +108,7 @@ function era(id: string): SpineEraBinding {
return {
id,
value: { skelData, atlasText, isBinary: true, textures: new Map() },
+ pair: { skeleton: `${id}.skel`, atlas: `${id}.atlas` },
retain: () => ({ release: () => {} }),
};
}
diff --git a/sdk/tests/spine-pose-materialization.test.ts b/sdk/tests/spine-pose-materialization.test.ts
index bf1bc7c90..1385137cd 100644
--- a/sdk/tests/spine-pose-materialization.test.ts
+++ b/sdk/tests/spine-pose-materialization.test.ts
@@ -51,6 +51,7 @@ function era(id: string): SpineEraBinding {
return {
id,
value: { skelData, atlasText, isBinary: true, textures: new Map() },
+ pair: { skeleton: `${id}.skel`, atlas: `${id}.atlas` },
retain: () => ({ release: () => {} }),
};
}
diff --git a/sdk/tests/spine-scene-diagnostics.test.ts b/sdk/tests/spine-scene-diagnostics.test.ts
index 90c9fa716..ed4e1a9fa 100644
--- a/sdk/tests/spine-scene-diagnostics.test.ts
+++ b/sdk/tests/spine-scene-diagnostics.test.ts
@@ -177,6 +177,19 @@ describe('why an asset is not lazy', () => {
dispose(runtimes);
});
+ it('carries the pair, so nothing downstream has to split an era id', () => {
+ // Refs that CONTAIN the separator, because that is the case a split gets
+ // wrong: `@uuid:a:@uuid:b` has three colons and one right answer.
+ const pair = { skeleton: '@uuid:aaaa', atlas: '@uuid:bbbb' };
+ const fake = fakeSpineModule();
+ const runtime = new SpineRuntime('3.8', fake.module);
+ runtime.loadEntity(1 as Entity, fakeSpineEra('era#1', new Uint8Array([1]), CERTIFIED, pair));
+
+ const asset = spineSceneDiagnostics([runtime], true).assets[0];
+ expect(asset.pair, 'the pair was rebuilt from a string instead of carried').toEqual(pair);
+ runtime.dispose();
+ });
+
it('puts the biggest asset first, so the first line is the one that matters', () => {
const runtimes = scene([
{ era: 'few#1', entities: 2 },
diff --git a/tools/check-spine-panel.mjs b/tools/check-spine-panel.mjs
new file mode 100644
index 000000000..d4215beb3
--- /dev/null
+++ b/tools/check-spine-panel.mjs
@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-spine-panel.mjs — the profiler's spine section renders a report
+ * and never becomes a second one.
+ *
+ * The whole value of the spine diagnostics is that ONE side computes them: the
+ * realm that ran the frame. An editor panel that starts a clock, keeps a
+ * counter, or holds a rolling window is a second authority about the same frame,
+ * and the first thing to go wrong with one is that it disagrees with the thing
+ * it is displaying — with no way for a reader to tell which half is lying.
+ *
+ * That is a boundary, not a preference, so it is frozen here rather than left to
+ * whoever edits the panel next. Each rule names the shape a regression takes.
+ *
+ * node tools/check-spine-panel.mjs
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VIEW = 'desktop/src/panels/spineDiagnosticsView.ts';
+const SECTION = 'desktop/src/panels/SpineDiagnosticsSection.tsx';
+const HOLDER = 'desktop/src/engine/spineDiagnosticsStore.ts';
+const REALM = 'desktop/src/playHost.ts';
+const FILES = [VIEW, SECTION, HOLDER, REALM];
+
+// The panel IS the subject, so an absent editor is refused rather than passed:
+// an empty scan finds nothing wrong with nothing. run-gates skips it by
+// `needs: 'editor'`; run directly, this says why.
+if (!existsSync(path.join(ROOT, 'desktop', 'package.json'))) {
+ console.error('check-spine-panel: the editor is not checked out, and its profiler');
+ console.error(' panel is the subject of this check.');
+ console.error(' git submodule update --init desktop (private; you need access)');
+ process.exit(2);
+}
+const missing = FILES.filter((f) => !existsSync(path.join(ROOT, f)));
+if (missing.length > 0) {
+ console.error(`check-spine-panel is stale: ${missing.join(', ')} does not exist.`);
+ process.exit(1);
+}
+
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+/** Comments out, so a rule reads code and not the prose describing it. */
+const strip = (text) => text
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/\/\/[^\n]*/g, '');
+
+/** What the realm's answer to `query { kind: 'spine' }` is made of. */
+function realmAnswer() {
+ const text = strip(read(REALM));
+ const at = text.indexOf('async function spineDiagnostics(');
+ if (at < 0) return null;
+ // To the next top-level declaration — enough of the body to judge.
+ const rest = text.slice(at);
+ const end = rest.indexOf('\nwindow.addEventListener');
+ return end < 0 ? rest : rest.slice(0, end);
+}
+
+const MEASURING = [
+ [/\b(performance|Date)\.now\s*\(/, 'reads a clock'],
+ [/\+\+|--(?![-])|\+=/, 'accumulates'],
+ [/\.push\s*\(/, 'keeps a history'],
+ [/\bpercentile\b|\bp95\b\s*[:=]/, 'computes a percentile'],
+];
+
+const RULES = [
+ {
+ rule: 'The spine section renders the realm\'s report. It may not measure: no clock, no counter, no history — the realm that ran the frame already answered all of it.',
+ holds: () => {
+ const bad = [];
+ for (const file of [VIEW, SECTION]) {
+ const text = strip(read(file));
+ for (const [pattern, what] of MEASURING) {
+ if (pattern.test(text)) bad.push(`${file} ${what}`);
+ }
+ }
+ return bad.length ? bad.join('; ') : null;
+ },
+ },
+ {
+ rule: 'The spine section reaches nothing that could answer a question — no realm, no engine host, no profiler. Its whole input is the DTO it is handed, which is what makes every number on screen come from ONE frame of ONE game.',
+ holds: () => {
+ const reached = [];
+ for (const file of [VIEW, SECTION]) {
+ for (const m of strip(read(file)).matchAll(/from\s+'([^']+)'/g)) {
+ const spec = m[1];
+ if (/^@\/engine\//.test(spec) || /PerfMonitor|EngineHost|PlayRealm/.test(spec)) {
+ reached.push(`${file} imports ${spec}`);
+ }
+ }
+ }
+ return reached.length ? reached.join('; ') : null;
+ },
+ },
+ {
+ rule: 'The realm answers with what the engine reported. It translates asset REFS into the editor\'s vocabulary and computes nothing else — a number the editor derives is a number the game never had.',
+ holds: () => {
+ const body = realmAnswer();
+ if (!body) return 'playHost has no spineDiagnostics() — the realm answers the spine query from somewhere else now';
+ if (!/\.diagnostics\(\)/.test(body)) return 'the realm\'s answer no longer comes from Spine.diagnostics()';
+ for (const [pattern, what] of MEASURING) {
+ if (pattern.test(body)) return `the realm's spine answer ${what}`;
+ }
+ return null;
+ },
+ },
+ {
+ rule: 'Findings route by the PAIR. A spine asset is a skeleton AND the atlas it is drawn with, and the same skeleton under two atlases is two assets — routing on a path would send both to whichever came first.',
+ holds: () => {
+ const view = strip(read(VIEW));
+ if (!/a\.era === f\.assets\[0\]/.test(view)) {
+ return 'routableAsset no longer matches the finding to an asset by era';
+ }
+ const section = strip(read(SECTION));
+ return /onOpenAsset\(asset\.pair\)/.test(section)
+ ? null : 'the section no longer opens the asset by its pair';
+ },
+ },
+ {
+ rule: 'Profiler finds, Inspector fixes. The section routes to an asset and does not author one: scanning and certifying live where the contract is written.',
+ holds: () => {
+ const section = strip(read(SECTION));
+ return /useAsFixedBounds|removeFixedBounds|observedSpineBounds/.test(section)
+ ? 'the section authors a culling contract' : null;
+ },
+ },
+];
+
+const findings = [];
+for (const { rule, holds } of RULES) {
+ const broken = holds();
+ if (broken) findings.push(`${broken}\n the boundary: ${rule}`);
+}
+
+if (findings.length === 0) {
+ console.log(`check-spine-panel: ${RULES.length} frozen boundaries — the panel renders the realm's report and computes none of it.`);
+ process.exit(0);
+}
+for (const f of findings) console.error(f);
+console.error('\nChanging one of these is allowed — with a counterexample. Edit this file and say why.');
+process.exit(1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 70780c077..8aa9893ad 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -121,6 +121,9 @@ export const GATES = [
// The five spine lifetime invariants, each with the judgment that proves it:
// what they replaced were teardown protocols, and a protocol comes back quietly.
{ id: 'spine-lifetimes', run: 'node tools/check-spine-lifetimes.mjs' },
+ // The profiler's spine section renders the realm's report and computes none
+ // of it: one side measures a frame, or two of them disagree about it.
+ { id: 'spine-panel', run: 'node tools/check-spine-panel.mjs', needs: 'editor' },
// …and that each of them can be reached on a device, where the registry is
// assembled from ptr accessors rather than from embind.
{ id: 'native-components', run: 'node tools/check-native-components.mjs' },