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.

refactor(spine): a spine asset is a preparation, not a second lifecycle

esengine621b99fa70dd
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index a747bbc04..f7aec9635 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -776,6 +776,7 @@ ResourceDef<AssetsClass>
@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; }
+acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>
acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>
acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>
applyUpdate: (onProgress?: (loaded: number, total: number) => void) => Promise<ApplyUpdateResult>
@@ -792,7 +793,6 @@ getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
getRefCounter: () => AssetRefCounter | null
-getSpineLoader: () => SpineAssetLoader
getTexture: (ref: string) => TextureResult | undefined
getTextureLoader: () => TextureLoader
invalidate: (ref: string) => boolean
@@ -843,7 +843,6 @@ setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
-setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index f8eee5426..025c329da 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -776,6 +776,7 @@ ResourceDef<AssetsClass>
@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; }
+acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>
acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>
acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>
applyUpdate: (onProgress?: (loaded: number, total: number) => void) => Promise<ApplyUpdateResult>
@@ -792,7 +793,6 @@ getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
getRefCounter: () => AssetRefCounter | null
-getSpineLoader: () => SpineAssetLoader
getTexture: (ref: string) => TextureResult | undefined
getTextureLoader: () => TextureLoader
invalidate: (ref: string) => boolean
@@ -843,7 +843,6 @@ setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
-setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index c33fe45ae..c4fc23be7 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -771,6 +771,7 @@ ResourceDef<AssetsClass>
@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; }
+acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>
acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>
acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>
applyUpdate: (onProgress?: (loaded: number, total: number) => void) => Promise<ApplyUpdateResult>
@@ -787,7 +788,6 @@ getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
getRefCounter: () => AssetRefCounter | null
-getSpineLoader: () => SpineAssetLoader
getTexture: (ref: string) => TextureResult | undefined
getTextureLoader: () => TextureLoader
invalidate: (ref: string) => boolean
@@ -838,7 +838,6 @@ setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
-setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 21c2aac03..ace29816f 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -771,6 +771,7 @@ ResourceDef<AssetsClass>
@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; }
+acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>
acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>
acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>
applyUpdate: (onProgress?: (loaded: number, total: number) => void) => Promise<ApplyUpdateResult>
@@ -787,7 +788,6 @@ getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
getRefCounter: () => AssetRefCounter | null
-getSpineLoader: () => SpineAssetLoader
getTexture: (ref: string) => TextureResult | undefined
getTextureLoader: () => TextureLoader
invalidate: (ref: string) => boolean
@@ -838,7 +838,6 @@ setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
-setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 2a6c59184..78cf150f8 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -771,6 +771,7 @@ ResourceDef<AssetsClass>
@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; }
+acquireSpine: (skeletonRef: string, atlasRef?: string) => Promise<AssetLease<SpineResult>>
acquireTexture: (ref: string) => Promise<AssetLease<TextureResult>>
acquireTyped: <T>(type: string, ref: string) => Promise<AssetLease<T>>
applyUpdate: (onProgress?: (loaded: number, total: number) => void) => Promise<ApplyUpdateResult>
@@ -787,7 +788,6 @@ getAtlasFrame: (ref: string) => AtlasFrameInfo | null
getLoader: <T>(type: string) => AssetLoader<T> | undefined
getManifest: () => ManifestModel | null
getRefCounter: () => AssetRefCounter | null
-getSpineLoader: () => SpineAssetLoader
getTexture: (ref: string) => TextureResult | undefined
getTextureLoader: () => TextureLoader
invalidate: (ref: string) => boolean
@@ -838,7 +838,6 @@ setAssetRegistry: (registry: AssetRegistry) => void
setManifest: (manifest: AddressableManifest | ManifestModel | null) => void
setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
-setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.ts
index 2054d4478..06ed819bd 100644
--- a/sdk/src/asset/AssetLoader.ts
+++ b/sdk/src/asset/AssetLoader.ts
@@ -6,6 +6,7 @@ import type { RegistryEra } from './registryAssets';
import type { Catalog } from './Catalog';
import type { TextureHandle, FontHandle } from '../types';
import type { CppResourceManager } from '../wasm';
+import type { SpineAssetValue } from '../spine/prepareSpine';
export interface TextureResult {
handle: TextureHandle;
@@ -13,9 +14,12 @@ export interface TextureResult {
height: number;
}
-export interface SpineResult {
- skeletonHandle: number;
-}
+/**
+ * One spine PAIR: the two documents it is, and the atlas pages it holds. No
+ * native skeleton — that belongs to a runtime backend of a particular Spine
+ * version, is built from this, and dies with the entities posing it.
+ */
+export type SpineResult = SpineAssetValue;
export interface SpineLoadResult {
success: boolean;
@@ -135,12 +139,13 @@ export interface LoadContext {
): Promise<AssetLease<TextureResult>>;
/**
* Read another asset's content because it shapes what this one becomes — a
- * `.tsj` folded into a `.tmj`.
+ * `.tsj` folded into a `.tmj`. Takes the REF, not a build path: what is
+ * recorded is the identity an invalidation will name.
*
* Nothing is held; what is recorded is that this asset must be rebuilt when
* that content changes. A log setting read during a load is not one.
*/
- readSource?(path: string): Promise<string>;
+ readSource?(ref: string): Promise<string>;
/**
* Audio API for the owning app, resolved lazily so that
* AudioPlugin / AssetPlugin can be installed in either order.
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 73379497d..afae5aacb 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -25,6 +25,7 @@ import { RegistryAssetSlots, type RegistryAssetKind } from './registryAssets';
import { DependencyRecorder, isInvalidatable, rebuildPlan, type AssetIdentity,
type DependencyReceipt, type Preparation, type PreparedLoad } from './dependencies';
import { SpineAssetLoader } from './loaders/SpineAssetLoader';
+import { spinePairKey } from '../spine/prepareSpine';
import { MaterialAssetLoader } from './loaders/MaterialAssetLoader';
import { MeshAssetLoader } from './loaders/MeshAssetLoader';
import { nativeEngineApi, type EngineApi } from '../ecs/bridge/engineApi';
@@ -42,7 +43,6 @@ import { AnimatorControllerAssetLoader } from './loaders/AnimatorControllerAsset
import { BtAssetLoader } from './loaders/BtAssetLoader';
import { LocaleAssetLoader } from './loaders/LocaleAssetLoader';
import { JsonAssetLoader } from './loaders/JsonAssetLoader';
-import type { SpineModuleController } from '../spine/SpineController';
import { getComponentDefaults } from '../ecs/component';
import { getComponentAssetFieldDescriptors } from '../scene/scene';
import { discoverSceneAssets } from './discoverAssets';
@@ -238,11 +238,9 @@ const GROUP_ASSET_CHANNELS: Readonly<Record<string, GroupAssetChannel>> = {
displayable: true,
},
spine: {
- load: (a, path, b) => a.loadSpine(path).then((r) => { b.spine.set(path, r); }),
- // Skeletons bind to spawned entities and are owned by the
- // SpineAssetLoader / SpineManager lifecycle; releasing one here could
- // yank it out from under a live entity.
- release: null,
+ load: (a, path, b) => a.acquireSpine(path)
+ .then((l) => { b.scope.add(l); b.spine.set(path, l.value); }),
+ release: (a, path) => a.releaseTyped('spine', path),
displayable: true,
},
prefab: {
@@ -406,7 +404,7 @@ export class Assets {
this.setManifest(options.manifest ?? null);
this.textureLoader_ = new TextureLoader(options.module);
- this.spineLoader_ = new SpineAssetLoader(options.module);
+ this.spineLoader_ = new SpineAssetLoader();
this.registerBuiltinLoaders();
}
@@ -609,14 +607,38 @@ export class Assets {
if (handle !== 0) this.handleToPath_.set(`${kind}:${handle}`, path);
}
+ /** {@link acquireSpine} without the receipt, for a caller that will let the
+ * realm's teardown be its release. */
async loadSpine(skeletonRef: string, atlasRef?: string): Promise<SpineResult> {
- const skelPath = this.resolveLoadPath_(skeletonRef);
- const ctx = this.getLoadContext_();
- if (atlasRef) {
- const atlasPath = this.resolveLoadPath_(atlasRef);
- return this.spineLoader_.loadWithAtlas(skelPath, atlasPath, ctx);
+ return (await this.acquireSpine(skeletonRef, atlasRef)).value;
+ }
+
+ /**
+ * One spine PAIR — a skeleton and the atlas it is drawn with. The same
+ * skeleton with another atlas is another asset, which is why the receipt
+ * names the pair and not the skeleton's path.
+ */
+ async acquireSpine(skeletonRef: string, atlasRef?: string): Promise<AssetLease<SpineResult>> {
+ const skeleton = this.resolveLoadPath_(skeletonRef);
+ const atlas = this.spineAtlasOf_(skeleton, atlasRef);
+ const key = spinePairKey(skeleton, atlas);
+ const { value, lease } = await this.acquirePrepared_<SpineResult>(
+ 'spine', key, skeletonRef,
+ (ctx) => this.spineLoader_.prepare(skeleton, atlas, ctx),
+ );
+ return this.typedLease_('spine', lease, value);
+ }
+
+ /** The atlas of a pair the caller named only half of: a skeleton's atlas is
+ * a Catalog dependency, which is what a cook records for it. */
+ private spineAtlasOf_(skeleton: string, atlasRef?: string): string {
+ if (atlasRef) return this.resolveLoadPath_(atlasRef);
+ const deps = this.catalog.getDeps(skeleton);
+ if (deps.length === 0) {
+ throw new Error(`Spine skeleton has no atlas dependency: ${skeleton}. `
+ + 'Pass the atlas explicitly or configure Catalog deps.');
}
- return this.spineLoader_.load(skelPath, ctx);
+ return deps[0];
}
async loadMaterial(ref: string): Promise<MaterialResult> {
@@ -1274,13 +1296,16 @@ export class Assets {
'mesh', meshHandles);
pushAcquire(environmentPaths, p => this.acquireTyped<{ handle: number }>('environment', p),
'environment', environmentHandles);
- // The runtime scene loader owns spine as a two-phase load+apply through the
- // SpineManager (skeletons must bind to spawned entities); it opts out here so
- // spine page textures / virtual-FS writes aren't done twice.
+ // A pair, so not `pushAcquire` (which keys by one path); the receipt is
+ // the scene's exactly as every other one is. The runtime scene loader
+ // opts out: its second phase binds to entities that do not exist yet.
if (!options?.skipSpine) {
for (const pair of spinePairs) {
tasks.push(() =>
- this.loadSpine(pair.skeleton, pair.atlas).then(() => {}).catch(e => {
+ this.acquireSpine(pair.skeleton, pair.atlas).then((lease) => {
+ scope.add(lease);
+ releaseCallbacks.push(() => lease.release());
+ }).catch(e => {
log.warn('asset', `Failed to load spine: ${pair.skeleton}`, e);
recordFailure(pair.skeleton, 'spine', e);
}),
@@ -1595,7 +1620,9 @@ export class Assets {
* group channel table uses. Game code calls the named release* methods.
*/
releaseTyped(type: string, ref: string): void {
- const path = this.resolveLoadPath_(ref);
+ const path = type === 'spine'
+ ? spinePairKey(this.resolveLoadPath_(ref), this.spineAtlasOf_(this.resolveLoadPath_(ref)))
+ : this.resolveLoadPath_(ref);
const kind = this.registryKind_(type);
if (kind) {
this.registrySlots_.releaseByName(type, this.assetIdentity_(ref));
@@ -1948,7 +1975,6 @@ export class Assets {
evictTextureDimensions(value);
}
- this.spineLoader_.releaseAll();
this.materialLoader_?.releaseAll();
for (const cache of this.genericCache_.values()) {
@@ -1965,14 +1991,6 @@ export class Assets {
// Spine Controller
// =========================================================================
- setSpineController(controller: SpineModuleController): void {
- this.spineLoader_.setSpineController(controller);
- }
-
- getSpineLoader(): SpineAssetLoader {
- return this.spineLoader_;
- }
-
getTextureLoader(): TextureLoader {
return this.textureLoader_;
}
@@ -2149,14 +2167,26 @@ export class Assets {
if (!loader) {
throw new Error(`No loader registered for type: ${type}`);
}
- const path = this.resolveLoadPath_(ref);
if (!loader.load) {
throw new Error(`Loader for "${type}" publishes by name; acquire it through its slot`);
}
const load = loader.load.bind(loader);
+ const path = this.resolveLoadPath_(ref);
+ return this.acquirePrepared_<T>(type, path, ref, (ctx) => load(path, ctx));
+ }
+
+ /**
+ * One era of one handle-bound asset, under the KEY that identifies it — the
+ * path for everything whose identity is a path, and the PAIR for spine,
+ * whose skeleton with another atlas is another asset. One ownership
+ * algorithm, differing only in what it calls one asset.
+ */
+ private async acquirePrepared_<T>(
+ type: string, key: string, ref: string, prepare: (ctx: LoadContext) => Promise<T>,
+ ): Promise<{ value: T; lease: AssetRefLease<PreparedLoad<unknown>> }> {
const epoch = this.resetEpoch_;
- const era = await this.genericCacheFor_(type).getOrLoad(path, () =>
- this.prepared_(async (ctx) => ({ value: await load(path, ctx) as unknown })),
+ const era = await this.genericCacheFor_(type).getOrLoad(key, () =>
+ this.prepared_(async (ctx) => ({ value: await prepare(ctx) as unknown })),
);
// BEFORE acquiring, as with textures: a realm that let go while this
// loaded has drained the ledger this row would go in, so nothing would
@@ -2167,10 +2197,10 @@ export class Assets {
`Assets were released while "${ref}" was loading; it has no owner. Load it again.`,
);
}
- const lease = this.genericRefs_.acquire(`${type}:${path}`, era);
+ const lease = this.genericRefs_.acquire(`${type}:${key}`, era);
const result = era.value as T;
const handle = (result as { handle?: unknown } | null)?.handle;
- if (typeof handle === 'number' && handle !== 0) this.recordHandlePath_(type, handle, path);
+ if (typeof handle === 'number' && handle !== 0) this.recordHandlePath_(type, handle, key);
return { value: result, lease };
}
@@ -2346,9 +2376,12 @@ export class Assets {
const lease = await base.createOwnedTexture!(width, height, pixels, flipY);
return recorder.own(`composed:${lease.value.handle}`, lease);
},
- readSource: async (path) => {
- recorder.read(path);
- return base.loadText(path);
+ readSource: async (ref) => {
+ // The edge records what was ASKED for; where the build put
+ // those bytes is this door's business, as it is for a texture.
+ // A loader resolving first records an identity nothing names.
+ recorder.read(ref);
+ return base.loadText(this.catalog.getBuildPath(ref));
},
};
}
diff --git a/sdk/src/asset/loaders/SpineAssetLoader.ts b/sdk/src/asset/loaders/SpineAssetLoader.ts
index f95c10e3d..909710ec8 100644
--- a/sdk/src/asset/loaders/SpineAssetLoader.ts
+++ b/sdk/src/asset/loaders/SpineAssetLoader.ts
@@ -1,153 +1,58 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-import type { AssetLoader, LoadContext, SpineResult } from '../AssetLoader';
-import { requireResourceManager } from '../../wasm/resourceManager';
+/**
+ * @file SpineAssetLoader.ts
+ * @brief The asset half of spine: two documents read, atlas pages acquired.
+ *
+ * @details It makes nothing, so it destroys nothing. The pages are taken through
+ * the acquisition door, which is what records them as the era's — and
+ * the native skeleton they end up in belongs to a runtime backend, not
+ * here: it is per Spine version, per App, and dies with the entities
+ * posing it.
+ */
+import type { AssetLoader, LoadContext } from '../AssetLoader';
import { getAssetTypeEntry } from '../../assetTypes';
-import type { ESEngineModule } from '../../wasm';
-import type { SpineModuleController } from '../../spine/SpineController';
-import { parseSpineAtlasPages } from '../../spine/atlasPages';
-import { log } from '../../util/logger';
+import { prepareSpine, type SpineAssetValue, type SpineIO } from '../../spine/prepareSpine';
-export class SpineAssetLoader implements AssetLoader<SpineResult> {
+export class SpineAssetLoader implements AssetLoader<SpineAssetValue> {
readonly type = 'spine';
readonly extensions = ['.skel'];
- private module_: ESEngineModule | null;
- private spineController_: SpineModuleController | null = null;
- private loaded_ = new Set<string>();
- private virtualFSPaths_ = new Set<string>();
- private skeletonHandles_ = new Map<string, number>();
-
- constructor(module: ESEngineModule | null) {
- this.module_ = module;
- }
-
- setSpineController(controller: SpineModuleController): void {
- this.spineController_ = controller;
- }
-
- getSkeletonHandle(cacheKey: string): number | undefined {
- return this.skeletonHandles_.get(cacheKey);
- }
-
- isLoaded(cacheKey: string): boolean {
- return this.loaded_.has(cacheKey);
- }
-
- async load(skeletonPath: string, ctx: LoadContext): Promise<SpineResult> {
+ /** The pair a skeleton names on its own: its atlas is a Catalog dependency,
+ * which is what a cook records for it. */
+ async load(skeletonPath: string, ctx: LoadContext): Promise<SpineAssetValue> {
const deps = ctx.catalog.getDeps(skeletonPath);
const atlasPath = deps.length > 0 ? deps[0] : null;
if (!atlasPath) {
- throw new Error(`Spine skeleton has no atlas dependency: ${skeletonPath}. Pass atlas explicitly or configure Catalog deps.`);
+ throw new Error(`Spine skeleton has no atlas dependency: ${skeletonPath}. `
+ + 'Pass the atlas explicitly or configure Catalog deps.');
}
- return this.loadWithAtlas(skeletonPath, atlasPath, ctx);
+ return this.prepare(skeletonPath, atlasPath, ctx);
}
- async loadWithAtlas(skeletonPath: string, atlasPath: string, ctx: LoadContext): Promise<SpineResult> {
- const cacheKey = `${skeletonPath}:${atlasPath}`;
- if (this.loaded_.has(cacheKey)) {
- return { skeletonHandle: this.skeletonHandles_.get(cacheKey) ?? -1 };
- }
-
- const atlasContent = await ctx.loadText(ctx.catalog.getBuildPath(atlasPath));
- const texNames = parseSpineAtlasPages(atlasContent);
- const atlasDir = atlasPath.substring(0, atlasPath.lastIndexOf('/'));
- const rm = requireResourceManager();
-
- const texPromises = texNames.map(async (texName) => {
- const texPath = atlasDir ? `${atlasDir}/${texName}` : texName;
- try {
- const texResult = await ctx.loadTexture(texPath, false);
- rm.registerTextureWithPath(texResult.handle, texPath);
- return { name: texName, handle: texResult.handle, width: texResult.width, height: texResult.height };
- } catch (err) {
- log.warn('asset', `Failed to load texture: ${texPath}`, err);
- return null;
- }
- });
- const loadedTextures = (await Promise.all(texPromises)).filter(
- (t): t is { name: string; handle: number; width: number; height: number } => t !== null,
- );
-
- const skelBuildPath = ctx.catalog.getBuildPath(skeletonPath);
- const isBinary = getAssetTypeEntry(skeletonPath)?.contentType === 'binary';
- const skelData = isBinary
- ? new Uint8Array(await ctx.loadBinary(skelBuildPath))
- : await ctx.loadText(skelBuildPath);
-
- this.writeToVirtualFS(atlasPath, atlasContent);
- this.writeToVirtualFS(skeletonPath, skelData);
-
- this.loaded_.add(cacheKey);
-
- let skeletonHandle = -1;
- if (this.spineController_) {
- skeletonHandle = this.spineController_.loadSkeleton(skelData, atlasContent, isBinary);
- if (skeletonHandle >= 0) {
- const pageCount = this.spineController_.getAtlasPageCount(skeletonHandle);
- for (let i = 0; i < pageCount; i++) {
- const pageName = this.spineController_.getAtlasPageTextureName(skeletonHandle, i);
- const tex = loadedTextures.find(t => t.name === pageName);
- if (tex) {
- const glId = rm.getTextureGLId(tex.handle);
- this.spineController_.setAtlasPageTexture(
- skeletonHandle, i, glId, tex.width, tex.height,
- );
- }
- }
- this.skeletonHandles_.set(cacheKey, skeletonHandle);
- }
- }
-
- return { skeletonHandle };
- }
-
- unload(_asset: SpineResult): void {
- // Spine resources managed by SpineController lifecycle
- }
-
- releaseAll(): void {
- if (this.spineController_) {
- for (const handle of this.skeletonHandles_.values()) {
- this.spineController_.unloadSkeleton(handle);
- }
- }
- this.skeletonHandles_.clear();
- this.loaded_.clear();
- this.cleanupVirtualFS();
- }
-
- private writeToVirtualFS(virtualPath: string, data: string | Uint8Array): void {
- if (this.virtualFSPaths_.has(virtualPath)) return;
- const fs = this.module_?.FS;
- if (!fs) return;
-
- try {
- ensureVirtualDir(fs, virtualPath);
- fs.writeFile(virtualPath, data);
- this.virtualFSPaths_.add(virtualPath);
- } catch (e) {
- log.warn('asset', `Failed to write virtual FS: ${virtualPath}`, e);
- }
- }
-
- private cleanupVirtualFS(): void {
- const fs = this.module_?.FS;
- if (!fs) return;
- for (const path of this.virtualFSPaths_) {
- try { fs.unlink(path); } catch { /* already removed */ }
- }
- this.virtualFSPaths_.clear();
+ /** The pair as a caller named it — a component authors both fields. */
+ async prepare(skeletonRef: string, atlasRef: string, ctx: LoadContext): Promise<SpineAssetValue> {
+ return prepareSpine(spineIo(ctx, atlasRef), skeletonRef, atlasRef);
}
}
-function ensureVirtualDir(fs: any, virtualPath: string): void {
- const dir = virtualPath.substring(0, virtualPath.lastIndexOf('/'));
- if (!dir) return;
- const parts = dir.split('/').filter((p: string) => p);
- let currentPath = '';
- for (const part of parts) {
- currentPath += '/' + part;
- try { fs.mkdir(currentPath); } catch { /* already exists */ }
- }
+/** The asset layer as a spine transport: documents through the source door,
+ * pages through the acquisition door — so the era holds every page receipt. */
+function spineIo(ctx: LoadContext, atlasRef: string): SpineIO {
+ const dir = atlasRef.substring(0, atlasRef.lastIndexOf('/'));
+ return {
+ // Read, not loaded: what these bytes say decides what the asset becomes,
+ // which is exactly when a change to them must rebuild it.
+ text: (ref) => (ctx.readSource
+ ? ctx.readSource(ref)
+ : ctx.loadText(ctx.catalog.getBuildPath(ref))),
+ binary: (ref) => ctx.loadBinary(ctx.catalog.getBuildPath(ref)),
+ // flipY false: an atlas page's rows are a layout, and the atlas's
+ // coordinates are top-first.
+ page: async (path) => (await ctx.acquireTexture(path, false)).value,
+ // Named relative to where the atlas was AUTHORED; the acquisition
+ // resolves that through the manifest like any other ref.
+ pagePath: (name) => (dir ? `${dir}/${name}` : name),
+ isBinary: (ref) => getAssetTypeEntry(ref)?.contentType === 'binary',
+ };
}
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index e2ca14445..11610f5b8 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -41,7 +41,7 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
+ 'depends on it — load it through the app Assets channel.');
}
const mapData = await parseTmjWithExternals(JSON.parse(text), (source) =>
- readSource(ctx.catalog.getBuildPath(resolveTiledRef(path, source))));
+ readSource(resolveTiledRef(path, source)));
if (!mapData) {
throw new Error(`Failed to parse tilemap: ${path}`);
}
diff --git a/sdk/src/spine/loadSpineScene.ts b/sdk/src/spine/loadSpineScene.ts
index c313f4874..c77064e08 100644
--- a/sdk/src/spine/loadSpineScene.ts
+++ b/sdk/src/spine/loadSpineScene.ts
@@ -21,10 +21,9 @@ import type { Entity } from '../types';
import { getComponentSkeletalFieldDescriptor, type SceneData } from '../scene/scene';
import { discoverSceneAssets } from '../asset/discoverAssets';
import { getAssetTypeEntry } from '../assetTypes';
-import { requireResourceManager } from '../wasm/resourceManager';
import { log } from '../util/logger';
import { SpineManager, type SpineVersion } from './SpineManager';
-import { parseSpineAtlasPages } from './atlasPages';
+import { prepareSpine, spinePairKey, type SpineAssetValue, type SpineIO } from './prepareSpine';
import { createAtlasPageTexture, type RuntimeAssetSource } from '../runtime/runtimeAssets';
import type { BasisTranscoder } from '../asset/compressed';
@@ -62,12 +61,8 @@ export type TranscoderProvider = () => Promise<BasisTranscoder | null>;
/** The opaque C++ registry handle SpineManager.loadEntity expects (app.world.getCppRegistry()). */
type CppRegistry = Parameters<SpineManager['loadEntity']>[4];
-export interface SpineAssetInfo {
- version: SpineVersion | null;
- skelData: Uint8Array | string;
- atlasText: string;
- textures: Map<string, { glId: number; w: number; h: number }>;
-}
+/** One prepared pair, plus the runtime version its skeleton document names. */
+export type SpineAssetInfo = SpineAssetValue & { version: SpineVersion | null };
/**
* Phase 1 — fetch + decode each spine pair's skeleton/atlas/textures and detect
@@ -83,78 +78,60 @@ export async function loadSpineAssets(
transcoderProvider?: TranscoderProvider,
): Promise<Map<string, SpineAssetInfo>> {
const assetInfoMap = new Map<string, SpineAssetInfo>();
- const resolveRef = source.resolveRef ?? ((r: string) => r);
for (const pair of spinePairs) {
- const skelRef = pair.skeleton;
- const atlasRef = pair.atlas;
- const cacheKey = `${skelRef}:${atlasRef}`;
-
- // Resolve skeleton/atlas refs (uuid/manifest → build path); the derived
- // texPath below is already a path, so it is NOT re-resolved.
- const atlasPath = resolveRef(atlasRef);
-
try {
- const atlasContent = await source.backend.fetchText(atlasPath);
-
- const skelPath = resolveRef(skelRef);
- const isBinary = getAssetTypeEntry(skelPath)?.contentType === 'binary';
- const skelData: Uint8Array | string = isBinary
- ? new Uint8Array(await source.backend.fetchBinary(skelPath))
- : await source.backend.fetchText(skelPath);
-
+ const value = await prepareSpine(
+ hostSpineIo(module, source, pair.atlas, transcoderProvider),
+ pair.skeleton, pair.atlas,
+ );
const version = spineManager
- ? (typeof skelData === 'string'
- ? SpineManager.detectVersionJson(skelData)
- : SpineManager.detectVersion(skelData))
+ ? (typeof value.skelData === 'string'
+ ? SpineManager.detectVersionJson(value.skelData)
+ : SpineManager.detectVersion(value.skelData))
: null;
-
- const texNames = parseSpineAtlasPages(atlasContent);
- // Pages are named relative to the atlas's AUTHORED location, not its
- // staged one — a content-addressed build renamed the atlas to a hash
- // under assets/, so `atlasPath`'s directory is not where the pages were.
- // Recover the authored directory from the atlas's logical address, so
- // `<dir>/page.png` resolves through the manifest like every other ref.
- const atlasLogical = source.resolveAddress?.(atlasRef) ?? atlasPath;
- const atlasDir = atlasLogical.substring(0, atlasLogical.lastIndexOf('/'));
- const rm = requireResourceManager();
- const textures = new Map<string, { glId: number; w: number; h: number }>();
-
- for (const texName of texNames) {
- // No dir ⇒ the page name IS the path (never a leading-slash
- // "/page.png", which resolves to nothing) — matches SpineAssetLoader.
- const texPath = atlasDir ? atlasDir + '/' + texName : texName;
- try {
- // The atlas names its pages by AUTHORED filename; a cook may
- // have re-encoded (.ktx2) or content-addressed the staged
- // file, so the derived logical path resolves through the
- // manifest/catalog like every other fetch.
- const staged = resolveRef(texPath);
- const page = await createAtlasPageTexture(
- staged,
- (p) => source.backend.fetchBinary(p),
- (p) => source.decodePixels(p, false),
- transcoderProvider, module,
- );
- rm.registerTextureWithPath(page.handle, texPath);
- textures.set(texName, {
- glId: rm.getTextureGLId(page.handle),
- w: page.width,
- h: page.height,
- });
- } catch (err) {
- log.warn('runtime', `Failed to load texture: ${texPath}`, err);
- }
- }
-
- assetInfoMap.set(cacheKey, { version, skelData, atlasText: atlasContent, textures });
+ assetInfoMap.set(spinePairKey(pair.skeleton, pair.atlas), { ...value, version });
} catch (err) {
- log.warn('runtime', `Failed to load spine asset: skel=${skelRef} atlas=${atlasRef}`, err);
+ log.warn('runtime', `Failed to load spine asset: skel=${pair.skeleton} atlas=${pair.atlas}`, err);
}
}
return assetInfoMap;
}
+/**
+ * A host's own file access as a spine transport — the editor, and any target
+ * driving this loader without an asset layer. Same algorithm as the asset
+ * layer's; what differs is where the bytes come from and that a page taken here
+ * has no receipt, so the host's own teardown is what ends it.
+ */
+function hostSpineIo(
+ module: ESEngineModule | null,
+ source: RuntimeAssetSource,
+ atlasRef: string,
+ transcoderProvider?: TranscoderProvider,
+): SpineIO {
+ const resolveRef = source.resolveRef ?? ((r: string) => r);
+ // Pages are named relative to the atlas's AUTHORED location, not its staged
+ // one — a content-addressed build renamed the atlas to a hash under assets/,
+ // so the staged path's directory is not where the pages were.
+ const atlasLogical = source.resolveAddress?.(atlasRef) ?? resolveRef(atlasRef);
+ const dir = atlasLogical.substring(0, atlasLogical.lastIndexOf('/'));
+ return {
+ text: (ref) => source.backend.fetchText(resolveRef(ref)),
+ binary: (ref) => source.backend.fetchBinary(resolveRef(ref)),
+ page: (path) => createAtlasPageTexture(
+ resolveRef(path),
+ (p) => source.backend.fetchBinary(p),
+ (p) => source.decodePixels(p, false),
+ transcoderProvider, module,
+ ),
+ // No dir ⇒ the page name IS the path (never a leading-slash "/page.png",
+ // which resolves to nothing).
+ pagePath: (name) => (dir ? `${dir}/${name}` : name),
+ isBinary: (ref) => getAssetTypeEntry(resolveRef(ref))?.contentType === 'binary',
+ };
+}
+
/**
* Phase 2 — for each SpineAnimation entity, route its loaded asset to the
* SpineManager (every version loads its side-module backend) and apply the
@@ -185,7 +162,7 @@ export async function applySpineEntities(opts: {
const atlasRef = comp.data[spineDesc.atlasField] as string;
if (!skelRef || !atlasRef) continue;
- const info = assetInfo.get(`${skelRef}:${atlasRef}`);
+ const info = assetInfo.get(spinePairKey(skelRef, atlasRef));
if (!info || !info.version) continue;
const entity = entityMap.get(sceneEntity.id);
diff --git a/sdk/src/spine/prepareSpine.ts b/sdk/src/spine/prepareSpine.ts
new file mode 100644
index 000000000..fe6a08f7b
--- /dev/null
+++ b/sdk/src/spine/prepareSpine.ts
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file prepareSpine.ts
+ * @brief What one spine asset IS, and the one algorithm that produces it.
+ *
+ * @details A spine asset is a PAIR: a skeleton document and the atlas it is
+ * drawn with. The same skeleton with another atlas is another asset —
+ * the component authors both fields, so a scene can and does say so —
+ * which is why the pair, not the skeleton's path, is its identity.
+ *
+ * What a preparation produces is data: the two documents and the atlas
+ * pages it took. The native skeleton is NOT here. That object belongs
+ * to a runtime backend of a particular Spine version, is built from
+ * this, and dies with the entities using it — an asset layer that
+ * creates one owns something it cannot answer questions about.
+ *
+ * The transport differs by host — the asset layer's recording context,
+ * an editor's own file access — and the algorithm does not. Which pages
+ * the atlas names, where they live, what is read and what is acquired
+ * is decided once, here.
+ */
+import { requireResourceManager } from '../wasm/resourceManager';
+import { parseSpineAtlasPages } from './atlasPages';
+import { log } from '../util/logger';
+
+/** One atlas page, as the runtime needs it: a GL id and its size. */
+export interface SpinePage {
+ glId: number;
+ w: number;
+ h: number;
+}
+
+/** What a spine preparation produced. */
+export interface SpineAssetValue {
+ /** The skeleton document — bytes for `.skel`, text for `.json`. */
+ skelData: Uint8Array | string;
+ atlasText: string;
+ isBinary: boolean;
+ /** By the name the atlas gives each page. */
+ textures: Map<string, SpinePage>;
+}
+
+/**
+ * What a spine preparation needs from the world it runs in.
+ *
+ * `text`/`binary` READ: those bytes decide what this asset becomes and nothing
+ * holds them afterwards. `page` TAKES: whether a receipt comes back with it is
+ * the transport's business — the asset layer's records one.
+ */
+export interface SpineIO {
+ text(ref: string): Promise<string>;
+ binary(ref: string): Promise<ArrayBuffer>;
+ page(path: string): Promise<{ handle: number; width: number; height: number }>;
+ /** Where the page the atlas names `name` actually lives. */
+ pagePath(name: string): string;
+ /** Whether the skeleton document is bytes rather than text — the extension
+ * of where it actually IS, which a uuid ref does not carry. */
+ isBinary(ref: string): boolean;
+}
+
+/** The identity of a spine asset in one realm: the pair, in one string. */
+export function spinePairKey(skeleton: string, atlas: string): string {
+ return `${skeleton}:${atlas}`;
+}
+
+/**
+ * Prepare one spine pair. A page that fails to load is left out with a warning
+ * rather than failing the asset: a skeleton missing one page still poses, and
+ * the atlas naming a page the build dropped is the ordinary shape of it.
+ */
+export async function prepareSpine(
+ io: SpineIO, skeletonRef: string, atlasRef: string,
+): Promise<SpineAssetValue> {
+ const atlasText = await io.text(atlasRef);
+ const rm = requireResourceManager();
+ const textures = new Map<string, SpinePage>();
+
+ for (const name of parseSpineAtlasPages(atlasText)) {
+ const path = io.pagePath(name);
+ try {
+ const page = await io.page(path);
+ rm.registerTextureWithPath(page.handle, path);
+ textures.set(name, { glId: rm.getTextureGLId(page.handle), w: page.width, h: page.height });
+ } catch (e) {
+ log.warn('spine', `atlas page "${path}" did not load`, e);
+ }
+ }
+
+ const isBinary = io.isBinary(skeletonRef);
+ const skelData: Uint8Array | string = isBinary
+ ? new Uint8Array(await io.binary(skeletonRef))
+ : await io.text(skeletonRef);
+
+ return { skelData, atlasText, isBinary, textures };
+}
diff --git a/sdk/tests/asset-group-channel-parity.test.ts b/sdk/tests/asset-group-channel-parity.test.ts
index 0da06f774..f959e4bc7 100644
--- a/sdk/tests/asset-group-channel-parity.test.ts
+++ b/sdk/tests/asset-group-channel-parity.test.ts
@@ -59,9 +59,10 @@ const TYPES: Array<{
{ type: 'bitmap-font', loadMethod: 'acquireTyped', loadArg: 'font', releasesVia: 'font' },
{ type: 'prefab', loadMethod: 'acquireTyped', loadArg: 'prefab', releasesVia: 'prefab' },
{ type: 'audio', loadMethod: 'acquireTyped', loadArg: 'audio', releasesVia: 'audio' },
- // Skeletons bind to spawned entities and belong to the SpineManager
- // lifecycle; releasing one here could yank it from under a live entity.
- { type: 'spine', loadMethod: 'loadSpine', releasesVia: null },
+ // Nothing is special about spine any more: the bundle holds a receipt for
+ // the era it took, and gives back that one. What a live entity holds it
+ // holds through a receipt of its own.
+ { type: 'spine', loadMethod: 'acquireSpine', releasesVia: 'spine' },
];
function manifestWith(type: AddressableAssetType): AddressableManifest {
diff --git a/sdk/tests/spine-asset-generation.test.ts b/sdk/tests/spine-asset-generation.test.ts
new file mode 100644
index 000000000..52a903036
--- /dev/null
+++ b/sdk/tests/spine-asset-generation.test.ts
@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spine-asset-generation.test.ts
+ * @brief Spine is an asset like any other: a preparation that reads two
+ * documents and holds the pages it took.
+ *
+ * @details What it produces is data — the two documents and the pages it took —
+ * and its era owns the receipts. The native skeleton is a runtime
+ * backend's, built from this. So every rule the asset layer already
+ * follows applies to spine unchanged.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Assets } from '../src/asset/Assets';
+import { Catalog } from '../src/asset/Catalog';
+import type { Backend } from '../src/asset/Backend';
+
+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(),
+ liveTextures: () => live.size,
+ };
+}
+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);
+
+/** An atlas naming one page, in the shape a spine export writes. */
+const ATLAS = 'hero.png\nsize: 4,4\nformat: RGBA8888\nfilter: Linear,Linear\nrepeat: none\n';
+const OTHER_ATLAS = 'winter.png\nsize: 4,4\nformat: RGBA8888\n';
+
+function realm(docs: Record<string, string>, fail?: (url: string) => boolean): Assets {
+ const assets = Assets.create({
+ backend: {
+ fetchBinary: vi.fn(async (url: string) => {
+ if (fail?.(url)) throw new Error(`no bytes at ${url}`);
+ return new ArrayBuffer(8);
+ }),
+ fetchText: vi.fn(async (url: string) => {
+ const key = Object.keys(docs).find((k) => url.endsWith(k));
+ return key ? docs[key] : '{}';
+ }),
+ 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.getTextureLoader().setPixelDecoder(async () => ({
+ width: 4, height: 4, pixels: new Uint8Array(64),
+ }));
+ return assets;
+}
+
+describe('a spine asset is a preparation', () => {
+ beforeEach(() => { pool = createPoolFake(); });
+
+ it('the atlas pages are the era\'s, and go back with it', async () => {
+ const assets = realm({ 'hero.atlas': ATLAS });
+ const held = await assets.acquireSpine('spine/hero.skel', 'spine/hero.atlas');
+
+ expect(held.value.textures.size, 'the page the atlas names').toBe(1);
+ expect(pool.liveTextures()).toBe(1);
+
+ held.release();
+ expect(pool.liveTextures(), 'the page the preparation took').toBe(0);
+ });
+
+ it('the documents it read are source edges, the page an owned one', async () => {
+ const assets = realm({ 'hero.atlas': ATLAS });
+ await assets.acquireSpine('spine/hero.skel', 'spine/hero.atlas');
+
+ const edges = assets.dependenciesOf('spine', 'spine/hero.skel:spine/hero.atlas');
+ expect(edges).toContainEqual({ kind: 'source', path: 'spine/hero.atlas' });
+ expect(edges).toContainEqual({ kind: 'owned', type: 'texture', path: 'spine/hero.png' });
+ });
+
+ it('a preparation that fails keeps no page', async () => {
+ // The pages are taken BEFORE the skeleton document is read, so a
+ // failure there is the window where they have no owner yet.
+ const assets = realm({ 'hero.atlas': ATLAS }, (url) => url.endsWith('.skel'));
+
+ await expect(assets.acquireSpine('spine/hero.skel', 'spine/hero.atlas'))
+ .rejects.toThrow(/no bytes/);
+
+ expect(pool.liveTextures(), 'the pages the failed preparation took').toBe(0);
+ });
+
+ it('the same skeleton with another atlas is another asset', async () => {
+ // The pair is the identity: a component authors both fields, so a scene
+ // can say so, and one era for both would draw the wrong pages.
+ const assets = realm({ 'hero.atlas': ATLAS, 'winter.atlas': OTHER_ATLAS });
+
+ const summer = await assets.acquireSpine('spine/hero.skel', 'spine/hero.atlas');
+ const winter = await assets.acquireSpine('spine/hero.skel', 'spine/winter.atlas');
+
+ expect([...summer.value.textures.keys()]).toEqual(['hero.png']);
+ expect([...winter.value.textures.keys()]).toEqual(['winter.png']);
+ expect(pool.liveTextures(), 'one page each').toBe(2);
+ });
+
+ it('two holders of one pair share the era', async () => {
+ const assets = realm({ 'hero.atlas': ATLAS });
+ const first = await assets.acquireSpine('spine/hero.skel', 'spine/hero.atlas');
+ const second = await assets.acquireSpine('spine/hero.skel', 'spine/hero.atlas');
+
+ expect(pool.liveTextures(), 'the page was uploaded twice').toBe(1);
+ expect(second.generation, 'two eras for one unchanged pair').toBe(first.generation);
+
+ first.release();
+ expect(pool.liveTextures(), 'released while a holder was still using it').toBe(1);
+ second.release();
+ expect(pool.liveTextures()).toBe(0);
+ });
+});