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
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.mdindex f7aec9635..75624fb40 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -819,6 +819,7 @@ onInvalidate: (listener: InvalidateListener) => () => voidpathForHandle: (kind: string, handle: number) => string | nullpreload: (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: () => voidrecoverFromDeviceLoss: () => Promise<boolean>register: <T>(loader: AssetLoader<T>) => voidreleaseAll: () => void@@ -844,6 +845,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => voidsetRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+spineCertificates: SpineCertificatestexturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 025c329da..19a6d1689 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -819,6 +819,7 @@ onInvalidate: (listener: InvalidateListener) => () => voidpathForHandle: (kind: string, handle: number) => string | nullpreload: (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: () => voidrecoverFromDeviceLoss: () => Promise<boolean>register: <T>(loader: AssetLoader<T>) => voidreleaseAll: () => void@@ -844,6 +845,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => voidsetRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+spineCertificates: SpineCertificatestexturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c4fc23be7..c9947b8a5 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -814,6 +814,7 @@ onInvalidate: (listener: InvalidateListener) => () => voidpathForHandle: (kind: string, handle: number) => string | nullpreload: (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: () => voidrecoverFromDeviceLoss: () => Promise<boolean>register: <T>(loader: AssetLoader<T>) => voidreleaseAll: () => void@@ -839,6 +840,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => voidsetRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+spineCertificates: SpineCertificatestexturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex ace29816f..92aac3467 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -814,6 +814,7 @@ onInvalidate: (listener: InvalidateListener) => () => voidpathForHandle: (kind: string, handle: number) => string | nullpreload: (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: () => voidrecoverFromDeviceLoss: () => Promise<boolean>register: <T>(loader: AssetLoader<T>) => voidreleaseAll: () => void@@ -839,6 +840,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => voidsetRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+spineCertificates: SpineCertificatestexturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 78cf150f8..b0ba129df 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -814,6 +814,7 @@ onInvalidate: (listener: InvalidateListener) => () => voidpathForHandle: (kind: string, handle: number) => string | nullpreload: (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: () => voidrecoverFromDeviceLoss: () => Promise<boolean>register: <T>(loader: AssetLoader<T>) => voidreleaseAll: () => void@@ -839,6 +840,7 @@ setManifest: (manifest: AddressableManifest | ManifestModel | null) => voidsetRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+spineCertificates: SpineCertificatestexturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassdiff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 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.tsnew file mode 100644index 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.tsindex 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 thediff --git a/sdk/src/spine/spineCertificates.ts b/sdk/src/spine/spineCertificates.tsindex 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.tsnew file mode 100644index 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 });+ });+});