【Cocos Creator】アタッチするだけ！VolumeControl (音量調整)の実装方法【TypeScript】

【Cocos Creator 3.8】VolumeControl の実装：アタッチするだけでスライダー操作から AudioServer の音量(dB)を制御する汎用スクリプト

このガイドでは、Slider コンポーネントにアタッチするだけで、スライダーの値に応じて AudioServer の音量(dB) を自動制御する「VolumeControl」コンポーネントを実装します。
ゲーム全体のマスターボリュームや BGM・SE の音量調整 UI を、シーン内に専用マネージャーを置かずに、このスクリプトだけで完結させたいときに役立ちます。

コンポーネントの設計方針

要件整理

• このコンポーネントは Slider を持つノードにアタッチして使う。
• Slider の値が変化したとき、AudioServer の音量(dB) を更新する。
• 外部の GameManager やシングルトンには一切依存せず、このスクリプト単体で完結させる。
• 必要な設定はすべてインスペクタから行えるようにする。
• Slider の値は通常 0〜1 の範囲なので、0〜1 の値を任意の dB 範囲にマッピングして AudioServer に反映する。
• 必要なコンポーネント（Slider）が見つからない場合は、エラーログを出して防御的に動作する。

AudioServer について

Cocos Creator 3.8 では、AudioServer（audio 名前空間など）を通じてグローバルな音量を制御できます。
本記事では、マスターボリュームを想定した実装例として、

• Slider の値 0.0 → 最小音量（例: -40dB）
• Slider の値 1.0 → 最大音量（例: 0dB）

となるように線形マッピングした値を AudioServer に設定する設計にします。
（実際に利用する API 名はプロジェクトの AudioServer 実装に合わせて書き換えてください。ここではサンプルとして AudioServer.setMasterVolumeDb(dbValue) のような呼び出しを想定したダミー実装をコメントで示します。）

インスペクタで設定可能なプロパティ

VolumeControl コンポーネントに用意するプロパティと役割は以下の通りです。

• minDb: number
  • スライダー値が 0.0 のときに適用する音量(dB)。
  • 例: -40（かなり小さい音量、ほぼ無音に近い）
• maxDb: number
  • スライダー値が 1.0 のときに適用する音量(dB)。
  • 例: 0（基準音量）
• applyOnLoad: boolean
  • true の場合、コンポーネントの start 時に、現在の Slider 値から AudioServer の音量を一度反映する。
  • シーン開始時にスライダーの初期位置を反映したい場合に有効。
• logDebug: boolean
  • 有効にすると、スライダー操作時に計算された dB 値をログ出力する。
  • 調整時のデバッグ・確認用。リリース時は false 推奨。

また、コンポーネントはアタッチされたノードから Slider コンポーネントを自動取得します。
見つからない場合は console.error で警告し、イベント登録や音量変更処理はスキップします。

TypeScriptコードの実装

以下が VolumeControl コンポーネントの完全な実装コードです。

import { _decorator, Component, Slider, log, error, clamp01 } from 'cc';
const { ccclass, property } = _decorator;

/**
 * VolumeControl
 * 
 * このコンポーネントを Slider を持つノードにアタッチすると、
 * Slider の value (0.0〜1.0) に応じて AudioServer の音量(dB)を変更します。
 * 
 * 注意:
 * - 実際の AudioServer への適用部分は、プロジェクトの AudioServer 実装に
 *   合わせて書き換えてください（下記の TODO コメント参照）。
 */
@ccclass('VolumeControl')
export class VolumeControl extends Component {

    @property({
        tooltip: 'スライダー値が 0.0 のときに適用する音量(dB)。\n例: -40 でほぼ無音。'
    })
    public minDb: number = -40.0;

    @property({
        tooltip: 'スライダー値が 1.0 のときに適用する音量(dB)。\n通常は 0dB を基準とする。'
    })
    public maxDb: number = 0.0;

