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): the culling contract reaches the runtime from the project

esengined5753d382b6e
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f7aec9635..75624fb40 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -819,6 +819,7 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
+projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -844,6 +845,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 025c329da..19a6d1689 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -819,6 +819,7 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
+projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -844,6 +845,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index c4fc23be7..c9947b8a5 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -814,6 +814,7 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
+projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -839,6 +840,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ace29816f..92aac3467 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -814,6 +814,7 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
+projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -839,6 +840,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 78cf150f8..b0ba129df 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -814,6 +814,7 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
+projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -839,6 +840,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index afae5aacb..97e452139 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -54,6 +54,7 @@ import { UUID_REF_PREFIX } from './AssetRegistry';
import type { AssetRefCounter } from './AssetRefCounter';
import { log } from '../util/logger';
import { recoverDevice, finishDeviceRecovery } from '../render/renderer';
+import { SpineCertificates, projectSpineCertificates } from '../spine/spineCertificates';
/**
* One asset generation ending: which ref, what kind of asset it was, and what
@@ -2012,6 +2013,34 @@ export class Assets {
setAssetRegistry(registry: AssetRegistry): void {
this.assetRegistry_ = registry;
this.assetRefResolver_ = (ref) => registry.resolveRef(ref);
+ this.projectSpineCertificates();
+ }
+
+ /**
+ * The spine culling promises this realm knows about — a PROJECTION of what
+ * the project persists, never a store of its own. Rebuilt on every ask, so
+ * a deleted contract disappears rather than outliving the metadata that
+ * granted it, and a manifest loaded later is not missed.
+ */
+ get spineCertificates(): SpineCertificates {
+ this.projectSpineCertificates();
+ return this.spineCertificates_;
+ }
+
+ /** Rebuild that projection from what the registry currently holds. */
+ projectSpineCertificates(): void {
+ const registry = this.assetRegistry_;
+ if (!registry) {
+ this.spineCertificates_.clear();
+ return;
+ }
+ projectSpineCertificates(
+ this.spineCertificates_,
+ registry.getAllByType('spine'),
+ (skeleton) => {
+ const deps = this.catalog.getDeps(skeleton);
+ return deps.length > 0 ? deps[0] : null;
+ });
}
getAssetRegistry(): AssetRegistry | null {
@@ -2027,6 +2056,8 @@ export class Assets {
* "does anything still need this asset?". Optional; null means no
* tracking (default, zero overhead).
*/
+ private readonly spineCertificates_ = new SpineCertificates();
+
setRefCounter(counter: AssetRefCounter): void {
this.refCounter_ = counter;
}
diff --git a/sdk/src/asset/spineImportSettings.ts b/sdk/src/asset/spineImportSettings.ts
new file mode 100644
index 000000000..845e80594
--- /dev/null
+++ b/sdk/src/asset/spineImportSettings.ts
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file asset/spineImportSettings.ts
+ * @brief The `.meta` importer block → a spine asset's culling contract.
+ *
+ * One parser, because there is one source: the importer block the asset
+ * inspector edits and the cook copies into the ship manifest. What it carries
+ * is a PROMISE — no pose of this skeleton leaves this rectangle — so what is
+ * stored is the rectangle and nothing about where it came from. Whether a scan
+ * proposed it is the editor's business; the runtime only needs to know whether
+ * somebody made the promise.
+ */
+
+/** The rectangle a spine asset promises to stay inside, in skeleton space. */
+export interface ParsedSpineImportSettings {
+ cullingBounds?: { x: number; y: number; width: number; height: number };
+}
+
+function readBounds(raw: unknown): ParsedSpineImportSettings['cullingBounds'] {
+ if (!raw || typeof raw !== 'object') return undefined;
+ const b = raw as Record<string, unknown>;
+ const n = (v: unknown): number | null =>
+ (typeof v === 'number' && Number.isFinite(v) ? v : null);
+ const x = n(b.x);
+ const y = n(b.y);
+ const width = n(b.width);
+ const height = n(b.height);
+ if (x === null || y === null || width === null || height === null) return undefined;
+ // A rectangle of no area promises that nothing is drawn, which is a promise
+ // nobody means to make; an incomplete block is not a contract either.
+ if (width <= 0 || height <= 0) return undefined;
+ return { x, y, width, height };
+}
+
+/** Parse an importer block; undefined when it carries no contract. */
+export function spineImportSettingsFrom(
+ importer: Record<string, unknown> | undefined | null,
+): ParsedSpineImportSettings | undefined {
+ if (!importer) return undefined;
+ const cullingBounds = readBounds(importer.cullingBounds);
+ return cullingBounds ? { cullingBounds } : undefined;
+}
diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.ts
index 94f0a3b03..3d9693054 100644
--- a/sdk/src/runtime/runtimeLoader.ts
+++ b/sdk/src/runtime/runtimeLoader.ts
@@ -344,7 +344,8 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
// instead of uploading its pages again.
const spineAssetInfo = app.sideModules
? await loadSpineAssets(module, source, spineManager, discovered.spines, transcoderProvider,
- { assets: sceneAssets, scope: assetResult.scope })
+ { assets: sceneAssets, scope: assetResult.scope },
+ sceneAssets.spineCertificates)
: new Map<string, SpineAssetInfo>();
// DragonBones, the same two phases. The manager is acquired only when the
diff --git a/sdk/src/spine/spineCertificates.ts b/sdk/src/spine/spineCertificates.ts
index 26751e1f8..5d2e135c1 100644
--- a/sdk/src/spine/spineCertificates.ts
+++ b/sdk/src/spine/spineCertificates.ts
@@ -19,6 +19,8 @@
*/
import type { SpineAABB, SpineCullingEnvelope } from './spineBounds';
import { certifyBounds } from './spineBounds';
+import { spineImportSettingsFrom } from '../asset/spineImportSettings';
+import { spinePairKey } from './prepareSpine';
/** What a runtime asks when it is about to make a residency. */
export interface SpineCertificateSource {
@@ -45,12 +47,40 @@ export class SpineCertificates implements SpineCertificateSource {
this.byPair_.delete(pairKey);
}
+ /** Forget every promise — what a rebuild from metadata starts with. */
+ clear(): void {
+ this.byPair_.clear();
+ }
+
envelopeFor(pairKey: string): SpineCullingEnvelope {
const bounds = this.byPair_.get(pairKey);
return bounds ? certifyBounds(bounds) : { kind: 'unknown' };
}
}
+/**
+ * Rebuild the projection from what the project persists — the ONLY way promises
+ * get in, and everything absent from `entries` loses its permission. `atlasOf`
+ * names the atlas a skeleton pairs with, because the promise is about the pair:
+ * the same skeleton against another atlas inherits nothing.
+ */
+export function projectSpineCertificates(
+ into: SpineCertificates,
+ entries: ReadonlyArray<{ path: string; importer?: Record<string, unknown> }>,
+ atlasOf: (skeletonPath: string) => string | null,
+): void {
+ into.clear();
+ for (const entry of entries) {
+ const settings = spineImportSettingsFrom(entry.importer);
+ if (!settings?.cullingBounds) continue;
+ const atlas = atlasOf(entry.path);
+ if (!atlas) continue;
+ const { x, y, width, height } = settings.cullingBounds;
+ into.certify(spinePairKey(entry.path, atlas),
+ { minX: x, minY: y, maxX: x + width, maxY: y + height });
+ }
+}
+
/** A realm with no recorded promises: everything materialises. */
export const NO_CERTIFICATES: SpineCertificateSource = {
envelopeFor: () => ({ kind: 'unknown' }),
diff --git a/sdk/tests/spine-certificate-pipeline.test.ts b/sdk/tests/spine-certificate-pipeline.test.ts
new file mode 100644
index 000000000..20b9dbc18
--- /dev/null
+++ b/sdk/tests/spine-certificate-pipeline.test.ts
@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spine-certificate-pipeline.test.ts
+ * @brief The promise reaching the runtime from the only place it may come
+ * from, and leaving when it is withdrawn.
+ *
+ * @details A deferred world pose is a permission somebody granted, so the grant
+ * has to live where the project keeps its decisions — the importer
+ * block an asset's `.meta` carries. What the runtime holds is a
+ * PROJECTION of that, rebuilt from it, never a store of its own: a
+ * contract deleted from the metadata that went on authorising a skip
+ * would be the worst kind of stale, because what it authorises is
+ * geometry not being drawn.
+ */
+import { describe, it, expect } from 'vitest';
+import { Assets } from '../src/asset/Assets';
+import { AssetRegistry } from '../src/asset/AssetRegistry';
+import { Catalog } from '../src/asset/Catalog';
+import type { Backend } from '../src/platform/backend';
+import type { ESEngineModule } from '../src/wasm';
+import { spineImportSettingsFrom } from '../src/asset/spineImportSettings';
+import { SpineCertificates, projectSpineCertificates } from '../src/spine/spineCertificates';
+import { spinePairKey } from '../src/spine/prepareSpine';
+import { SpineRuntime } from '../src/spine/SpineRuntime';
+import { fakeSpineModule, fakeSpineEra } from './helpers/fakeSpineModule';
+import type { Entity } from '../src/types';
+
+const RECT = { x: -120, y: -80, width: 240, height: 180 };
+const SKEL = 'hero/hero.skel';
+const ATLAS = 'hero/hero.atlas';
+
+function assetsWith(entries: Array<{ path: string; importer?: Record<string, unknown> }>): Assets {
+ const backend = {
+ resolveUrl: (p: string) => p,
+ fetchText: async () => '',
+ fetchBinary: async () => new ArrayBuffer(0),
+ } as unknown as Backend;
+ const assets = new Assets({
+ backend,
+ module: { _malloc: () => 0, _free: () => {} } as unknown as ESEngineModule,
+ // A skeleton's atlas is a catalog dependency, which is what a cook
+ // records for it — the same place `acquireSpine` looks.
+ catalog: Catalog.fromJson({
+ entries: { [SKEL]: { path: SKEL, deps: [ATLAS] } } as never,
+ } as never),
+ });
+ const registry = new AssetRegistry();
+ registry.loadManifest({
+ version: '1.0',
+ entries: entries.map((e, i) => ({
+ uuid: `0000000${i}-0000-4000-8000-000000000000`,
+ path: e.path, type: 'spine', importer: e.importer,
+ })),
+ });
+ assets.setAssetRegistry(registry);
+ return assets;
+}
+
+describe('a promise reaches the runtime from the project, and leaves with it', () => {
+ it('the block carries a rectangle and nothing about where it came from', () => {
+ expect(spineImportSettingsFrom({ cullingBounds: RECT })).toEqual({ cullingBounds: RECT });
+ expect(spineImportSettingsFrom({})).toBeUndefined();
+ expect(spineImportSettingsFrom(null)).toBeUndefined();
+ // Half a rectangle is not a contract, and neither is one of no area:
+ // "nothing is ever drawn" is not a promise anybody means to make.
+ expect(spineImportSettingsFrom({ cullingBounds: { x: 0, y: 0, width: 10 } })).toBeUndefined();
+ expect(spineImportSettingsFrom({ cullingBounds: { ...RECT, width: 0 } })).toBeUndefined();
+ });
+
+ it('metadata on the skeleton certifies the pair it forms', () => {
+ const assets = assetsWith([{ path: SKEL, importer: { cullingBounds: RECT } }]);
+ const envelope = assets.spineCertificates.envelopeFor(spinePairKey(SKEL, ATLAS));
+ expect(envelope.kind).toBe('certified');
+ if (envelope.kind !== 'certified') throw new Error('not certified');
+ expect(envelope.bounds).toEqual({ minX: -120, minY: -80, maxX: 120, maxY: 100 });
+ });
+
+ it('a project that promised nothing certifies nothing', () => {
+ const assets = assetsWith([{ path: SKEL }]);
+ expect(assets.spineCertificates.envelopeFor(spinePairKey(SKEL, ATLAS)).kind).toBe('unknown');
+ });
+
+ it('withdrawing the contract withdraws the permission', () => {
+ // The one that matters: what a stale certificate authorises is geometry
+ // not being drawn, so the projection is rebuilt rather than added to.
+ const certificates = new SpineCertificates();
+ const atlasOf = (): string => ATLAS;
+ projectSpineCertificates(certificates, [{ path: SKEL, importer: { cullingBounds: RECT } }], atlasOf);
+ expect(certificates.envelopeFor(spinePairKey(SKEL, ATLAS)).kind).toBe('certified');
+
+ projectSpineCertificates(certificates, [{ path: SKEL }], atlasOf);
+ expect(certificates.envelopeFor(spinePairKey(SKEL, ATLAS)).kind,
+ 'a deleted contract went on authorising a skip').toBe('unknown');
+ });
+
+ it('a manifest that arrives after the registry is not missed', () => {
+ // Attaching a registry and loading its manifest are two moments, and
+ // which order a host does them in is the host's business. A projection
+ // built once at the first would be empty for the whole run.
+ const backend = {
+ resolveUrl: (p: string) => p,
+ fetchText: async () => '',
+ fetchBinary: async () => new ArrayBuffer(0),
+ } as unknown as Backend;
+ const assets = new Assets({
+ backend,
+ module: { _malloc: () => 0, _free: () => {} } as unknown as ESEngineModule,
+ catalog: Catalog.fromJson({
+ entries: { [SKEL]: { path: SKEL, deps: [ATLAS] } } as never,
+ } as never),
+ });
+ const registry = new AssetRegistry();
+ assets.setAssetRegistry(registry);
+ expect(assets.spineCertificates.envelopeFor(spinePairKey(SKEL, ATLAS)).kind).toBe('unknown');
+
+ registry.loadManifest({
+ version: '1.0',
+ entries: [{
+ uuid: '00000000-0000-4000-8000-000000000000',
+ path: SKEL, type: 'spine', importer: { cullingBounds: RECT },
+ }],
+ });
+ expect(assets.spineCertificates.envelopeFor(spinePairKey(SKEL, ATLAS)).kind,
+ 'the projection was built once and never looked again').toBe('certified');
+ });
+
+ it('the promise is about the pair, so another atlas inherits nothing', () => {
+ const certificates = new SpineCertificates();
+ projectSpineCertificates(certificates,
+ [{ path: SKEL, importer: { cullingBounds: RECT } }], () => ATLAS);
+
+ expect(certificates.envelopeFor(spinePairKey(SKEL, ATLAS)).kind).toBe('certified');
+ expect(certificates.envelopeFor(spinePairKey(SKEL, 'winter/winter.atlas')).kind,
+ 'a promise about one atlas was read for another').toBe('unknown');
+ });
+
+ it('the promise does not care which generation of the bytes is loaded', () => {
+ const assets = assetsWith([{ path: SKEL, importer: { cullingBounds: RECT } }]);
+ const key = spinePairKey(SKEL, ATLAS);
+ for (const generation of [17, 18, 19]) {
+ expect(assets.spineCertificates.envelopeFor(key).kind,
+ `generation ${generation} lost the promise`).toBe('certified');
+ }
+ });
+
+ it('the contract is what turns the effect on, and off again', () => {
+ // End to end, through the runtime that acts on it: a certified stateless
+ // skeleton nobody can see costs an advance, and the same asset without
+ // the contract costs everything it did before.
+ const offscreen = (() => {
+ const heap = new Uint32Array(64);
+ return {
+ renderer_submitSkeletalBatchByEntity: () => {},
+ renderer_entityVisibleToCamera: (
+ _r: unknown, _e: number, _l: number,
+ _a: number, _b: number, _c: number, _d: number, out: number,
+ ) => { heap[out >> 2] = 0; },
+ _malloc: () => 4, _free: () => {},
+ HEAPU8: new Uint8Array(heap.buffer), HEAPU32: heap,
+ } as never;
+ })();
+
+ const run = (importer: Record<string, unknown> | undefined): {
+ world: number; extract: number;
+ } => {
+ const assets = assetsWith([{ path: SKEL, importer }]);
+ const envelope = assets.spineCertificates.envelopeFor(spinePairKey(SKEL, ATLAS));
+ const fake = fakeSpineModule();
+ const runtime = new SpineRuntime('3.8', fake.module);
+ runtime.loadEntity(1 as Entity, fakeSpineEra('era#1', new Uint8Array([1]), envelope));
+ runtime.setAnimation(1 as Entity, 'walk', true);
+ runtime.observe(true);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(offscreen, {} as never);
+ const m = runtime.metrics()!;
+ const counts = {
+ world: m.pose.worldMaterializations, extract: m.pose.meshExtractions,
+ };
+ runtime.dispose();
+ return counts;
+ };
+
+ expect(run({ cullingBounds: RECT }), 'the contract did not reach the effect')
+ .toEqual({ world: 0, extract: 0 });
+ expect(run(undefined), 'an asset without a contract stopped behaving as it did')
+ .toEqual({ world: 1, extract: 1 });
+ });
+});