Merge pull request #482 from akashic-games/support-request-asset-fallback

feat: `g.Scene#requestAssets()` で対象のアセットのロード失敗時に callback 経由でエラーを通知するインタフェースを追加

Author: yu-ogi

CHANGELOG.md

@@ -1,5 +1,8 @@
 # ChangeLog
 
+## 3.16.5
+* `g.Scene#requestAssets()` で対象のアセットのロード失敗時に `callback` 経由でエラーを通知するインタフェースを追加
+
 ## 3.16.4
 不具合修正
  * `require()` で末尾の "index" や "index.js" を省略する表記としない表記を混在させた時、スクリプトが複数回評価される問題を修正

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@akashic/akashic-engine",
-  "version": "3.16.4",
+  "version": "3.16.5",
   "description": "The core library of Akashic Engine",
   "main": "index.js",
   "dependencies": {

package.json

@@ -64,6 +64,11 @@ export interface AssetHolderParameterObject<UserData> {
 	 * このインスタンスに紐づけるユーザ定義データ。
 	 */
 	userData: UserData | null;
+
+	/**
+	 * エラーが発生したか否かに関わらず常に `handlerSet.handleFinish` を実行するか。
+	 */
+	alwaysNotifyFinish?: boolean;
 }
 
 /**
@@ -108,6 +113,16 @@ export class AssetHolder<UserData> {
 	 */
 	_requested: boolean;
 
+	/**
+	 * @private
+	 */
+	_alwaysNotifyFinish: boolean;
+
+	/**
+	 * @private
+	 */
+	_failureAssetIds: (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[];
+
 	constructor(param: AssetHolderParameterObject<UserData>) {
 		const assetManager = param.assetManager;
 		const assetIds = param.assetIds ? param.assetIds.concat() : [];
@@ -120,6 +135,8 @@ export class AssetHolder<UserData> {
 		this._assets = [];
 		this._handlerSet = param.handlerSet;
 		this._requested = false;
+		this._alwaysNotifyFinish = !!param.alwaysNotifyFinish;
+		this._failureAssetIds = [];
 	}
 
 	request(): boolean {
@@ -138,6 +155,7 @@ export class AssetHolder<UserData> {
 		this.userData = undefined!;
 		this._handlerSet = undefined!;
 		this._assetIds = undefined!;
+		this._failureAssetIds = undefined!;
 		this._requested = false;
 	}
 
@@ -165,6 +183,10 @@ export class AssetHolder<UserData> {
 			// game.json に定義されていればゲームを止める。それ以外 (DynamicAsset) では続行。
 			if (this._assetManager.configuration[asset.id]) {
 				hs.handleFinish.call(hs.owner, this, false);
+			} else if (this._alwaysNotifyFinish) {
+				const assetConf = this._peekAssetConfFromAssetId(asset.id);
+				this._failureAssetIds.push(assetConf);
+				this._decrementWaitingAssetCount();
 			}
 		}
 	}
@@ -179,10 +201,38 @@ export class AssetHolder<UserData> {
 		hs.handleLoad.call(hs.owner, asset);
 		this._assets.push(asset);
 
+		this._decrementWaitingAssetCount();
+	}
+
+	/**
+	 * @private
+	 */
+	_decrementWaitingAssetCount(): void {
 		--this.waitingAssetsCount;
 		if (this.waitingAssetsCount > 0) return;
 		if (this.waitingAssetsCount < 0) throw ExceptionFactory.createAssertionError("AssetHolder#_onAssetLoad: broken waitingAssetsCount");
 
+		const hs = this._handlerSet;
 		hs.handleFinish.call(hs.owner, this, true);
 	}
+
+	/**
+	 * @private
+	 */
+	_getFailureAssetIds(): (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[] {
+		return this._failureAssetIds;
+	}
+
+	/**
+	 * @private
+	 */
+	_peekAssetConfFromAssetId(id: string): string | DynamicAssetConfiguration | AssetGenerationConfiguration {
+		for (const assetConf of this._assetIds) {
+			const assetId = typeof assetConf === "string" ? assetConf : assetConf.id;
+			if (id === assetId) {
+				return assetConf;
+			}
+		}
+		throw ExceptionFactory.createAssertionError(`AssetHolder#_peekAssetConfFromAssetId: could not peek the asset: ${id}`);
+	}
 }

src/AssetHolder.ts

@@ -1,4 +1,5 @@
 import type { AssertionError, AssetLoadError, TypeMismatchError } from "@akashic/pdi-types";
+import type { RequestAssetDetail, RequestAssetLoadError } from "./errors";
 
 /**
  * 例外生成ファクトリ。
@@ -49,4 +50,12 @@ export module ExceptionFactory {
 		e.retriable = retriable;
 		return e;
 	}
+
+	export function createRequestAssetLoadError(message: string, detail: RequestAssetDetail, cause?: any): RequestAssetLoadError {
+		const e = new Error(message) as RequestAssetLoadError;
+		e.name = "RequestAssetLoadError";
+		e.detail = detail;
+		e.cause = cause;
+		return e;
+	}
 }

src/ExceptionFactory.ts

@@ -8,6 +8,7 @@ import type { Camera } from "./Camera";
 import { Camera2D } from "./Camera2D";
 import type { DynamicAssetConfiguration } from "./DynamicAssetConfiguration";
 import type { E, PointDownEvent, PointMoveEvent, PointSource, PointUpEvent } from "./entities/E";
+import type { RequestAssetLoadError } from "./errors";
 import type { MessageEvent, OperationEvent } from "./Event";
 import { ExceptionFactory } from "./ExceptionFactory";
 import type { Game } from "./Game";
@@ -17,7 +18,20 @@ import type { Timer } from "./Timer";
 import type { TimerIdentifier } from "./TimerManager";
 import { TimerManager } from "./TimerManager";
 
-export type SceneRequestAssetHandler = () => void;
+export type SceneRequestAssetHandler = (error?: RequestAssetLoadError) => void;
+
+/**
+ * `Scene#requestAsset` の引数に渡すことができるパラメータ。
+ */
+export interface SceneRequestAssetsParameterObject {
+	assetIds: (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[];
+
+	/**
+	 * アセットの読込みに失敗した際にコールバックを実行するかどうか。
+	 * @default false
+	 */
+	notifyErrorOnCallback?: boolean;
+}
 
 /**
  * `Scene` のコンストラクタに渡すことができるパラメータ。
@@ -792,7 +806,7 @@ export class Scene {
 	}
 
 	requestAssets(
-		assetIds: (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[],
+		assetIdsOrConf: (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[] | SceneRequestAssetsParameterObject,
 		handler: SceneRequestAssetHandler
 	): void {
 		if (this._loadingState !== "ready-fired" && this._loadingState !== "loaded-fired") {
@@ -801,9 +815,20 @@ export class Scene {
 			throw ExceptionFactory.createAssertionError("Scene#requestAssets(): can be called after loaded.");
 		}
 
+		let assetIds: (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[];
+		let alwaysNotifyFinish: boolean;
+		if (Array.isArray(assetIdsOrConf)) {
+			assetIds = assetIdsOrConf;
+			alwaysNotifyFinish = false;
+		} else {
+			assetIds = assetIdsOrConf.assetIds;
+			alwaysNotifyFinish = !!assetIdsOrConf.notifyErrorOnCallback;
+		}
+
 		const holder = new AssetHolder<SceneRequestAssetHandler>({
 			assetManager: this.game._assetManager,
-			assetIds: assetIds,
+			assetIds,
+			alwaysNotifyFinish,
 			handlerSet: {
 				owner: this,
 				handleLoad: this._handleSceneAssetLoad,
@@ -812,7 +837,19 @@ export class Scene {
 			},
 			userData: () => {
 				// 不要なクロージャは避けたいが生存チェックのため不可避
-				if (!this.destroyed()) handler();
+				if (!this.destroyed()) {
+					const failureAssetIds = holder._getFailureAssetIds();
+					if (failureAssetIds.length) {
+						// このパスに入るのは AssetHolder の alwaysNotifyFinish フラグを真にした時のみであることに注意
+						const error = ExceptionFactory.createRequestAssetLoadError(
+							`Scene#requestAssets(): failed to load the asset. refer to the 'detail' property for more information.`,
+							{ failureAssetIds }
+						);
+						handler(error);
+					} else {
+						handler();
+					}
+				}
 			}
 		});
 		this._assetHolders.push(holder);

src/Scene.ts

@@ -1,5 +1,5 @@
 import { Trigger } from "@akashic/trigger";
-import type { AssetConfiguration, SceneStateString } from "..";
+import type { AssetConfiguration, DynamicAssetConfiguration, SceneStateString } from "..";
 import { AssetManager, E, Scene } from "..";
 import { customMatchers, Game, skeletonRuntime, ImageAsset, AudioAsset } from "./helpers";
 
@@ -374,6 +374,70 @@ describe("test Scene", () => {
 		game._startLoadingGlobalAssets();
 	});
 
+	it("loads assets dynamically - notifying error through the callback", done => {
+		const game = new Game({
+			width: 320,
+			height: 320,
+			main: "",
+			assets: {}
+		});
+
+		game._onLoad.add(() => {
+			const scene = new Scene({
+				game: game
+			});
+			scene.onLoad.add(() => {
+				let loaded = false;
+
+				const assetIds: DynamicAssetConfiguration[] = [
+					{
+						id: "unregistered-asset-1",
+						type: "audio",
+						duration: 450,
+						systemId: "sound",
+						uri: "http://example.com/assets/audio/foo"
+					},
+					{
+						id: "unregistered-asset-2",
+						type: "audio",
+						duration: 120,
+						systemId: "sound",
+						uri: "http://example.com/assets/audio/baz"
+					}
+				];
+
+				game.resourceFactory.withNecessaryRetryCount(-1, () => {
+					scene.requestAssets(
+						{
+							assetIds,
+							notifyErrorOnCallback: true
+						},
+						error => {
+							loaded = true;
+							expect(error!.name).toBe("RequestAssetLoadError");
+							expect(error!.detail).toEqual({
+								failureAssetIds: assetIds
+							});
+							done();
+						}
+					);
+
+					// Scene#requestAssets() のハンドラ呼び出しは Game#tick() に同期しており、実ロードの完了後に tick() が来るまで遅延される。
+					// テスト上は tick() を呼び出さないので、 _flushPostTickTasks() を呼び続けることで模擬する。
+					function flushUntilLoaded(): void {
+						if (loaded) return;
+						game._flushPostTickTasks();
+						setTimeout(flushUntilLoaded, 10);
+					}
+					flushUntilLoaded();
+				});
+			});
+			game.pushScene(scene);
+			game._flushPostTickTasks();
+		});
+		game._startLoadingGlobalAssets();
+	});
+
 	it("does not crash even if destroyed while loading assets", done => {
 		const game = new Game({
 			width: 320,

src/__tests__/SceneSpec.ts

@@ -0,0 +1,16 @@
+/**
+ * akashic-engine 独自のエラー型定義。
+ */
+
+import type { ErrorLike } from "@akashic/pdi-types";
+import type { AssetGenerationConfiguration } from "./AssetGenerationConfiguration";
+import type { DynamicAssetConfiguration } from "./DynamicAssetConfiguration";
+
+export interface RequestAssetDetail {
+	failureAssetIds: (string | DynamicAssetConfiguration | AssetGenerationConfiguration)[];
+}
+
+export interface RequestAssetLoadError extends ErrorLike {
+	name: "RequestAssetLoadError";
+	detail: RequestAssetDetail;
+}