    @property({
        tooltip: 'true の場合、start 時に現在の Slider 値から一度だけ音量を反映します。'
    })
    public applyOnLoad: boolean = true;

    @property({
        tooltip: 'true の場合、スライダー操作時に計算された dB 値をログ出力します。'
    })
    public logDebug: boolean = false;

    // 内部参照：同じノードにアタッチされた Slider コンポーネント
    private _slider: Slider | null = null;

    onLoad() {
        // 必要な Slider コンポーネントを取得
        this._slider = this.getComponent(Slider);

        if (!this._slider) {
            error('[VolumeControl] Slider コンポーネントが見つかりません。' +
                  'このスクリプトは Slider を持つノードにアタッチしてください。');
            return;
        }

        // スライダー値変更時のコールバック登録
        this._slider.node.on('slide', this._onSliderChanged, this);
    }

    start() {
        // start 時に一度だけ現在の Slider 値で音量を反映
        if (this.applyOnLoad && this._slider) {
            this._applyVolumeFromSlider(this._slider.value);
        }
    }

    onDestroy() {
        // イベントのクリーンアップ
        if (this._slider) {
            this._slider.node.off('slide', this._onSliderChanged, this);
        }
    }

    /**
     * スライダー値変更時のハンドラ
     */
    private _onSliderChanged(slider: Slider) {
        const value = slider.value;
        this._applyVolumeFromSlider(value);
    }

    /**
     * Slider の値 (0.0〜1.0) から dB を計算し、AudioServer に反映する。
     */
    private _applyVolumeFromSlider(rawValue: number) {
        // 念のため 0〜1 にクランプ
        const value = clamp01(rawValue);

        // 線形補間で dB を計算
        const db = this.minDb + (this.maxDb - this.minDb) * value;

        if (this.logDebug) {
            log(`[VolumeControl] slider=${value.toFixed(3)} => volume=${db.toFixed(2)} dB`);
        }

        // ==== ここから AudioServer への適用処理 ====
        // TODO: プロジェクトの AudioServer 実装に合わせて書き換えてください。
        // 以下は例示的な疑似コードです（実際には存在しない API です）:
        //
        // import { AudioServer } from 'cc'; // 実際の import 先に合わせる
        // AudioServer.setMasterVolumeDb(db);
        //
        // あるいは、BGM/SE などチャンネル別の API がある場合:
        // AudioServer.setBgmVolumeDb(db);
        // AudioServer.setSeVolumeDb(db);
        //
        // このコンポーネント自体は外部スクリプトに依存しないよう、
        // 具体的なクラス名やシングルトンには依存させていません。
        // ===========================================
    }
}

コードのポイント解説

• onLoad()
  • this.getComponent(Slider) で同じノード上の Slider を取得。
  • 見つからない場合は error ログを出して以降の処理を行わない。
  • Slider のイベント 'slide' に _onSliderChanged を登録。
• start()
  • applyOnLoad が true なら、シーン開始時に現在の Slider 値から一度だけ音量を反映。
  • これにより、スライダーの初期位置がそのまま初期ボリュームになる。
• onDestroy()
  • 登録したイベント 'slide' を確実に解除して、不要なコールバック実行を防ぐ。
• _applyVolumeFromSlider()
  • 0〜1 の Slider 値を clamp01 で安全にクランプ。
  • minDb〜maxDb の範囲に線形補間して dB 値を算出。
  • デバッグ用ログ（logDebug が true のとき）。
  • AudioServer への具体的な反映は、プロジェクト側の API に合わせて書き換えられるよう、コメントで疑似コードとして分離。

使用手順と動作確認

1. スクリプトファイルの作成

1. エディタ左下の Assets パネルで、任意のフォルダ（例: assets/scripts/ui）を右クリックします。
2. Create → TypeScript を選択し、ファイル名を VolumeControl.ts にします。
3. 自動生成されたコードをすべて削除し、本記事の TypeScriptコードの実装 セクションにあるコードを丸ごと貼り付けて保存します。

