Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(spine): a culling contract reaches a runtime, for the first time

esengine23e334ee078b
diff --git a/desktop b/desktop
index d6d344bf0..e5075c1df 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit d6d344bf0cf0b2fbdd74715f4d5605d7dee156a0
+Subproject commit e5075c1dfc4c3572ef7d96fa21cbbebacaffe322
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.ts
index 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.ts
index 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 fields
diff --git a/sdk/etc/dragonbones.api.md b/sdk/etc/dragonbones.api.md
index 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[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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; } | undefined
path: string
size: number
+spineImport: SpineManifestContract | undefined
textureImport: ParsedTextureImportSettings | undefined
type: 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 | null
getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
@@ -819,7 +819,6 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
-projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -840,12 +839,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => void
restorePersistedUpdate: (key: string) => boolean
reuploadTexturesAfterDeviceLoss: () => Promise<number>
setAssetRefResolver: (resolver: AssetRefResolver) => void
-setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
-spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
@@ -4444,6 +4441,7 @@ remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefined
static empty: () => ManifestModel
static fromJson: (manifest: AddressableManifest) => ManifestModel
@@ -5148,6 +5146,7 @@ catalog: Catalog | undefined
manifest: AddressableManifest
model: ManifestModel
resolvePath: (ref: string) => string
+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImport: (ref: string) => ParsedTextureImportSettings | undefined
```
@@ -6645,6 +6644,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
@@ -7395,6 +7395,20 @@ timeScale: number
setAnimation: (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 | undefined
success: 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): SideModuleId
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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; } | undefined
path: string
size: number
+spineImport: SpineManifestContract | undefined
textureImport: ParsedTextureImportSettings | undefined
type: 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 | null
getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
@@ -819,7 +819,6 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
-projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -840,12 +839,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => void
restorePersistedUpdate: (key: string) => boolean
reuploadTexturesAfterDeviceLoss: () => Promise<number>
setAssetRefResolver: (resolver: AssetRefResolver) => void
-setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
-spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
@@ -4452,6 +4449,7 @@ remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefined
static empty: () => ManifestModel
static fromJson: (manifest: AddressableManifest) => ManifestModel
@@ -5331,6 +5329,7 @@ catalog: Catalog | undefined
manifest: AddressableManifest
model: ManifestModel
resolvePath: (ref: string) => string
+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImport: (ref: string) => ParsedTextureImportSettings | undefined
```
@@ -6838,6 +6837,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
@@ -7588,6 +7588,20 @@ timeScale: number
setAnimation: (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 | undefined
success: 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): SideModuleId
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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; } | undefined
path: string
size: number
+spineImport: SpineManifestContract | undefined
textureImport: ParsedTextureImportSettings | undefined
type: 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 | null
getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
@@ -814,7 +814,6 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
-projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -835,12 +834,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => void
restorePersistedUpdate: (key: string) => boolean
reuploadTexturesAfterDeviceLoss: () => Promise<number>
setAssetRefResolver: (resolver: AssetRefResolver) => void
-setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
-spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
@@ -4439,6 +4436,7 @@ remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefined
static empty: () => ManifestModel
static fromJson: (manifest: AddressableManifest) => ManifestModel
@@ -5143,6 +5141,7 @@ catalog: Catalog | undefined
manifest: AddressableManifest
model: ManifestModel
resolvePath: (ref: string) => string
+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImport: (ref: string) => ParsedTextureImportSettings | undefined
```
@@ -6640,6 +6639,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
@@ -7390,6 +7390,20 @@ timeScale: number
setAnimation: (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 | undefined
success: 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): SideModuleId
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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; } | undefined
path: string
size: number
+spineImport: SpineManifestContract | undefined
textureImport: ParsedTextureImportSettings | undefined
type: 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 | null
getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
@@ -814,7 +814,6 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
-projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -835,12 +834,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => void
restorePersistedUpdate: (key: string) => boolean
reuploadTexturesAfterDeviceLoss: () => Promise<number>
setAssetRefResolver: (resolver: AssetRefResolver) => void
-setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
-spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
@@ -4439,6 +4436,7 @@ remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefined
static empty: () => ManifestModel
static fromJson: (manifest: AddressableManifest) => ManifestModel
@@ -5389,6 +5387,7 @@ catalog: Catalog | undefined
manifest: AddressableManifest
model: ManifestModel
resolvePath: (ref: string) => string
+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImport: (ref: string) => ParsedTextureImportSettings | undefined
```
@@ -6886,6 +6885,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
@@ -7636,6 +7636,20 @@ timeScale: number
setAnimation: (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 | undefined
success: 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): SideModuleId
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 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[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((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.md
index 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; } | undefined
path: string
size: number
+spineImport: SpineManifestContract | undefined
textureImport: ParsedTextureImportSettings | undefined
type: 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 | null
getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
@@ -814,7 +814,6 @@ onInvalidate: (listener: InvalidateListener) => () => void
pathForHandle: (kind: string, handle: number) => string | null
preload: (refs: ReadonlyArray<string>, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; }) => Promise<{ failed: MissingAsset[]; }>
preloadSceneAssets: (sceneData: SceneData, onProgress?: (loaded: number, total: number) => void, options?: { readonly maxConcurrent?: number; readonly skipSpine?: boolean; }) => Promise<SceneAssetResult>
-projectSpineCertificates: () => void
recoverFromDeviceLoss: () => Promise<boolean>
register: <T>(loader: AssetLoader<T>) => void
releaseAll: () => void
@@ -835,12 +834,10 @@ resolveSceneAssetPaths: (sceneData: SceneData, result: SceneAssetResult) => void
restorePersistedUpdate: (key: string) => boolean
reuploadTexturesAfterDeviceLoss: () => Promise<number>
setAssetRefResolver: (resolver: AssetRefResolver) => void
-setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
-spineCertificates: SpineCertificates
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
@@ -4446,6 +4443,7 @@ remoteAssetIdentity: (ref: string) => string | null
remoteAssetPath: (ref: string) => string | null
resolvePath: (ref: string, normalize?: (ref: string) => string) => string
revision: () => string | null
+spineCullingLookup: () => (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImportLookup: () => (ref: string) => ParsedTextureImportSettings | undefined
static empty: () => ManifestModel
static fromJson: (manifest: AddressableManifest) => ManifestModel
@@ -5150,6 +5148,7 @@ catalog: Catalog | undefined
manifest: AddressableManifest
model: ManifestModel
resolvePath: (ref: string) => string
+spineCulling: (skeleton: string, atlas: string) => SpineCullingRect | undefined
textureImport: (ref: string) => ParsedTextureImportSettings | undefined
```
@@ -6647,6 +6646,7 @@ decodePixels: (path: string, flip: boolean) => Promise<{ width: number; height:
listAssetPaths: (() => string[]) | undefined
resolveAddress: ((ref: string) => string | null) | undefined
resolveRef: ((ref: string) => string) | undefined
+spineCulling: ((skeleton: string, atlas: string) => { x: number; y: number; width: number; height: number; } | undefined) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
@@ -7397,6 +7397,20 @@ timeScale: number
setAnimation: (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 | undefined
success: 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): SideModuleId
diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.ts
index 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 Team
import 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/AddressableMan
import { 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.ts
index 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.ts
index 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.ts
index 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 the
diff --git a/sdk/src/spine/index.ts b/sdk/src/spine/index.ts
index 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.ts
index 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/runt
import 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
index 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.mjs
index 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)));
}
/**