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
fix(spine): a culling contract reaches a runtime, for the first time
esengine23e334ee078b
diff --git a/desktop b/desktopindex d6d344bf0..e5075c1df 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit d6d344bf0cf0b2fbdd74715f4d5605d7dee156a0+Subproject commit e5075c1dfc4c3572ef7d96fa21cbbebacaffe322diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex d5f48e904..81eab631e 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": 1664,+ "experimental": 1669,"deprecated": 3},- "total": 1868,+ "total": 1873,"subsystems": [{"id": "ecs",diff --git a/pipeline/src/assets/addressableManifest.ts b/pipeline/src/assets/addressableManifest.tsindex f5dbc7048..5977da968 100644--- a/pipeline/src/assets/addressableManifest.ts+++ b/pipeline/src/assets/addressableManifest.ts@@ -19,6 +19,7 @@ import { readFile, stat } from 'node:fs/promises';import path from 'node:path';import { deriveManifestRevision, type AddressableManifest } from '../../../sdk/src/asset/AddressableManifest';import { textureImportSettingsFrom, type ParsedTextureImportSettings } from '../../../sdk/src/asset/textureImportSettings';+import { spineManifestContractFrom, type SpineManifestContract } from '../../../sdk/src/asset/spineImportSettings';/** The flat v1.0 cook manifest this reads (see cookAssets `CookManifestEntry`). */interface FlatManifest {@@ -60,10 +61,22 @@ export async function buildAddressableManifest(absOut: string): Promise<string>path: string; address?: string; type: string; size: number; labels: string[]; contentHash?: string;compressedFormats?: string[];textureImport?: ParsedTextureImportSettings;+ spineImport?: SpineManifestContract;metadata?: { atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number }; atlasPageWidth?: number; atlasPageHeight?: number };};type Group = { bundleMode: string; labels: string[]; assets: Record<string, Entry> };const groups: Record<string, Group> = {};+ // Every spelling this build knows an asset by → its key. A spine contract+ // names the atlas it was promised against however the author's metadata+ // spelled it; what ships is this build's key for that asset.+ const keyOfRef = new Map<string, string>();+ for (const e of flat.entries) {+ const key = e.uuid.toLowerCase();+ for (const spelling of [e.uuid, e.uuid.toLowerCase(), `@uuid:${e.uuid}`,+ `@uuid:${e.uuid.toLowerCase()}`, e.path, e.sourcePath]) {+ if (spelling) keyOfRef.set(spelling, key);+ }+ }for (const e of flat.entries) {let size = e.size ?? 0;if (e.size == null) { try { size = (await stat(path.join(absOut, e.path))).size; } catch { /* missing → 0 */ } }@@ -84,6 +97,10 @@ export async function buildAddressableManifest(absOut: string): Promise<string>// editor.const textureImport = textureImportSettingsFrom(e.importer);if (textureImport) entry.textureImport = textureImport;+ // Same channel and the same reason: without it a shipped game poses every+ // skeleton every frame while the editor honoured the author's promise.+ const spineImport = spineManifestContractFrom(e.importer, (ref) => keyOfRef.get(ref));+ if (spineImport) entry.spineImport = spineImport;// The logical source path rides as the asset's address: path-style refs// resolve through it. Only meaningful when staging renamed the file.if (e.sourcePath && e.sourcePath !== e.path) entry.address = e.sourcePath;diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.tsindex 83fb42e72..a6cfb1efb 100644--- a/pipeline/src/project/importSettings.ts+++ b/pipeline/src/project/importSettings.ts@@ -107,6 +107,13 @@ const SPINE: ImporterFieldSpec[] = [+ 'in view can be culled while visible.',},{ key: 'cullingBounds.height', label: 'Culling Height', type: 'number', default: 0, min: 0, category: 'Culling', advanced: true },+ {+ key: 'cullingAtlas', label: 'Culling Atlas', type: 'string', default: '',+ category: 'Culling', advanced: true,+ tooltip: 'The atlas this promise was made against — written by "Use as Fixed Culling '+ + 'Bounds", not by hand. A spine asset is a skeleton AND an atlas, so the same '+ + 'skeleton drawn with a different atlas inherits no promise. Empty means no promise.',+ },];// Which armature and animation an entity gets are DragonBonesAnimation fieldsdiff --git a/sdk/etc/dragonbones.api.md b/sdk/etc/dragonbones.api.mdindex beb99cbf0..150f1a0c9 100644--- a/sdk/etc/dragonbones.api.md+++ b/sdk/etc/dragonbones.api.md@@ -142,6 +142,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 75624fb40..654163209 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1502 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1507 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -121,6 +121,7 @@ labels: string[]metadata: { atlas?: string; atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number; }; atlasPageWidth?: number; atlasPageHeight?: number; } | undefinedpath: stringsize: number+spineImport: SpineManifestContract | undefinedtextureImport: ParsedTextureImportSettings | undefinedtype: AddressableAssetType```@@ -775,7 +776,7 @@ ResourceDef<AssetsClass>@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<PreparedLoad<unknown>>) => void@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined-@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }+@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registrySlots: number; trackedRefRows: number; }acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>@@ -788,7 +789,6 @@ fetchBinary: (ref: string) => Promise<ArrayBuffer>fetchJson: <T = unknown>(ref: string) => Promise<T>fetchText: (ref: string) => Promise<string>getAssetRefResolver: () => AssetRefResolver | null-getAssetRegistry: () => AssetRegistry | nullgetAtlasFrame: (ref: string) => AtlasFrameInfo | nullgetLoader: <T>(type: string) => AssetLoader<T> | undefinedgetManifest: () => ManifestModel | null@@ -819,7 +819,6 @@ 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@@ -840,12 +839,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => voidrestorePersistedUpdate: (key: string) => booleanreuploadTexturesAfterDeviceLoss: () => Promise<number>setAssetRefResolver: (resolver: AssetRefResolver) => void-setAssetRegistry: (registry: AssetRegistry) => voidsetManifest: (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): AssetsClass@@ -4444,6 +4441,7 @@ remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | null+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefinedstatic empty: () => ManifestModelstatic fromJson: (manifest: AddressableManifest) => ManifestModel@@ -5148,6 +5146,7 @@ catalog: Catalog | undefinedmanifest: AddressableManifestmodel: ManifestModelresolvePath: (ref: string) => string+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImport: (ref: string) => ParsedTextureImportSettings | undefined```@@ -6645,6 +6644,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```@@ -7395,6 +7395,20 @@ timeScale: numbersetAnimation: (entity: Entity, animation: string, loop: boolean) => void```+## SpineCullingContract — interface @experimental+```+atlas: string+bounds: SpineCullingRect+```++## SpineCullingRect — interface @experimental+```+height: number+width: number+x: number+y: number+```+## SpineEvents — const @experimental```ResourceDef<SpineEventsData>@@ -7406,6 +7420,12 @@ error: string | undefinedsuccess: boolean```+## SpineManifestContract — interface @experimental+```+atlas: string+cullingBounds: SpineCullingRect+```+## SpinePlugin — class @experimental```build: (app: App) => void@@ -12171,6 +12191,16 @@ ServicesPlugin(init: UIEntityInit): Entity```+## spineCullingContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined+```++## spineManifestContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null, keyOfRef: (ref: string) => string | undefined): SpineManifestContract | undefined+```+## spineModuleId — function @experimental```(version: SpineVersion): SideModuleIddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 19a6d1689..7196e63f0 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 89 beta · 1521 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1526 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -121,6 +121,7 @@ labels: string[]metadata: { atlas?: string; atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number; }; atlasPageWidth?: number; atlasPageHeight?: number; } | undefinedpath: stringsize: number+spineImport: SpineManifestContract | undefinedtextureImport: ParsedTextureImportSettings | undefinedtype: AddressableAssetType```@@ -775,7 +776,7 @@ ResourceDef<AssetsClass>@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<PreparedLoad<unknown>>) => void@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined-@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }+@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registrySlots: number; trackedRefRows: number; }acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>@@ -788,7 +789,6 @@ fetchBinary: (ref: string) => Promise<ArrayBuffer>fetchJson: <T = unknown>(ref: string) => Promise<T>fetchText: (ref: string) => Promise<string>getAssetRefResolver: () => AssetRefResolver | null-getAssetRegistry: () => AssetRegistry | nullgetAtlasFrame: (ref: string) => AtlasFrameInfo | nullgetLoader: <T>(type: string) => AssetLoader<T> | undefinedgetManifest: () => ManifestModel | null@@ -819,7 +819,6 @@ 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@@ -840,12 +839,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => voidrestorePersistedUpdate: (key: string) => booleanreuploadTexturesAfterDeviceLoss: () => Promise<number>setAssetRefResolver: (resolver: AssetRefResolver) => void-setAssetRegistry: (registry: AssetRegistry) => voidsetManifest: (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): AssetsClass@@ -4452,6 +4449,7 @@ remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | null+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefinedstatic empty: () => ManifestModelstatic fromJson: (manifest: AddressableManifest) => ManifestModel@@ -5331,6 +5329,7 @@ catalog: Catalog | undefinedmanifest: AddressableManifestmodel: ManifestModelresolvePath: (ref: string) => string+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImport: (ref: string) => ParsedTextureImportSettings | undefined```@@ -6838,6 +6837,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```@@ -7588,6 +7588,20 @@ timeScale: numbersetAnimation: (entity: Entity, animation: string, loop: boolean) => void```+## SpineCullingContract — interface @experimental+```+atlas: string+bounds: SpineCullingRect+```++## SpineCullingRect — interface @experimental+```+height: number+width: number+x: number+y: number+```+## SpineEvents — const @experimental```ResourceDef<SpineEventsData>@@ -7599,6 +7613,12 @@ error: string | undefinedsuccess: boolean```+## SpineManifestContract — interface @experimental+```+atlas: string+cullingBounds: SpineCullingRect+```+## SpinePlugin — class @experimental```build: (app: App) => void@@ -12414,6 +12434,16 @@ ServicesPlugin(init: UIEntityInit): Entity```+## spineCullingContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined+```++## spineManifestContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null, keyOfRef: (ref: string) => string | undefined): SpineManifestContract | undefined+```+## spineModuleId — function @experimental```(version: SpineVersion): SideModuleIddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c9947b8a5..79b4f7ede 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 86 beta · 1501 experimental · 3 deprecated+Symbols: 113 public · 86 beta · 1506 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -116,6 +116,7 @@ labels: string[]metadata: { atlas?: string; atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number; }; atlasPageWidth?: number; atlasPageHeight?: number; } | undefinedpath: stringsize: number+spineImport: SpineManifestContract | undefinedtextureImport: ParsedTextureImportSettings | undefinedtype: AddressableAssetType```@@ -770,7 +771,7 @@ ResourceDef<AssetsClass>@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<PreparedLoad<unknown>>) => void@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined-@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }+@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registrySlots: number; trackedRefRows: number; }acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>@@ -783,7 +784,6 @@ fetchBinary: (ref: string) => Promise<ArrayBuffer>fetchJson: <T = unknown>(ref: string) => Promise<T>fetchText: (ref: string) => Promise<string>getAssetRefResolver: () => AssetRefResolver | null-getAssetRegistry: () => AssetRegistry | nullgetAtlasFrame: (ref: string) => AtlasFrameInfo | nullgetLoader: <T>(type: string) => AssetLoader<T> | undefinedgetManifest: () => ManifestModel | null@@ -814,7 +814,6 @@ 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@@ -835,12 +834,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => voidrestorePersistedUpdate: (key: string) => booleanreuploadTexturesAfterDeviceLoss: () => Promise<number>setAssetRefResolver: (resolver: AssetRefResolver) => void-setAssetRegistry: (registry: AssetRegistry) => voidsetManifest: (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): AssetsClass@@ -4439,6 +4436,7 @@ remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | null+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefinedstatic empty: () => ManifestModelstatic fromJson: (manifest: AddressableManifest) => ManifestModel@@ -5143,6 +5141,7 @@ catalog: Catalog | undefinedmanifest: AddressableManifestmodel: ManifestModelresolvePath: (ref: string) => string+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImport: (ref: string) => ParsedTextureImportSettings | undefined```@@ -6640,6 +6639,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```@@ -7390,6 +7390,20 @@ timeScale: numbersetAnimation: (entity: Entity, animation: string, loop: boolean) => void```+## SpineCullingContract — interface @experimental+```+atlas: string+bounds: SpineCullingRect+```++## SpineCullingRect — interface @experimental+```+height: number+width: number+x: number+y: number+```+## SpineEvents — const @experimental```ResourceDef<SpineEventsData>@@ -7401,6 +7415,12 @@ error: string | undefinedsuccess: boolean```+## SpineManifestContract — interface @experimental+```+atlas: string+cullingBounds: SpineCullingRect+```+## SpinePlugin — class @experimental```build: (app: App) => void@@ -12176,6 +12196,16 @@ ServicesPlugin(init: UIEntityInit): Entity```+## spineCullingContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined+```++## spineManifestContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null, keyOfRef: (ref: string) => string | undefined): SpineManifestContract | undefined+```+## spineModuleId — function @experimental```(version: SpineVersion): SideModuleIddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 92aac3467..c8c1a47ff 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1523 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1528 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -116,6 +116,7 @@ labels: string[]metadata: { atlas?: string; atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number; }; atlasPageWidth?: number; atlasPageHeight?: number; } | undefinedpath: stringsize: number+spineImport: SpineManifestContract | undefinedtextureImport: ParsedTextureImportSettings | undefinedtype: AddressableAssetType```@@ -770,7 +771,7 @@ ResourceDef<AssetsClass>@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<PreparedLoad<unknown>>) => void@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined-@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }+@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registrySlots: number; trackedRefRows: number; }acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>@@ -783,7 +784,6 @@ fetchBinary: (ref: string) => Promise<ArrayBuffer>fetchJson: <T = unknown>(ref: string) => Promise<T>fetchText: (ref: string) => Promise<string>getAssetRefResolver: () => AssetRefResolver | null-getAssetRegistry: () => AssetRegistry | nullgetAtlasFrame: (ref: string) => AtlasFrameInfo | nullgetLoader: <T>(type: string) => AssetLoader<T> | undefinedgetManifest: () => ManifestModel | null@@ -814,7 +814,6 @@ 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@@ -835,12 +834,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => voidrestorePersistedUpdate: (key: string) => booleanreuploadTexturesAfterDeviceLoss: () => Promise<number>setAssetRefResolver: (resolver: AssetRefResolver) => void-setAssetRegistry: (registry: AssetRegistry) => voidsetManifest: (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): AssetsClass@@ -4439,6 +4436,7 @@ remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | null+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefinedstatic empty: () => ManifestModelstatic fromJson: (manifest: AddressableManifest) => ManifestModel@@ -5389,6 +5387,7 @@ catalog: Catalog | undefinedmanifest: AddressableManifestmodel: ManifestModelresolvePath: (ref: string) => string+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImport: (ref: string) => ParsedTextureImportSettings | undefined```@@ -6886,6 +6885,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```@@ -7636,6 +7636,20 @@ timeScale: numbersetAnimation: (entity: Entity, animation: string, loop: boolean) => void```+## SpineCullingContract — interface @experimental+```+atlas: string+bounds: SpineCullingRect+```++## SpineCullingRect — interface @experimental+```+height: number+width: number+x: number+y: number+```+## SpineEvents — const @experimental```ResourceDef<SpineEventsData>@@ -7647,6 +7661,12 @@ error: string | undefinedsuccess: boolean```+## SpineManifestContract — interface @experimental+```+atlas: string+cullingBounds: SpineCullingRect+```+## SpinePlugin — class @experimental```build: (app: App) => void@@ -12433,6 +12453,16 @@ ServicesPlugin(init: UIEntityInit): Entity```+## spineCullingContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined+```++## spineManifestContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null, keyOfRef: (ref: string) => string | undefined): SpineManifestContract | undefined+```+## spineModuleId — function @experimental```(version: SpineVersion): SideModuleIddiff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.mdindex c1f5ebac9..c9624872c 100644--- a/sdk/etc/spine.api.md+++ b/sdk/etc/spine.api.md@@ -31,6 +31,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```@@ -74,17 +75,7 @@ update: (instanceId: number, dt: number) => void## SpineCertificateSource — interface @experimental```-envelopeFor: (pairKey: string) => SpineCullingEnvelope-```--## SpineCertificates — class @experimental-```-certify: (pairKey: string, bounds: SpineAABB) => void-clear: () => void-envelopeFor: (pairKey: string) => SpineCullingEnvelope-revoke: (pairKey: string) => void-static new (): SpineCertificates-static prototype: SpineCertificates+envelopeFor: (skeleton: string, atlas: string) => SpineCullingEnvelope```## SpineCullingEnvelope — type @experimental@@ -97,6 +88,11 @@ static prototype: SpineCertificates| { kind: 'unknown' }```+## SpineCullingProvider — interface @experimental+```+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined+```+## SpineDeferralBlocker — type @experimental```'no-certificate' | 'stateful-constraints'@@ -397,7 +393,7 @@ mixY: number## loadSpineAssets — function @experimental```-(module: ESEngineModule | null, source: RuntimeAssetSource, spineManager: SpineManager | null | undefined, spinePairs: ReadonlyArray<{ skeleton: string; atlas: string; }>, transcoderProvider?: TranscoderProvider, owner?: SpineAssetOwner, certificates?: SpineCertificateSource): Promise<Map<string, SpineAssetInfo>>+(module: ESEngineModule | null, source: RuntimeAssetSource, spineManager: SpineManager | null | undefined, spinePairs: ReadonlyArray<{ skeleton: string; atlas: string; }>, transcoderProvider?: TranscoderProvider, owner?: SpineAssetOwner): Promise<Map<string, SpineAssetInfo>>```## loadSpineSceneEntities — function @experimental@@ -410,11 +406,6 @@ mixY: number(envelope: SpineCullingEnvelope, requiresContinuousWorldPose: boolean): boolean```-## projectSpineCertificates — function @experimental-```-(into: SpineCertificates, entries: ReadonlyArray<{ path: string; importer?: Record<string, unknown>; }>, atlasOf: (skeletonPath: string) => string | null): void-```-## scanObservedBounds — function @experimental```(source: SpineBoundsSource, skeletonHandle: number, era: string, sampleStep?: number): SpineCullingEnvelope@@ -425,6 +416,11 @@ mixY: number(source: SpineBoundsSource, skeletonHandle: number): SpineAABB | null```+## spineCertificatesFrom — function @experimental+```+(source: SpineCullingProvider): SpineCertificateSource+```+## spineEntityProps — function @experimental```(d: Record<string, unknown>): { skeletonScale: number; flipX: boolean; flipY: boolean; layer: number; timeScale: number; playing: boolean; color?: { r: number; g: number; b: number; a: number; }; }diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b0ba129df..4b096156f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1513 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1518 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -116,6 +116,7 @@ labels: string[]metadata: { atlas?: string; atlasPage?: number; atlasFrame?: { x: number; y: number; width: number; height: number; }; atlasPageWidth?: number; atlasPageHeight?: number; } | undefinedpath: stringsize: number+spineImport: SpineManifestContract | undefinedtextureImport: ParsedTextureImportSettings | undefinedtype: AddressableAssetType```@@ -770,7 +771,7 @@ ResourceDef<AssetsClass>@internal releaseTyped: (type: string, ref: string) => void@internal releaseTypedLease: (type: string, lease: AssetRefLease<PreparedLoad<unknown>>) => void@internal resolveRegistryAsset: <T>(type: string, ref: string) => T | undefined-@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; registrySlots: number; trackedRefRows: number; }+@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registrySlots: number; trackedRefRows: number; }acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>@@ -783,7 +784,6 @@ fetchBinary: (ref: string) => Promise<ArrayBuffer>fetchJson: <T = unknown>(ref: string) => Promise<T>fetchText: (ref: string) => Promise<string>getAssetRefResolver: () => AssetRefResolver | null-getAssetRegistry: () => AssetRegistry | nullgetAtlasFrame: (ref: string) => AtlasFrameInfo | nullgetLoader: <T>(type: string) => AssetLoader<T> | undefinedgetManifest: () => ManifestModel | null@@ -814,7 +814,6 @@ 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@@ -835,12 +834,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => voidrestorePersistedUpdate: (key: string) => booleanreuploadTexturesAfterDeviceLoss: () => Promise<number>setAssetRefResolver: (resolver: AssetRefResolver) => void-setAssetRegistry: (registry: AssetRegistry) => voidsetManifest: (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): AssetsClass@@ -4446,6 +4443,7 @@ remoteAssetIdentity: (ref: string) => string | nullremoteAssetPath: (ref: string) => string | nullresolvePath: (ref: string, normalize?: (ref: string) => string) => stringrevision: () => string | null+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefinedstatic empty: () => ManifestModelstatic fromJson: (manifest: AddressableManifest) => ManifestModel@@ -5150,6 +5148,7 @@ catalog: Catalog | undefinedmanifest: AddressableManifestmodel: ManifestModelresolvePath: (ref: string) => string+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefinedtextureImport: (ref: string) => ParsedTextureImportSettings | undefined```@@ -6647,6 +6646,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:listAssetPaths: (() => string[]) | undefinedresolveAddress: ((ref: string) => string | null) | undefinedresolveRef: ((ref: string) => string) | undefined+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefinedtextureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined```@@ -7397,6 +7397,20 @@ timeScale: numbersetAnimation: (entity: Entity, animation: string, loop: boolean) => void```+## SpineCullingContract — interface @experimental+```+atlas: string+bounds: SpineCullingRect+```++## SpineCullingRect — interface @experimental+```+height: number+width: number+x: number+y: number+```+## SpineEvents — const @experimental```ResourceDef<SpineEventsData>@@ -7408,6 +7422,12 @@ error: string | undefinedsuccess: boolean```+## SpineManifestContract — interface @experimental+```+atlas: string+cullingBounds: SpineCullingRect+```+## SpinePlugin — class @experimental```build: (app: App) => void@@ -12199,6 +12219,16 @@ ServicesPlugin(init: UIEntityInit): Entity```+## spineCullingContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null): SpineCullingContract | undefined+```++## spineManifestContractFrom — function @experimental+```+(importer: Record<string, unknown> | undefined | null, keyOfRef: (ref: string) => string | undefined): SpineManifestContract | undefined+```+## spineModuleId — function @experimental```(version: SpineVersion): SideModuleIddiff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.tsindex c7549c580..64156bf1a 100644--- a/sdk/src/asset/AddressableManifest.ts+++ b/sdk/src/asset/AddressableManifest.ts@@ -2,6 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { AddressableAssetType } from '../assetTypes';import { indexTextureImportSettings, type ParsedTextureImportSettings } from './textureImportSettings';+import type { SpineCullingRect, SpineManifestContract } from './spineImportSettings';import { contentHashOf } from './contentHash';export type { AddressableAssetType };@@ -30,6 +31,14 @@ export interface AddressableManifestAsset {* texture or its importer says nothing the renderer acts on.*/textureImport?: ParsedTextureImportSettings;+ /**+ * A spine skeleton's culling promise: the rectangle, and the ATLAS it was+ * promised against as this manifest's own KEY, not a build locator.+ *+ * It ships rather than being re-derived, which would honour the promise+ * after a skeleton was re-pointed at another atlas.+ */+ spineImport?: SpineManifestContract;metadata?: {atlas?: string;atlasPage?: number;@@ -110,6 +119,17 @@ export function normalizeBundleMode(mode: string | undefined | null): BundleMode* / bundle-mode questions, so loaders and exporters never re-walk `groups` by* hand and never re-interpret the bare `bundleMode` string.*/+/** Every way a manifest entry can be named — the spellings a ref may arrive as. */+function spellingsOf(key: string, path: string, address: string | undefined): string[] {+ const out: string[] = [];+ for (const spelling of [key, `@uuid:${key}`, path, address]) {+ if (!spelling) continue;+ out.push(spelling);+ if (!spelling.startsWith('/')) out.push(`/${spelling}`);+ }+ return out;+}+export class ManifestModel {private constructor(private readonly manifest: AddressableManifest) {}@@ -188,6 +208,32 @@ export class ManifestModel {);}+ /**+ * The culling contract this build ships for a spine PAIR, or undefined.+ *+ * Both refs, because there is no useful answer about a skeleton alone. The+ * atlas is compared as an IDENTITY — `@uuid:…`, a path and an address all+ * agree — so one the contract was not made against inherits nothing.+ */+ spineCullingLookup(): (skeleton: string, atlas: string) => SpineCullingRect | undefined {+ const contracts = new Map<string, SpineManifestContract>();+ const identity = new Map<string, string>();+ for (const { key, asset } of this.entries()) {+ for (const spelling of spellingsOf(key, asset.path, asset.address)) {+ identity.set(spelling, key);+ if (asset.spineImport) contracts.set(spelling, asset.spineImport);+ }+ }+ if (contracts.size === 0) return () => undefined;+ return (skeleton, atlas) => {+ const contract = contracts.get(skeleton);+ if (!contract) return undefined;+ // Identity settles it, and unknown is a no. `contract.atlas` is+ // already a key, so only the ref in hand is canonicalised.+ return identity.get(atlas) === contract.atlas ? contract.cullingBounds : undefined;+ };+ }+/** The manifest's build content revision (see {@link deriveManifestRevision}),* or null on a legacy manifest that predates the field. */revision(): string | null {diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 97e452139..71bb83d1a 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -49,12 +49,10 @@ import { discoverSceneAssets } from './discoverAssets';import { fetchDecodePixels } from './imageDecode';import type { SceneData, AssetFieldType } from '../scene/scene';import { SceneHandle, type ReleaseCallback } from './SceneHandle';-import type { AssetRegistry } from './AssetRegistry';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@@ -384,7 +382,6 @@ export class Assets {private settling_ = new Set<Promise<void>>();private loadContext_: LoadContext | null = null;private assetRefResolver_: AssetRefResolver | null = null;- private assetRegistry_: AssetRegistry | null = null;private refCounter_: AssetRefCounter | null = null;private invalidateListeners_ = new Set<InvalidateListener>();private readonly appScope_ = new AssetScope();@@ -1902,7 +1899,6 @@ export class Assets {genericCached: number;handlePaths: number;invalidateListeners: number;- registryEntries: number;registrySlots: number;trackedRefRows: number;} {@@ -1923,7 +1919,6 @@ export class Assets {genericCached,handlePaths: this.handleToPath_.size,invalidateListeners: this.invalidateListeners_.size,- registryEntries: this.assetRegistry_?.size ?? 0,registrySlots: this.registrySlots_.size,trackedRefRows: this.refCounter_?.getTotalRefRows() ?? 0,};@@ -2004,49 +1999,6 @@ export class Assets {return this.assetRefResolver_;}- /**- * Attach an AssetRegistry so that scene/prefab refs of the form- * `"@uuid:..."` are resolved to current paths before loading.- * Convenience over `setAssetRefResolver`: sets the resolver to- * `registry.resolveRef`.- */- 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 {- return this.assetRegistry_;- }-/*** Attach an AssetRefCounter. When set, resolveSceneAssetPaths records* which entity references which texture/material/font path as it@@ -2056,8 +2008,6 @@ 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/index.ts b/sdk/src/asset/index.tsindex afafce364..393d4b0e6 100644--- a/sdk/src/asset/index.ts+++ b/sdk/src/asset/index.ts@@ -34,6 +34,8 @@ export {export { xxh64, contentHashHex, contentHashOf } from './contentHash';export { AsyncCache } from './AsyncCache';export { textureImportSettingsFrom, type ParsedTextureImportSettings } from './textureImportSettings';+export { spineCullingContractFrom, spineManifestContractFrom } from './spineImportSettings';+export type { SpineCullingRect, SpineCullingContract, SpineManifestContract } from './spineImportSettings';export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels, fetchDecodePixels } from './imageDecode';export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';diff --git a/sdk/src/asset/spineImportSettings.ts b/sdk/src/asset/spineImportSettings.tsindex 845e80594..84c967dbd 100644--- a/sdk/src/asset/spineImportSettings.ts+++ b/sdk/src/asset/spineImportSettings.ts@@ -5,19 +5,33 @@* @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.+ * inspector edits and the cook copies into the ship manifest.+ *+ * A contract is a rectangle AND the atlas it was promised against, and the type+ * says so rather than leaving them two optional fields. A spine asset is a+ * PAIR — an atlas decides how its regions were trimmed and so what geometry the+ * attachments end up with — so a rectangle with no atlas beside it is a promise+ * about nothing in particular. Recording the atlas at authoring time is also+ * what makes the promise stop applying when somebody re-points the skeleton at+ * a different one, which is the direction this has to fail in.*/-/** The rectangle a spine asset promises to stay inside, in skeleton space. */-export interface ParsedSpineImportSettings {- cullingBounds?: { x: number; y: number; width: number; height: number };+/** A rectangle in the skeleton's own space, as the `.meta` stores it. */+export interface SpineCullingRect {+ x: number;+ y: number;+ width: number;+ height: number;+}++/** What an author promised, and what they promised it about. */+export interface SpineCullingContract {+ bounds: SpineCullingRect;+ /** The atlas ref the promise was recorded against. */+ atlas: string;}-function readBounds(raw: unknown): ParsedSpineImportSettings['cullingBounds'] {+function readBounds(raw: unknown): SpineCullingRect | undefined {if (!raw || typeof raw !== 'object') return undefined;const b = raw as Record<string, unknown>;const n = (v: unknown): number | null =>@@ -33,11 +47,42 @@ function readBounds(raw: unknown): ParsedSpineImportSettings['cullingBounds'] {return { x, y, width, height };}-/** Parse an importer block; undefined when it carries no contract. */-export function spineImportSettingsFrom(+/**+ * Parse an importer block; undefined when it carries no contract.+ *+ * Both halves or neither: a fresh `.meta` carries every declared setting's+ * default, so the state "no contract" is a zero-area rectangle and an empty+ * atlas rather than absent keys — and half a contract is not one.+ */+export function spineCullingContractFrom(importer: Record<string, unknown> | undefined | null,-): ParsedSpineImportSettings | undefined {+): SpineCullingContract | undefined {if (!importer) return undefined;- const cullingBounds = readBounds(importer.cullingBounds);- return cullingBounds ? { cullingBounds } : undefined;+ const bounds = readBounds(importer.cullingBounds);+ const atlas = typeof importer.cullingAtlas === 'string' ? importer.cullingAtlas.trim() : '';+ return bounds && atlas ? { bounds, atlas } : undefined;+}++/** What the manifest ships for a skeleton: the rectangle, and the atlas as this+ * build's own asset key. */+export interface SpineManifestContract {+ cullingBounds: SpineCullingRect;+ atlas: string;+}++/**+ * One skeleton's `.meta` → the manifest entry, or undefined. ONE function for+ * every writer, because two is how "works in Play, not in the build" is born.+ *+ * `keyOfRef` turns the recorded atlas into this build's key; a contract naming+ * an atlas this build does not ship is dropped.+ */+export function spineManifestContractFrom(+ importer: Record<string, unknown> | undefined | null,+ keyOfRef: (ref: string) => string | undefined,+): SpineManifestContract | undefined {+ const contract = spineCullingContractFrom(importer);+ if (!contract) return undefined;+ const atlas = keyOfRef(contract.atlas);+ return atlas ? { cullingBounds: contract.bounds, atlas } : undefined;}diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 35dcb4792..1c4b10875 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -92,6 +92,11 @@ export {type AssetRefInfo,textureImportSettingsFrom,type ParsedTextureImportSettings,+ spineCullingContractFrom,+ spineManifestContractFrom,+ type SpineCullingRect,+ type SpineCullingContract,+ type SpineManifestContract,} from './asset';/** When the live bindings that READ the asset graph have caught up with it —diff --git a/sdk/src/diagnostics/censusProbes.ts b/sdk/src/diagnostics/censusProbes.tsindex f499b70d0..fc0f54e14 100644--- a/sdk/src/diagnostics/censusProbes.ts+++ b/sdk/src/diagnostics/censusProbes.ts@@ -160,7 +160,6 @@ export function installBuiltinCensusProbes(): void {counter('asset.textureCached', s.textureCached, 'bounded'),counter('asset.genericCached', s.genericCached, 'bounded'),counter('asset.genericCaches', s.genericCaches, 'bounded'),- counter('asset.registryEntries', s.registryEntries, 'info'),];},});diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.tsindex 00cbca68b..0de2b5da2 100644--- a/sdk/src/runtime/packagedRuntime.ts+++ b/sdk/src/runtime/packagedRuntime.ts@@ -19,6 +19,7 @@ import { ManifestModel, type AddressableManifest } from '../asset/AddressableManimport { Catalog, atlasCatalogFields, type CatalogEntry } from '../asset/Catalog';import { FileSystemBackend, type Backend } from '../asset/Backend';import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';+import type { SpineCullingRect } from '../asset/spineImportSettings';import { Audio } from '../audio/Audio';import type { AudioProjectConfig } from '../audio/AudioProjectConfig';import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';@@ -114,6 +115,8 @@ export interface PackagedAssetIndex {assetPaths(): string[];/** How a texture is sampled and 9-sliced, for any ref spelling. */textureImport(ref: string): ParsedTextureImportSettings | undefined;+ /** The culling contract shipped for a spine PAIR, for any ref spelling. */+ spineCulling(skeleton: string, atlas: string): SpineCullingRect | undefined;}/**@@ -265,6 +268,7 @@ export function indexPackagedManifest(manifest: AddressableManifest): PackagedAs// and rebuilding the spelling map per ref would walk the whole manifest// each time.textureImport: model.textureImportLookup(),+ spineCulling: model.spineCullingLookup(),};}@@ -295,6 +299,7 @@ export function createPackagedAssetSource(resolveAddress: index.addressOf,listAssetPaths: index.assetPaths,textureImportSettings: index.textureImport,+ spineCulling: index.spineCulling,};}diff --git a/sdk/src/runtime/playRealmRuntime.ts b/sdk/src/runtime/playRealmRuntime.tsindex 6ea91726b..30d2bc10c 100644--- a/sdk/src/runtime/playRealmRuntime.ts+++ b/sdk/src/runtime/playRealmRuntime.ts@@ -141,6 +141,19 @@ export function resolvePlayAssetRef(return base ? `${base}/${ref.replace(/^\//, '')}` : ref;}+/**+ * What a manifest tells a realm about its assets, in one place: two lookups a+ * packaged build and an editor Play session read identically. Assembled once per+ * source — rebuilding a spelling map per ref would walk the manifest on every+ * asset a scene preloads.+ */+function manifestBackedSettings(model: ManifestModel): Partial<RuntimeAssetSource> {+ return {+ textureImportSettings: model.textureImportLookup(),+ spineCulling: model.spineCullingLookup(),+ };+}+function createPlayRealmSource(manifest: Record<string, string>,assetBaseUrl?: string,@@ -156,12 +169,10 @@ function createPlayRealmSource(// manifest's resolved URLs — both keep the real extension, which is all// the .eslocale discovery filters on.listAssetPaths: () => (pathMap ? Object.keys(pathMap) : Object.values(manifest)),- // Sampling and the 9-slice border come off the addressable manifest, the- // same field a cooked build reads — Play and ship cannot disagree about- // an asset when they are looking at one description of it.- ...(addressable- ? { textureImportSettings: ManifestModel.fromJson(addressable).textureImportLookup() }- : {}),+ // Sampling, and the spine culling contract, both come off the addressable+ // manifest — the same fields a cooked build reads, so Play and ship+ // cannot disagree about what an author promised.+ ...(addressable ? manifestBackedSettings(ManifestModel.fromJson(addressable)) : {}),};}diff --git a/sdk/src/runtime/runtimeAssets.ts b/sdk/src/runtime/runtimeAssets.tsindex a661c5f72..49f44c9ea 100644--- a/sdk/src/runtime/runtimeAssets.ts+++ b/sdk/src/runtime/runtimeAssets.ts@@ -63,6 +63,11 @@ export interface RuntimeAssetSource {* the `importer` block the cook copies into the ship manifest.*/textureImportSettings?(ref: string): ParsedTextureImportSettings | undefined;+ /** The rectangle no pose of this spine PAIR leaves, in the skeleton's own+ * space. Both refs, since an atlas the promise was not recorded against+ * inherits nothing; a realm without this certifies nothing. */+ spineCulling?(skeleton: string, atlas: string):+ { x: number; y: number; width: number; height: number } | undefined;}export interface TextureParams {diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex 3d9693054..94f0a3b03 100644--- a/sdk/src/runtime/runtimeLoader.ts+++ b/sdk/src/runtime/runtimeLoader.ts@@ -344,8 +344,7 @@ 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 },- sceneAssets.spineCertificates)+ { assets: sceneAssets, scope: assetResult.scope }): new Map<string, SpineAssetInfo>();// DragonBones, the same two phases. The manager is acquired only when thediff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.tsindex 5f68ee842..d7482f677 100644--- a/sdk/src/spine/index.ts+++ b/sdk/src/spine/index.ts@@ -17,8 +17,8 @@ export {setupBounds, scanObservedBounds, certifyBounds, envelopeFor, mayDeferWorldPose,worldBounds, contains,} from './spineBounds';-export { SpineCertificates, projectSpineCertificates, NO_CERTIFICATES } from './spineCertificates';-export type { SpineCertificateSource } from './spineCertificates';+export { spineCertificatesFrom, NO_CERTIFICATES } from './spineCertificates';+export type { SpineCertificateSource, SpineCullingProvider } from './spineCertificates';export { spineSceneDiagnostics, formatSpineDiagnostics } from './spineSceneDiagnostics';export type {SpineSceneDiagnostics, SpineAssetDiagnostic, SpineFinding, SpineFindingCode,diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.tsindex 26641d5b5..0443bdf85 100644--- a/sdk/src/spine/loadSpineScene.ts+++ b/sdk/src/spine/loadSpineScene.ts@@ -31,8 +31,7 @@ import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimport type { BasisTranscoder } from '../asset/compressed';import type { AssetsData } from '../asset/AssetPlugin';import type { AssetScope } from '../asset/AssetLease';-import { NO_CERTIFICATES } from './spineCertificates';-import type { SpineCertificateSource } from './spineCertificates';+import { spineCertificatesFrom } from './spineCertificates';/*** The in-place editable spine props from a SpineAnimation component's data — the@@ -102,11 +101,11 @@ export async function loadSpineAssets(spinePairs: ReadonlyArray<{ skeleton: string; atlas: string }>,transcoderProvider?: TranscoderProvider,owner?: SpineAssetOwner,- /** The promises this realm has recorded about spine assets' extents. Absent- * means none, which is what makes an unconfigured project behave exactly as- * it did: nothing is certified, so nothing may defer a world pose. */- certificates: SpineCertificateSource = NO_CERTIFICATES,): Promise<Map<string, SpineAssetInfo>> {+ // Read from the SOURCE that serves the assets, not handed in: a promise+ // about an asset travels with the asset, and a caller that could pass a+ // different set is a second place a contract can come from.+ const certificates = spineCertificatesFrom(source);const assetInfoMap = new Map<string, SpineAssetInfo>();for (const pair of spinePairs) {@@ -120,7 +119,8 @@ 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(pair, lease as never, certificates.envelopeFor(key));+ era = spineEraOf(pair, lease as never,+ certificates.envelopeFor(pair.skeleton, pair.atlas));} else {const pages: number[] = [];const value = await prepareSpine(diff --git a/sdk/src/spine/spineCertificates.ts b/sdk/src/spine/spineCertificates.tsindex 5d2e135c1..73c01cb01 100644--- a/sdk/src/spine/spineCertificates.ts+++ b/sdk/src/spine/spineCertificates.ts@@ -7,78 +7,54 @@* @details A certified envelope is a statement somebody made about an asset, so* it belongs to the asset and not to a generation of its bytes: a hot* reload replaces what the skeleton does, not what was promised about- * it. That makes the key the PAIR — skeleton and atlas, the identity- * spine assets already have — and never a path on its own, because an- * atlas decides how its regions were trimmed and so what geometry the- * attachments end up with.+ * it. And it is about the PAIR — an atlas decides how its regions were+ * trimmed and so what geometry the attachments end up with — which is+ * why nothing here answers about a skeleton alone.*- * This is the read seam and nothing more. Where the promises are- * persisted is the project's business — import metadata today, an- * inspector writing that metadata later — and neither of them may- * reach past this to hand a runtime an envelope it did not certify.+ * It is a READ, not a table. This was a mutable projection somebody had+ * to remember to fill, and the thing that went wrong with it is the+ * only thing that can: nobody filled it, in any realm, ever. So the+ * question now goes straight to the authority a realm already ships —+ * the manifest the cook wrote from the `.meta` — and there is no moment+ * at which the projection can be out of date with it, because there is+ * no projection.*/-import type { SpineAABB, SpineCullingEnvelope } from './spineBounds';+import type { 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 {- /** The promise recorded for this pair, or unknown where there is none. */- envelopeFor(pairKey: string): SpineCullingEnvelope;+ /** The promise recorded for this PAIR, or unknown where there is none. */+ envelopeFor(skeleton: string, atlas: string): SpineCullingEnvelope;}-/**- * The promises a realm knows about, by pair.- *- * Only `certify` puts one in, and it takes a rectangle: an observation cannot- * become a promise by being stored somewhere that returns promises.- */-export class SpineCertificates implements SpineCertificateSource {- private byPair_ = new Map<string, SpineAABB>();-- /** Record that nothing this pair can pose leaves `bounds`. */- certify(pairKey: string, bounds: SpineAABB): void {- this.byPair_.set(pairKey, { ...bounds });- }-- /** Withdraw a promise: a pair with no contract has no envelope. */- revoke(pairKey: string): void {- 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' };- }+/** The slice of a realm's asset source a certificate is read from. */+export interface SpineCullingProvider {+ spineCulling?(skeleton: string, atlas: string):+ { x: number; y: number; width: number; height: number } | undefined;}/**- * 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.+ * The promises a realm ships, read from the source that serves its assets.+ *+ * A realm whose source answers nothing certifies nothing — which is what makes+ * an unconfigured project behave exactly as it did, and what makes an editor+ * preview (not a product runtime) simply not defer.*/-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 });- }+export function spineCertificatesFrom(source: SpineCullingProvider): SpineCertificateSource {+ const read = source.spineCulling?.bind(source);+ if (!read) return NO_CERTIFICATES;+ return {+ envelopeFor(skeleton, atlas) {+ const bounds = read(skeleton, atlas);+ return bounds+ ? certifyBounds({+ minX: bounds.x, minY: bounds.y,+ maxX: bounds.x + bounds.width, maxY: bounds.y + bounds.height,+ })+ : { kind: 'unknown' };+ },+ };}/** A realm with no recorded promises: everything materialises. */diff --git a/sdk/tests/spine-certificate-pipeline.test.ts b/sdk/tests/spine-certificate-pipeline.test.tsdeleted file mode 100644index 20b9dbc18..000000000--- a/sdk/tests/spine-certificate-pipeline.test.ts+++ /dev/null@@ -1,189 +0,0 @@-// 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 });- });-});diff --git a/sdk/tests/spine-contract-delivery.test.ts b/sdk/tests/spine-contract-delivery.test.tsnew file mode 100644index 000000000..16578aad5--- /dev/null+++ b/sdk/tests/spine-contract-delivery.test.ts@@ -0,0 +1,271 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spine-contract-delivery.test.ts+ * @brief An author's promise, from the `.meta` to a world pose nobody pays for.+ *+ * @details The criterion this replaces proved that the projection worked when+ * something handed it a registry, and nothing anywhere handed it one —+ * so a contract had never authorised a single deferred pose in any+ * realm, in any build, ever. A test can be green on both sides of a+ * seam that nobody crosses.+ *+ * So this one starts where an author actually leaves the promise and+ * ends where it is supposed to pay off, and NOTHING in it may inject a+ * certificate: no `certifyBounds`, no envelope handed to a constructor.+ * The only inputs are an importer block, a manifest built by the+ * shipping writer, and a scene naming its assets the way scenes do.+ *+ * That the mechanism works given a certificate is a different question,+ * answered by spine-demand-driven-pose. This one asks whether the+ * certificate is ever there.+ */+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { Assets } from '../src/asset/Assets';+import { Catalog } from '../src/asset/Catalog';+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 { SpineManager } from '../src/spine/SpineManager';+import { loadSpineAssets } from '../src/spine/loadSpineScene';+import { spinePairKey } from '../src/spine/prepareSpine';+import { spineManifestContractFrom } from '../src/asset/spineImportSettings';+import { ManifestModel, type AddressableManifest } from '../src/asset/AddressableManifest';+import type { RuntimeAssetSource } from '../src/runtime/runtimeAssets';+import { fakeSpineModule } from './helpers/fakeSpineModule';++function createPoolFake() {+ const live = new Set<number>();+ const byPath = new Map<string, number>();+ let next = 1;+ return {+ budget: 0,+ createTexture: vi.fn((): number => { const h = next++; live.add(h); return h; }),+ createTextureFromBytes: vi.fn((): number => { const h = next++; live.add(h); return h; }),+ registerTextureWithPath: vi.fn((handle: number, path: string) => { byPath.set(path, handle); }),+ acquireTextureByPath: vi.fn((path: string): number => byPath.get(path) ?? 0),+ invalidateTexturePath: vi.fn((path: string): boolean => byPath.delete(path)),+ releaseTexture: vi.fn((handle: number) => { live.delete(handle); }),+ getTextureDimensions: vi.fn(() => ({ width: 4, height: 4 })),+ getTextureGLId: vi.fn((handle: number) => handle + 1000),+ setTextureMetadata: vi.fn(),+ };+}+let pool = createPoolFake();+vi.mock('../src/wasm/resourceManager', () => ({+ requireResourceManager: () => pool,+ getResourceManager: () => pool,+ evictTextureDimensions: vi.fn(),+}));++const platformFactory = vi.hoisted(() => () => ({+ platformCreateCanvas: () => ({+ width: 4, height: 4,+ getContext: () => ({+ clearRect: vi.fn(), drawImage: vi.fn(),+ getImageData: () => ({ data: { buffer: new ArrayBuffer(64) } }),+ }),+ }),+ platformCreateImage: () => {+ const img: { width?: number; height?: number; onload?: () => void } = {};+ setTimeout(() => { img.width = 4; img.height = 4; img.onload?.(); }, 0);+ return img;+ },+ platformFetch: vi.fn(), platformReadFile: vi.fn(),+ platformReadTextFile: vi.fn(), platformFileExists: vi.fn(),+ platformLoadSubpackage: vi.fn(async () => {}),+ platformGetStorageItem: () => null, platformSetStorageItem: vi.fn(),+ platformWriteCacheFile: vi.fn(async () => {}),+}));+vi.mock('../src/platform', platformFactory);+vi.mock('../src/platform/base', platformFactory);++// The project, as files on somebody's disk.+const SKEL_UUID = '7386aaf3-55a9-4879-b4f3-95a5f6a1cde4';+const ATLAS_UUID = 'b5f07fb2-95dd-4ed5-98b8-414900e96b9d';+const OTHER_ATLAS_UUID = 'c0ffee00-0000-4000-8000-000000000001';+const SKEL_PATH = 'assets/spine/hero.skel';+const ATLAS_PATH = 'assets/spine/hero.atlas';+const OTHER_ATLAS_PATH = 'assets/spine/winter.atlas';++/** A scene names its assets by uuid — the shape the delivery actually failed in. */+const SKEL_REF = `@uuid:${SKEL_UUID}`;+const ATLAS_REF = `@uuid:${ATLAS_UUID}`;+const OTHER_ATLAS_REF = `@uuid:${OTHER_ATLAS_UUID}`;++/** The `.meta` importer block the inspector's "Use as Fixed Culling Bounds" left. */+const AUTHORED_META = {+ scale: 1,+ cullingBounds: { x: -200, y: -100, width: 400, height: 700 },+ cullingAtlas: ATLAS_REF,+};++const ASSET_TABLE = [+ { uuid: SKEL_UUID, path: SKEL_PATH, importer: AUTHORED_META as Record<string, unknown> },+ { uuid: ATLAS_UUID, path: ATLAS_PATH, importer: {} as Record<string, unknown> },+ { uuid: OTHER_ATLAS_UUID, path: OTHER_ATLAS_PATH, importer: {} as Record<string, unknown> },+];++/**+ * The manifest a build ships, through the writer BOTH production writers use.+ * Round-tripped through JSON, because that is what actually reaches a realm.+ */+function shippedManifest(table = ASSET_TABLE): AddressableManifest {+ const keyOfRef = new Map<string, string>();+ for (const { uuid, path } of table) {+ for (const spelling of [uuid, `@uuid:${uuid}`, path]) keyOfRef.set(spelling, uuid);+ }+ const assets: Record<string, unknown> = {};+ for (const { uuid, path, importer } of table) {+ const spineImport = spineManifestContractFrom(importer, (ref) => keyOfRef.get(ref));+ assets[uuid] = {+ path, type: 'binary', size: 0, labels: [],+ ...(spineImport ? { spineImport } : {}),+ };+ }+ const manifest = { version: '2.0', groups: { main: { bundleMode: 'local', labels: [], assets } } };+ return JSON.parse(JSON.stringify(manifest)) as AddressableManifest;+}++/** The realm's asset source, carrying only what a realm's source carries. */+function shippedSource(manifest: AddressableManifest): RuntimeAssetSource {+ return { spineCulling: ManifestModel.fromJson(manifest).spineCullingLookup() } as RuntimeAssetSource;+}++const atlasDoc = 'page.png\nsize: 4,4\nformat: RGBA8888\n';++/** A realm's Assets: uuid refs resolve to paths, exactly as `applyAssetRefResolvers` does. */+function realm(): Assets {+ const byUuid = new Map(ASSET_TABLE.map((a) => [`@uuid:${a.uuid}`, a.path]));+ const assets = Assets.create({+ backend: {+ fetchBinary: vi.fn(async () => new ArrayBuffer(8)),+ fetchText: vi.fn(async () => atlasDoc),+ resolveUrl: (p: string) => `http://test/${p}`,+ } as unknown as Backend,+ catalog: Catalog.empty(),+ module: { _malloc: vi.fn(() => 0), _free: vi.fn(), HEAPU8: new Uint8Array(1 << 16), GL: null, FS: null } as never,+ });+ assets.setAssetRefResolver((ref) => byUuid.get(ref) ?? ref);+ assets.getTextureLoader().setPixelDecoder(async () => ({+ width: 4, height: 4, pixels: new Uint8Array(64),+ }));+ return assets;+}++/** Load one pair the way a scene does, and hand back the era it produced. */+async function delivered(atlas = ATLAS_REF, manifest = shippedManifest()) {+ const assets = realm();+ const scope = new AssetScope(assets);+ const manager = new SpineManager({} as never, new Map());+ const info = await loadSpineAssets(+ null, shippedSource(manifest), manager, [{ skeleton: SKEL_REF, atlas }],+ undefined, { assets, scope },+ );+ return { era: info.get(spinePairKey(SKEL_REF, atlas))?.era, scope };+}++/** A core that declines everything and records what it was asked to draw. */+function offscreenCamera() {+ const state = { submits: 0 };+ const heap = new Uint32Array(64);+ const api = {+ renderer_submitSkeletalBatchByEntity: () => { state.submits++; },+ 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,+ };+ return { core: api as never, state };+}++beforeEach(() => { pool = createPoolFake(); });++describe('an author\'s promise reaches a running scene', () => {+ it('arrives certified at the era a uuid-referencing scene loads', async () => {+ const { era, scope } = await delivered();+ expect(era, 'the pair never loaded').toBeDefined();+ expect(era!.culling.kind,+ 'the contract did not survive metadata → manifest → source → era').toBe('certified');+ expect(era!.culling.kind === 'certified' && era!.culling.bounds)+ .toEqual({ minX: -200, minY: -100, maxX: 200, maxY: 600 });+ scope.releaseAll();+ });++ it('and costs nothing while no camera wants it', async () => {+ const { era, scope } = await delivered();+ const fake = fakeSpineModule();+ const runtime = new SpineRuntime('3.8', fake.module);+ runtime.loadEntity(1 as Entity, era!);+ runtime.observe(true);++ expect(runtime.mayDefer(1 as Entity),+ 'a delivered contract did not authorise a deferral').toBe(true);++ const camera = offscreenCamera();+ runtime.updateAll(1 / 60);+ runtime.extractAndSubmitMeshes(camera.core, {} as never);++ const m = runtime.metrics()!;+ expect(m.pose.logicalUpdates, 'the animation stopped').toBe(1);+ expect(m.pose.worldMaterializations, 'a world pose nobody wanted was resolved').toBe(0);+ expect(m.pose.meshExtractions).toBe(0);+ expect(camera.state.submits).toBe(0);+ expect(runtime.worldPoseDebt(), 'the frame did not skip the pose').toBe(1);+ runtime.dispose();+ scope.releaseAll();+ });++ it('is named by uuid the whole way, because that is how the delivery failed', () => {+ // Not decoration: the transport this replaced resolved paths and dropped+ // uuid refs on the floor, and every criterion it had used paths.+ expect(SKEL_REF.startsWith('@uuid:')).toBe(true);+ expect(AUTHORED_META.cullingAtlas.startsWith('@uuid:')).toBe(true);+ const shipped = shippedManifest().groups.main.assets[SKEL_UUID];+ expect(shipped.spineImport, 'the contract never reached the manifest').toBeDefined();+ expect(shipped.spineImport!.atlas,+ 'the shipped atlas is a ref spelling, not this build\'s identity').toBe(ATLAS_UUID);+ });+});++describe('the promise is about a pair, and stops at its edge', () => {+ it('another atlas inherits nothing', async () => {+ const { era, scope } = await delivered(OTHER_ATLAS_REF);+ expect(era, 'the pair never loaded').toBeDefined();+ expect(era!.culling.kind,+ 'a promise about one atlas authorised a skeleton drawn with another').toBe('unknown');+ scope.releaseAll();+ });++ it('a contract naming an atlas this build does not ship is not shipped either', () => {+ const orphan = [{+ uuid: SKEL_UUID, path: SKEL_PATH,+ importer: { ...AUTHORED_META, cullingAtlas: '@uuid:nothing-here' } as Record<string, unknown>,+ }];+ expect(shippedManifest(orphan).groups.main.assets[SKEL_UUID].spineImport,+ 'a promise about an absent asset shipped anyway').toBeUndefined();+ });++ it('half a contract is not a contract', () => {+ const keyOf = () => ATLAS_UUID;+ expect(spineManifestContractFrom({ cullingBounds: AUTHORED_META.cullingBounds }, keyOf),+ 'a rectangle with no atlas shipped as a promise').toBeUndefined();+ expect(spineManifestContractFrom({ cullingAtlas: ATLAS_REF }, keyOf)).toBeUndefined();+ expect(spineManifestContractFrom({+ cullingBounds: { x: 0, y: 0, width: 0, height: 0 }, cullingAtlas: ATLAS_REF,+ }, keyOf), 'a rectangle of no area shipped as a promise').toBeUndefined();+ });+});++describe('a realm that ships no contracts', () => {+ it('certifies nothing, and nothing may defer', async () => {+ const bare = [{ uuid: SKEL_UUID, path: SKEL_PATH, importer: { scale: 1 } as Record<string, unknown> },+ { uuid: ATLAS_UUID, path: ATLAS_PATH, importer: {} as Record<string, unknown> }];+ const { era, scope } = await delivered(ATLAS_REF, shippedManifest(bare));+ expect(era!.culling.kind).toBe('unknown');+ scope.releaseAll();+ });+});diff --git a/tools/check-spine-lifetimes.mjs b/tools/check-spine-lifetimes.mjsindex 472c6535e..c0823b945 100644--- a/tools/check-spine-lifetimes.mjs+++ b/tools/check-spine-lifetimes.mjs@@ -147,6 +147,54 @@ const INVARIANTS = [: `${holders.join(', ')} holds a SpineRuntime; entity binding is the manager's`;},},+ {+ rule: 'A culling contract reaches a runtime through the manifest that ships the asset, and through nothing else. It arrived through an AssetRegistry once, which nothing in any realm ever attached — so no contract authorised a single deferred pose, in any build, for as long as the feature existed.',+ proof: 'arrives certified at the era a uuid-referencing scene loads',+ holds: () => {+ const found = [];+ const walk = (dir) => {+ for (const entry of readdirSync(path.join(ROOT, dir), { withFileTypes: true })) {+ const rel = `${dir}/${entry.name}`;+ if (entry.isDirectory()) walk(rel);+ else if (entry.name.endsWith('.ts')) {+ const text = strip(read(rel));+ if (/projectSpineCertificates|setAssetRegistry/.test(text)) found.push(rel);+ }+ }+ };+ walk(SRC);+ return found.length === 0 ? null+ : `${found.join(', ')} revives the AssetRegistry contract transport`;+ },+ },+ {+ rule: 'The cook and the editor\'s play manifest write a contract through ONE function. Two writers is how "works in Play, not in the build" is born — and the promise a player never gets is the one nobody notices.',+ proof: 'is named by uuid the whole way, because that is how the delivery failed',+ holds: () => {+ const writers = ['pipeline/src/assets/addressableManifest.ts',+ 'desktop/src/project/ProjectStore.ts'];+ const missing = writers+ .filter((f) => existsSync(path.join(ROOT, f)))+ // A CALL, not a mention: an import the file no longer uses is+ // exactly how one writer quietly grew its own way of doing this.+ .filter((f) => !/spineManifestContractFrom\s*\(/.test(strip(read(f))));+ return missing.length === 0 ? null+ : `${missing.join(', ')} writes a spine contract its own way`;+ },+ },+ {+ rule: 'The delivery criterion may not manufacture the thing it is checking for. Handing it a certificate turns it back into what it replaced: a test green on both sides of a seam nobody crosses.',+ proof: 'and costs nothing while no camera wants it',+ holds: () => {+ const file = `${TESTS}/spine-contract-delivery.test.ts`;+ if (!existsSync(path.join(ROOT, file))) return 'the delivery criterion is gone';+ const text = strip(read(file));+ const injected = ['certifyBounds', 'setAssetRegistry']+ .filter((name) => new RegExp(`\\b${name}\\b`).test(text));+ return injected.length === 0 ? null+ : `the delivery criterion injects its own authority (${injected.join(', ')})`;+ },+ },];const titles = judgments();diff --git a/tools/lib/sourceRoots.mjs b/tools/lib/sourceRoots.mjsindex 66c95f4cf..1c308e6c7 100644--- a/tools/lib/sourceRoots.mjs+++ b/tools/lib/sourceRoots.mjs@@ -24,7 +24,12 @@ export function hasEditor() {function ls(cwd, args) {if (!args.length) return [];- return execFileSync('git', ['ls-files', ...args], { cwd, encoding: 'utf8' }).split('\n').filter(Boolean);+ const tracked = execFileSync('git', ['ls-files', ...args], { cwd, encoding: 'utf8' })+ .split('\n').filter(Boolean);+ // The index still lists a file deleted from the working tree until the+ // deletion is staged, and every caller goes on to READ what it is handed —+ // so a gate run mid-edit died on ENOENT instead of reporting a finding.+ return tracked.filter((rel) => existsSync(path.join(cwd, rel)));}/**