2. テスト用 UI ノード（Slider）の作成

1. Hierarchy パネルで右クリック → Create → UI → Canvas を作成（既に Canvas がある場合は不要）。
2. Canvas を選択した状態で、右クリック → Create → UI → Slider を選択して Slider ノードを作成します。
3. 作成された Slider ノードを選択し、Inspector で Slider コンポーネントが付いていることを確認します（自動で付いているはずです）。

3. VolumeControl コンポーネントをアタッチ

1. Hierarchy で先ほど作成した Slider ノード を選択します。
2. Inspector の下部にある Add Component ボタンをクリックします。
3. Custom カテゴリから VolumeControl を選択してアタッチします。
   • 見つからない場合は、スクリプト保存後にエディタがコンパイル完了するまで数秒待ってから再度試してください。

4. プロパティの設定

Slider ノードにアタッチされた VolumeControl コンポーネントのプロパティを設定します。

• Min Db:
  • 例: -40（ほぼ無音にしたい場合）
  • 完全にミュートにしたい場合は、AudioServer 側の仕様に合わせて -80 や -100 など大きな負値にしても良いです。
• Max Db:
  • 例: 0（基準音量）
  • 少しブーストしたい場合は 3 や 6 などに変更しても構いません。
• Apply On Load:
  • true（デフォルト推奨）にしておくと、シーン開始時にスライダーの初期位置が AudioServer に即時反映されます。
• Log Debug:
  • 動作確認中は true にして、Console に出るログで dB の変化を確認すると便利です。
  • リリースビルドでは false に戻すことを推奨します。

5. AudioServer への適用部分の調整

プロジェクトで実際に利用している AudioServer の API に合わせて、
_applyVolumeFromSlider() 内の「TODO: プロジェクトの AudioServer 実装に合わせて書き換えてください。」と書かれた部分を修正します。

例（マスターボリュームを制御する場合のイメージ）：

// 仮の AudioServer 実装例
import { AudioServer } from 'cc'; // 実際のパスに合わせる

private _applyVolumeFromSlider(rawValue: number) {
    const value = clamp01(rawValue);
    const db = this.minDb + (this.maxDb - this.minDb) * value;

    if (this.logDebug) {
        log(`[VolumeControl] slider=${value.toFixed(3)} => volume=${db.toFixed(2)} dB`);
    }

    // 実際の AudioServer へ反映
    AudioServer.setMasterVolumeDb(db);
}

この修正は VolumeControl.ts 内部だけで完結し、他のカスタムスクリプトには一切依存しないようにしてください。

6. プレビューで動作確認

1. エディタ右上の Play ボタンを押してプレビューを開始します。
2. ゲーム画面に表示された Slider をドラッグしてみます。
3. Log Debug を true にしている場合、Console に

   [VolumeControl] slider=0.500 => volume=-20.00 dB

   のようなログが表示され、スライダー位置に応じて dB 値が変化していることを確認できます。

4. AudioServer 側の実装が正しく連携できていれば、スライダーを動かすことで実際にゲーム内の音量が変化します。

まとめ

本記事では、Cocos Creator 3.8 向けに、Slider にアタッチするだけで AudioServer の音量(dB)を制御できる「VolumeControl」コンポーネントを実装しました。

• 外部の GameManager やシングルトンに依存せず、このスクリプト単体で完結する設計。
• インスペクタから minDb / maxDb / applyOnLoad / logDebug を調整するだけで、様々なボリューム UI に対応可能。
• Slider の値を 0〜1 から任意の dB 範囲にマッピングするため、マスターボリューム・BGM・SE など幅広い用途に使い回せる。

このコンポーネントをベースに、BGM 用 VolumeControl、SE 用 VolumeControl といったバリエーションを作る場合も、
AudioServer への適用部分だけを差し替えればよく、UI 側の実装を毎回書き直す必要がなくなります。
ボリューム設定画面やオプションメニューの実装を、大幅にシンプルかつ再利用可能な形で構築できるはずです。