Merge pull request #432 from akashic-games/add-cross-fade

feat: クロスフェード機構を追加

Author: yu-ogi

CHANGELOG.md

@@ -1,5 +1,14 @@
 # ChangeLog
 
+## 3.9.2
+機能追加
+* `g.AudioUtil` を追加
+  * 音声のフェードイン・フェードアウト・クロスフェード等の機能を提供します。
+* `g.Game#onUpdate` を追加
+  * ティックの進行後 (`g.Scene#onUpdate` が発火した後) に発火します。
+* `g.Util#clamp()` を追加
+* `EasingFunction` `AudioTransitionContext` を追加
+
 ## 3.9.1
 * 早送り中に `g.AudioPlayContext` の再生を抑制するように
 

package-lock.json

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

package.json

@@ -0,0 +1,182 @@
+import type { AudioPlayContext } from "./AudioPlayContext";
+import type { Game } from "./Game";
+import { Util } from "./Util";
+
+/**
+ * イージング関数。
+ *
+ * @param t 経過時間
+ * @param b 開始位置
+ * @param c 差分
+ * @param d 所要時間
+ */
+export type EasingFunction = (t: number, b: number, c: number, d: number) => number;
+
+export type AudioTransitionContext = {
+	/**
+	 * 遷移を即座に完了する。
+	 * 音量は遷移完了後の値となる。
+	 */
+	complete: () => void;
+	/**
+	 * 遷移を取り消す。音量はこの関数を実行した時点での値となる。
+	 * @param revert 音量を遷移実行前まで戻すかどうか。省略時は `false` 。
+	 */
+	cancel: (revert?: boolean) => void;
+};
+
+/**
+ * linear のイージング関数。
+ */
+const linear: EasingFunction = (t: number, b: number, c: number, d: number) => (c * t) / d + b;
+
+/**
+ * Audio に関連するユーティリティ。
+ */
+export module AudioUtil {
+	/**
+	 * 音声をフェードインさせる。
+	 *
+	 * @param game 対象の `Game`。
+	 * @param context 対象の `AudioPlayContext` 。
+	 * @param duration フェードインの長さ (ms)。
+	 * @param to フェードイン後の音量。0 未満または 1 より大きい値を指定した場合の挙動は不定である。省略時は `1` 。
+	 * @param easing イージング関数。省略時は linear 。
+	 */
+	export function fadeIn(
+		game: Game,
+		context: AudioPlayContext,
+		duration: number,
+		to: number = 1,
+		easing: EasingFunction = linear
+	): AudioTransitionContext {
+		context.changeVolume(0);
+		context.play();
+		const { complete, cancel } = transitionVolume(game, context, duration, to, easing);
+
+		return {
+			complete: () => {
+				complete();
+			},
+			cancel: (revert: boolean = false) => {
+				cancel(revert);
+				if (revert) {
+					context.stop();
+				}
+			}
+		};
+	}
+
+	/**
+	 * 音声をフェードアウトさせる。
+	 *
+	 * @param game 対象の `Game`。
+	 * @param context 対象の `AudioPlayContext` 。
+	 * @param duration フェードアウトの長さ (ms)。
+	 * @param easing イージング関数。省略時は linear が指定される。
+	 */
+	export function fadeOut(
+		game: Game,
+		context: AudioPlayContext,
+		duration: number,
+		easing: EasingFunction = linear
+	): AudioTransitionContext {
+		const { complete, cancel } = transitionVolume(game, context, duration, 0, easing);
+
+		return {
+			complete: () => {
+				complete();
+				context.stop();
+			},
+			cancel: (revert: boolean = false) => {
+				cancel(revert);
+			}
+		};
+	}
+
+	/**
+	 * 二つの音声をクロスフェードさせる。
+	 *
+	 * @param game 対象の `Game`。
+	 * @param fadeInContext フェードイン対象の `AudioPlayContext` 。
+	 * @param fadeOutContext フェードアウト対象の `AudioPlayContext` 。
+	 * @param duration クロスフェードの長さ (ms)。
+	 * @param to クロスフェード後の音量。0 未満または 1 より大きい値を指定した場合の挙動は不定。省略時は `1` 。
+	 * @param easing イージング関数。フェードインとフェードアウトで共通であることに注意。省略時は linear が指定される。
+	 */
+	export function crossFade(
+		game: Game,
+		fadeInContext: AudioPlayContext,
+		fadeOutContext: AudioPlayContext,
+		duration: number,
+		to: number = 1,
+		easing: EasingFunction = linear
+	): AudioTransitionContext {
+		const fadeInFuncs = fadeIn(game, fadeInContext, duration, to, easing);
+		const fadeOutFuncs = fadeOut(game, fadeOutContext, duration, easing);
+
+		return {
+			complete: () => {
+				fadeInFuncs.complete();
+				fadeOutFuncs.complete();
+			},
+			cancel: (revert: boolean = false) => {
+				fadeInFuncs.cancel(revert);
+				fadeOutFuncs.cancel(revert);
+			}
+		};
+	}
+
+	/**
+	 * 音量を指定のイージングで遷移させる。
+	 *
+	 * @param game 対象の `Game`。
+	 * @param context 対象の `AudioPlayContext` 。
+	 * @param duration 遷移の長さ (ms)。
+	 * @param to 遷移後の音量。0 未満または 1 より大きい値を指定した場合の挙動は不定。
+	 * @param easing イージング関数。省略時は linear が指定される。
+	 */
+	export function transitionVolume(
+		game: Game,
+		context: AudioPlayContext,
+		duration: number,
+		to: number,
+		easing: EasingFunction = linear
+	): AudioTransitionContext {
+		const frame = 1000 / game.fps;
+		const from = context.volume;
+		let elapsed = 0;
+		context.changeVolume(Util.clamp(from, 0, 1));
+
+		const handler = (): boolean => {
+			elapsed += frame;
+			if (elapsed <= duration) {
+				const progress = easing(elapsed, from, to - from, duration);
+				context.changeVolume(Util.clamp(progress, 0, 1));
+				return false;
+			} else {
+				context.changeVolume(to);
+				return true;
+			}
+		};
+		const remove = (): void => {
+			if (game.onUpdate.contains(handler)) {
+				game.onUpdate.remove(handler);
+			}
+		};
+		game.onUpdate.add(handler);
+
+		return {
+			complete: () => {
+				remove();
+				context.changeVolume(to);
+			},
+			cancel: revert => {
+				remove();
+				if (revert) {
+					context.changeVolume(from);
+				}
+			}
+		};
+	}
+}

