GFramework/GFramework.Godot/system/IAudioManagerSystem.cs

using GFramework.Core.Abstractions.system;
using Godot;

namespace GFramework.Godot.system;

/// <summary>
///     音频管理器系统接口，用于统一管理背景音乐和音效的播放
/// </summary>
public interface IAudioManagerSystem : ISystem
{
    /// <summary>
    ///     播放背景音乐
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="volume">音量大小，范围0-1</param>
    /// <param name="loop">是否循环播放</param>
    void PlayMusic(string audioPath, float volume = 1.0f, bool loop = true);

    /// <summary>
    ///     播放音效
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="volume">音量大小，范围0-1</param>
    /// <param name="pitch">音调调整</param>
    void PlaySound(string audioPath, float volume = 1.0f, float pitch = 1.0f);

    /// <summary>
    ///     播放特效音效
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="volume">音量大小，范围0-1</param>
    /// <param name="pitch">音调调整</param>
    void PlaySfx(string audioPath, float volume = 1.0f, float pitch = 1.0f);

    /// <summary>
    ///     播放语音
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="volume">音量大小，范围0-1</param>
    /// <param name="pitch">音调调整</param>
    void PlayVoice(string audioPath, float volume = 1.0f, float pitch = 1.0f);

    /// <summary>
    ///     播放环境音效
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="volume">音量大小，范围0-1</param>
    /// <param name="pitch">音调调整</param>
    void PlayAmbient(string audioPath, float volume = 1.0f, float pitch = 1.0f);

    /// <summary>
    ///     停止背景音乐
    /// </summary>
    void StopMusic();

    /// <summary>
    ///     暂停背景音乐
    /// </summary>
    void PauseMusic();

    /// <summary>
    ///     恢复背景音乐播放
    /// </summary>
    void ResumeMusic();

    /// <summary>
    ///     设置背景音乐音量
    /// </summary>
    /// <param name="volume">音量大小，范围0-1</param>
    void SetMusicVolume(float volume);

    /// <summary>
    ///     获取背景音乐音量
    /// </summary>
    /// <returns>音量大小，范围0-1</returns>
    float GetMusicVolume();

    /// <summary>
    ///     设置音效音量
    /// </summary>
    /// <param name="volume">音量大小，范围0-1</param>
    void SetSoundVolume(float volume);

    /// <summary>
    ///     获取音效音量
    /// </summary>
    /// <returns>音量大小，范围0-1</returns>
    float GetSoundVolume();

    /// <summary>
    ///     设置特效音量
    /// </summary>
    /// <param name="volume">音量大小，范围0-1</param>
    void SetSfxVolume(float volume);

    /// <summary>
    ///     获取特效音量
    /// </summary>
    /// <returns>音量大小，范围0-1</returns>
    float GetSfxVolume();

    /// <summary>
    ///     设置语音音量
    /// </summary>
    /// <param name="volume">音量大小，范围0-1</param>
    void SetVoiceVolume(float volume);

    /// <summary>
    ///     获取语音音量
    /// </summary>
    /// <returns>音量大小，范围0-1</returns>
    float GetVoiceVolume();

    /// <summary>
    ///     设置环境音量
    /// </summary>
    /// <param name="volume">音量大小，范围0-1</param>
    void SetAmbientVolume(float volume);

    /// <summary>
    ///     获取环境音量
    /// </summary>
    /// <returns>音量大小，范围0-1</returns>
    float GetAmbientVolume();

    /// <summary>
    ///     设置主音量
    /// </summary>
    /// <param name="volume">音量大小，范围0-1</param>
    void SetMasterVolume(float volume);

    /// <summary>
    ///     获取主音量
    /// </summary>
    /// <returns>音量大小，范围0-1</returns>
    float GetMasterVolume();

    /// <summary>
    ///     检查背景音乐是否正在播放
    /// </summary>
    /// <returns>正在播放返回true，否则返回false</returns>
    bool IsMusicPlaying();

    /// <summary>
    ///     淡入背景音乐
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="duration">淡入持续时间（秒）</param>
    /// <param name="volume">目标音量</param>
    void FadeInMusic(string audioPath, float duration, float volume = 1.0f);

    /// <summary>
    ///     淡出背景音乐
    /// </summary>
    /// <param name="duration">淡出持续时间（秒）</param>
    void FadeOutMusic(float duration);

    /// <summary>
    ///     播放3D音效
    /// </summary>
    /// <param name="audioPath">音频文件路径</param>
    /// <param name="position">3D空间中的位置</param>
    /// <param name="volume">音量大小，范围0-1</param>
    void PlaySound3D(string audioPath, Vector3 position, float volume = 1.0f);

    /// <summary>
    ///     设置低通滤波器强度
    /// </summary>
    /// <param name="amount">滤波器强度，范围0-1</param>
    void SetLowPassFilter(float amount);

    /// <summary>
    ///     设置音频混响效果
    /// </summary>
    /// <param name="roomSize">房间大小</param>
    /// <param name="damping">阻尼</param>
    /// <param name="wetLevel">湿声级别</param>
    void SetReverb(float roomSize, float damping, float wetLevel);
}