src/AudioUtil.ts

@@ -538,6 +538,11 @@ export class Game {
 	 */
 	skippingChanged: Trigger<boolean>;
 
+	/**
+	 * ティック消化後にfireされるTrigger。
+	 */
+	onUpdate: Trigger<void>;
+
 	/**
 	 * ゲームが早送りに状態にあるかどうか。
 	 *
@@ -924,6 +929,8 @@ export class Game {
 		this._onSceneChange.add(this._handleSceneChanged, this);
 		this._sceneChanged = this._onSceneChange;
 
+		this.onUpdate = new Trigger<void>();
+
 		this._initialScene = new Scene({
 			game: this,
 			assetIds: this._assetManager.globalAssetIds(),
@@ -1033,6 +1040,8 @@ export class Game {
 			if (advanceAge) ++this.age;
 		}
 
+		this.onUpdate.fire();
+
 		if (this._postTickTasks.length) {
 			this._flushPostTickTasks();
 			return scene !== this.scenes[this.scenes.length - 1];
@@ -1449,6 +1458,7 @@ export class Game {
 		this.onResized.removeAll();
 		this.onSkipChange.removeAll();
 		this.onSceneChange.removeAll();
+		this.onUpdate.removeAll();
 		this.handlerSet.removeAllEventFilters();
 
 		this.isSkipping = false;
@@ -1573,6 +1583,8 @@ export class Game {
 		this.onSkipChange = undefined!;
 		this.onSceneChange.destroy();
 		this.onSceneChange = undefined!;
+		this.onUpdate.destroy();
+		this.onUpdate = undefined!;
 		this.onSnapshotRequest.destroy();
 		this.onSnapshotRequest = undefined!;
 		this.join = undefined!;

src/Game.ts

@@ -71,6 +71,16 @@ export module Util {
 		return (s[0].toLowerCase() + s.slice(1).replace(/[A-Z]/g, (c: string) => "-" + c.toLowerCase())) as U;
 	}
 
+	/**
+	 * 数値を範囲内［min, max］に丸める
+	 * @param num 丸める値
+	 * @param min 値の下限
+	 * @param max 値の上限
+	 */
+	export function clamp(num: number, min: number, max: number): number {
+		return Math.min(Math.max(num, min), max);
+	}
+
 	/**
 	 * CompositeOperation を CompositeOperationString に読み替えるテーブル。
 	 * @deprecated 非推奨である。非推奨の機能との互換性のために存在する。ゲーム開発者が使用すべきではない。