1
// ===== 五种音频播放方式：从快捷到完全控制 =====
2

3
void AudioPlaybackExamples(AActor* ContextActor)
4
{
5
    USoundBase* MySound = ...;  // MetaSound 或 SoundCue 或 SoundWave
6

7
    // ---------- ① PlaySoundAtLocation：纯快捷——不返回组件 ----------
8
    // 适用：脚步声、撞击声、环境音——播完即弃
9
    UGameplayStatics::PlaySoundAtLocation(
10
        ContextActor->GetWorld(),
11
        MySound,
12
        ContextActor->GetActorLocation(),
13
        FRotator::ZeroRotator,
14
        1.0f,    // VolumeMultiplier
15
        1.0f,    // PitchMultiplier
16
        0.0f,    // StartTime
17
        nullptr, // AttenuationSettings（nullptr = 使用 Sound 内置设定）
18
        nullptr  // ConcurrencySettings
19
    );
20

21
    // ---------- ② PlaySound2D：无空间化的 UI 播放 ----------
22
    // 适用：按钮点击、菜单切换、提示音——不需要 3D 定位
23
    UGameplayStatics::PlaySound2D(
24
        ContextActor->GetWorld(),
25
        MySound,
26
        1.0f, 1.0f, 0.0f
27
    );
28

29
    // ---------- ③ SpawnSoundAttached：挂载到组件——返回 AudioComponent ----------
30
    // 适用：角色身上的持续音效（引擎声、心跳声、护盾嗡嗡声）
31
    UAudioComponent* AttachedComp = UGameplayStatics::SpawnSoundAttached(
32
        MySound,
33
        ContextActor->GetRootComponent(),  // AttachToComponent
34
        NAME_None,                          // AttachPointName（Socket 名）
35
        FVector::ZeroVector,                // Location（相对偏移）
36
        FRotator::ZeroRotator,              // Rotation
37
        EAttachLocation::KeepRelativeOffset,
38
        false,    // bStopWhenAttachedToDestroyed
39
        1.0f,     // VolumeMultiplier
40
        1.0f,     // PitchMultiplier
41
        0.0f,     // StartTime
42
        nullptr,  // AttenuationSettings
43
        nullptr,  // ConcurrencySettings
44
        true      // bAutoDestroy —— 播放完自动销毁
45
    );
46

47
    // ---------- ④ SpawnSound2D：2D 播放但返回组件——可控制 ----------
48
    // 适用：需要动态音量/音高控制的 UI 音效
49
    UAudioComponent* TwoDComp = UGameplayStatics::SpawnSound2D(
50
        ContextActor->GetWorld(),
51
        MySound,
52
        1.0f, 1.0f, 0.0f,
53
        nullptr,  // ConcurrencySettings
54
        true,     // bPersistAcrossLevelTransition
55
        true      // bAutoDestroy
56
    );
57

58
    // ---------- ⑤ 手动创建 UAudioComponent：终极控制 ----------
59
    // 适用：需要精细控制每一个参数——动态混音、运行时 DSP 切换
60
    UAudioComponent* ManualComp = NewObject<UAudioComponent>(ContextActor);
61
    ManualComp->RegisterComponent();                          // ★ 必须注册！
62
    ManualComp->SetSound(MySound);
63
    ManualComp->SetVolumeMultiplier(0.8f);
64
    ManualComp->SetPitchMultiplier(1.2f);
65
    ManualComp->bAutoDestroy = true;
66
    ManualComp->Play();
67
}

1
// ===== UAudioComponent 核心方法 =====
2
UCLASS()
3
class UAudioComponentExample
4
{
5
    void FullControl(UAudioComponent* AudioComp)
6
    {
7
        // ---------- 播放控制 ----------
8
        AudioComp->Play();         // 从头播放
9
        AudioComp->Play(1.5f);     // 从 1.5 秒处开始播放
10
        AudioComp->Stop();         // 立即停止
11
        // ★ 没有 StopDelayed —— 延迟停止需用 Timer 或 FadeOut 淡出后 Stop
12
        AudioComp->SetPaused(true);    // 暂停
13
        AudioComp->SetPaused(false);   // 继续
14

15
        // ---------- 淡入淡出 ----------
16
        AudioComp->FadeIn(0.5f);                        // 0.5 秒淡入到 1.0
17
        AudioComp->FadeIn(0.5f, 0.8f);                  // 0.5 秒淡入到 0.8
18
        AudioComp->FadeOut(1.0f);                       // 1 秒淡出到 0
19
        AudioComp->FadeOut(1.0f, 0.2f);                 // 1 秒淡出到 0.2（背景弱化）
20

21
        // ---------- 音量与音高 ----------
22
        AudioComp->SetVolumeMultiplier(1.5f);            // 提升 50%
23
        AudioComp->SetPitchMultiplier(0.9f);             // 降低 10%——模拟慢动作
24
        // ★ AdjustVolume(Duration, TargetLevel) —— 第一个参数是持续时间，第二个是目标值
25
        AudioComp->AdjustVolume(0.5f, 0.1f);            // 0.5 秒内将音量调整到 0.1
26
        AudioComp->AdjustVolume(1.0f, -0.2f);           // 1.0 秒内将音量调整到 -0.2
27

28
        // ---------- 空间化设置 ----------
29
        // ★ 没有 AdjustAttenuation —— 运行时修改衰减需通过 AttenuationOverrides 结构体
30
        AudioComp->bOverrideAttenuation = true;          // 必须先勾选覆盖
31
        // AudioComp->AttenuationOverrides.bAttenuate = true;
32
        // AudioComp->AttenuationOverrides.dBAttenuationAtMax = -60.f;  // 示例：修改最大衰减量
33
        // ⚠️ UAudioComponent 上没有 SetUISound() 方法！
34
        //    bIsUISound 是 USoundBase 资产层级的属性，或 FActiveSound 内部标记
35
        //    想让音效不经过空间化 → 使用 UGameplayStatics::PlaySound2D / SpawnSound2D
36

37
        // ---------- 状态查询 ----------
38
        bool bPlaying = AudioComp->IsPlaying();
39
        float PlaybackTime = AudioComp->GetPlaybackTime();
40
        float Duration = AudioComp->GetDuration();
41
        bool bVirtualized = AudioComp->IsVirtual();      // 是否因距离太远被虚拟化
42
    }
43
};

1
// ===== 完整脚步声系统：物理材质 + 随机音效池 + 冷却 =====
2
UCLASS()
3
class UFootstepComponent : public UActorComponent
4
{
5
    GENERATED_BODY()
6

7
public:
8
    virtual void BeginPlay() override
9
    {
10
        Super::BeginPlay();
11
        OwnerActor = GetOwner();
12

13
        if (OwnerActor)
14
        {
15
            // 缓存角色骨骼网格体——获取脚下 Socket 位置
16
            CachedMesh = OwnerActor->FindComponentByClass<USkeletalMeshComponent>();
17
        }
18
    }
19

20
    // 由 AnimNotify 调用
21
    UFUNCTION(BlueprintCallable, Category = "Footstep")
22
    void PlayFootstep()
23
    {
24
        if (!OwnerActor || !CachedMesh) return;
25

26
        // ① 脚下射线检测——获取物理表面类型
27
        FVector FootLocation = CachedMesh->GetSocketLocation(FootSocketName);
28
        FVector TraceStart = FootLocation + FVector(0, 0, 20.0f);
29
        FVector TraceEnd   = FootLocation - FVector(0, 0, 50.0f);
30

31
        FHitResult Hit;
32
        FCollisionQueryParams Params;
33
        Params.AddIgnoredActor(OwnerActor);
34
        Params.bReturnPhysicalMaterial = true;
35

36
        EPhysicalSurface SurfaceType = EPhysicalSurface::SurfaceType_Default;
37
        if (OwnerActor->GetWorld()->LineTraceSingleByChannel(
38
                Hit, TraceStart, TraceEnd, ECC_Visibility, Params))
39
        {
40
            if (Hit.PhysMaterial.IsValid())
41
            {
42
                SurfaceType = Hit.PhysMaterial->SurfaceType;
43
            }
44
        }
45

46
        // ② 根据表面类型选择音效池
47
        TArray<USoundBase*>* SoundPool = FootstepMap.Find(SurfaceType);
48
        if (!SoundPool || SoundPool->Num() == 0) return;
49

50
        // ③ 随机选择 + 轻微随机音高（避免重复感）
51
        int32 Index = FMath::RandRange(0, SoundPool->Num() - 1);
52
        float RandomPitch = FMath::RandRange(0.95f, 1.05f);
53

54
        UGameplayStatics::PlaySoundAtLocation(
55
            OwnerActor->GetWorld(),
56
            (*SoundPool)[Index],
57
            Hit.bBlockingHit ? Hit.Location : OwnerActor->GetActorLocation(),
58
            FRotator::ZeroRotator,
59
            1.0f,
60
            RandomPitch
61
        );
62
    }
63

64
    UPROPERTY(EditDefaultsOnly, Category = "Footstep")
65
    FName FootSocketName = TEXT("foot_l");
66

67
protected:
68
    UPROPERTY(EditDefaultsOnly, Category = "Footstep")
69
    TMap<TEnumAsByte<EPhysicalSurface>, TArray<USoundBase*>> FootstepMap;
70
    // 键 = SurfaceType_Default / SurfaceType1(Concrete) / SurfaceType2(Wood) ...
71
    // 值 = 该表面的脚步声变体数组
72

73
    TWeakObjectPtr<AActor> OwnerActor;
74
    TObjectPtr<USkeletalMeshComponent> CachedMesh;
75
};

1
// ===== MetaSounds：UE5 的音频"Material Editor" =====
2
//
3
// SoundCue（UE4 遗留）：
4
//   - 节点数固定（WavePlayer / Random / Mixer / Modulator / Attenuation）
5
//   - 没有真正的参数系统——只能通过 WaveParameter 等节点做简单映射
6
//   - 逻辑编排能力弱——无法做条件分支、状态保持
7
//
8
// MetaSounds（UE5 新一代）：
9
//   - 类似 Material Editor 的完整节点图
10
//   - 内置参数系统：Bool / Float / Int / String / Wave / Trigger
11
//   - 支持 Input 节点（接收外部参数）和 Output 节点（回传音频数据）
12
//   - 支持 Generator（振荡器/噪声）——不需要预录音频文件也能合成声音
13
//   - 支持实时 Parameter 控制——比 SoundCue 灵活一个数量级
14
//
15
// 一句话：SoundCue = 音频播放器，MetaSounds = 音频合成器 + 效果器
16

17
// ---------- C++ 中动态控制 MetaSounds 参数 ----------
18
void ControlMetaSound(UAudioComponent* AudioComp)
19
{
20
    if (!AudioComp || !AudioComp->GetSound()) return;
21

22
    // MetaSounds 参数通过 AudioComponent 的 Set*Parameter 系列方法设置
23
    // 注意：参数名必须与 MetaSound 图中定义的 Input 节点名称完全匹配
24

25
    // 浮点参数——引擎推力、心跳频率
26
    AudioComp->SetFloatParameter(FName(TEXT("EngineRPM")), 6500.0f);
27

28
    // 布尔参数——开关效果器
29
    AudioComp->SetBoolParameter(FName(TEXT("bUnderwater")), true);
30

31
    // 整数参数——选择变体
32
    AudioComp->SetIntParameter(FName(TEXT("GearIndex")), 3);
33

34
    // 字符串参数——切换音色库
35
    AudioComp->SetStringParameter(FName(TEXT("SurfaceMaterial")), TEXT("Metal"));
36

37
    // 触发参数——一次性事件（如"播放碰撞音"）
38
    AudioComp->SetTriggerParameter(FName(TEXT("OnImpact")));
39

40
    // Wave 参数——运行时替换音频波形
41
    AudioComp->SetWaveParameter(FName(TEXT("ExplosionSample")), ExplosionWave);
42
}
43

44
// ===== MetaSounds 关键 API 速记 =====
45
//
46
// UMetaSoundSource：
47
//   - 继承自 USoundBase——可以用于任何接受 USoundBase* 的地方
48
//   - 运行时不可编辑——所有修改通过 Set*Parameter 完成
49
//
50
// 参数类型与作用：
51
//   Float   → 连续量（速度、距离、强度）
52
//   Bool    → 开关（模式切换、效果器激活）
53
//   Int     → 离散选项（音阶、索引）
54
//   Trigger → 瞬时事件（碰撞、射击）——触发后自动复位
55
//   Wave    → 运行时替换音频资源
56
//   String  → 标签/标识

1
// ===== 动态引擎音效：MetaSounds + 实时 RPM 参数 =====
2
UCLASS()
3
class AEngineSoundController : public AActor
4
{
5
    GENERATED_BODY()
6

7
public:
8
    virtual void BeginPlay() override
9
    {
10
        Super::BeginPlay();
11

12
        // 挂载 AudioComponent 到自身
13
        EngineAudioComp = UGameplayStatics::SpawnSoundAttached(
14
            EngineSound,          // UMetaSoundSource*
15
            GetRootComponent(),
16
            NAME_None,
17
            FVector::ZeroVector,
18
            FRotator::ZeroRotator,
19
            EAttachLocation::KeepRelativeOffset,
20
            false,                // bStopWhenAttachedToDestroyed
21
            0.0f,                 // VolumeMultiplier——先静音
22
            1.0f
23
        );
24
    }
25

26
    virtual void Tick(float DeltaTime) override
27
    {
28
        Super::Tick(DeltaTime);
29

30
        if (!EngineAudioComp || !EngineAudioComp->IsPlaying()) return;
31

32
        // 从物理组件读取当前发动机转速
33
        float CurrentRPM = GetEngineRPM();
34

35
        // 平滑 RPM 参数——避免突变
36
        float SmoothedRPM = FMath::FInterpTo(
37
            CachedRPM, CurrentRPM, DeltaTime, 3.0f);
38
        CachedRPM = SmoothedRPM;
39

40
        // ★ 实时更新 MetaSounds 的浮点参数
41
        //   MetaSound 图内部用这个参数驱动：振荡器频率 + 滤波器截止 + 音量曲线
42
        EngineAudioComp->SetFloatParameter(FName(TEXT("EngineRPM")), SmoothedRPM);
43

44
        // 引擎负载影响额外谐波强度
45
        float Load = GetEngineLoad();
46
        EngineAudioComp->SetFloatParameter(FName(TEXT("EngineLoad")), Load);
47
    }
48

49
    float GetEngineRPM() const
50
    {
51
        // 从载具物理或自定义组件中读取
52
        return 3000.0f;
53
    }
54

55
    float GetEngineLoad() const
56
    {
57
        return 0.5f;
58
    }
59

60
protected:
61
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
62
    TObjectPtr<USoundBase> EngineSound;  // 指向 UMetaSoundSource 资产
63

64
    UPROPERTY()
65
    TObjectPtr<UAudioComponent> EngineAudioComp;
66

67
    float CachedRPM = 0.0f;
68
};

1
// ===== SoundCue：节点编辑器概览 =====
2
//
3
// SoundCue 是 UE4 时代的主力音频工具，在 UE5 中依然广泛使用。
4
// 它通过连线节点图定义"一个音频事件触发后怎么播放”。
5
//
6
// 核心节点族：
7
// ┌────────────────┬──────────────────────────────────────┐
8
// │ WavePlayer      │ 播放单个 .wav 文件                     │
9
// │ Random          │ N 个输入中随机选一个（变体不重复感）       │
10
// │ Mixer           │ 叠加多个输入（同时播放多个波形）          │
11
// │ Modulator       │ 调制音量/音高（低频振荡器做颤音/震动）    │
12
// │ Attenuation     │ 覆盖默认的空间衰减行为                   │
13
// │ Concatenator    │ 串接多个波形（A→B→C 依次播放）           │
14
// │ Looping         │ 循环播放（引擎声、环境音）               │
15
// │ Delay           │ 延迟播放（时间差产生空间感）              │
16
// │ SoundClass      │ 音效分类（SFX/Music/Voice——独立音量控制） │
17
// └────────────────┴──────────────────────────────────────┘
18

19
// ---------- C++ 中使用 SoundCue ----------
20
void PlayGunshotSound(AActor* Shooter)
21
{
22
    // SoundCue 在使用上与 MetaSounds 完全相同——它们都是 USoundBase*
23
    USoundCue* GunshotCue = LoadObject<USoundCue>(nullptr,
24
        TEXT("/Game/Audio/Cues/Gunshot_Cue.Gunshot_Cue"));
25

26
    if (GunshotCue)
27
    {
28
        // 在枪口位置播放——自动应用 SoundCue 中配置的 Attenuation 节点
29
        UGameplayStatics::PlaySoundAtLocation(
30
            Shooter->GetWorld(),
31
            GunshotCue,
32
            Shooter->GetActorLocation() + Shooter->GetActorForwardVector() * 100.0f
33
        );
34
    }
35
}

1
// ===== 什么时候用 SoundCue，什么时候用 MetaSounds？ =====
2
//
3
// 继续使用 SoundCue：
4
//   ✓ 项目从 UE4 迁移——已有数百个 SoundCue 资产
5
//   ✓ 简单的一次性音效——枪声、爆炸、UI 点击
6
//   ✓ 只需随机变体 + 简单衰减——SoundCue 的 Random + Attenuation 节点足够
7
//   ✓ 团队还在学习曲线——SoundCue 节点图更简单直观
8
//
9
// 切换到 MetaSounds：
10
//   ✓ 需要运行时参数——引擎 RPM、呼吸频率、动态混响量
11
//   ✓ 需要音频合成——不需要 .wav 文件，纯算法生成（风声、科幻音效）
12
//   ✓ 需要条件逻辑——"如果在室内用这个混响，室外用那个"
13
//   ✓ 需要 Trigger 事件——"碰撞发生的瞬间播放撞击音"
14
//   ✓ 新项目从零开始——MetaSounds 是 UE5 的推荐方向
15
//
16
// 经验法则：
17
//   简单音效（播一次、不管了） → SoundCue
18
//   复杂音效（实时参数、音频合成、条件路由） → MetaSounds

1
// ===== Submix：音频后处理的"Post Process Volume" =====
2
//
3
// Submix 将音频分类路线——每一路经过独立的 DSP 效果链：
4
//
5
//   Master Submix（主输出）
6
//   ├── SFX Submix（音效）
7
//   │   ├── Reverb（混响）→ 枪声在走廊里的回响
8
//   │   └── EQ（均衡器）→ 削减脚步声的低频，提升清晰度
9
//   ├── Music Submix（音乐）
10
//   │   └── Compressor → 动作高潮时自动压缩，不让音乐盖过对话
11
//   ├── Voice Submix（对话）
12
//   │   └── EQ + De-esser → 对话更清晰
13
//   └── Ambient Submix（环境音）
14
//       └── Reverb + Delay → 风声、虫鸣的空间感
15
//
16
// 在 Project Settings → Audio 中配置默认 Submix 层级
17
// 每个 SoundBase 可指定所属的 SoundClass（→ Submix）
18

19
// ---------- C++ 中动态控制 Submix ----------
20
void ControlSubmix()
21
{
22
    // 获取 Submix
23
    USoundSubmix* SFXSubmix = LoadObject<USoundSubmix>(nullptr,
24
        TEXT("/Game/Audio/Submixes/SFX_Submix.SFX_Submix"));
25

26
    if (SFXSubmix)
27
    {
28
        // 动态调整 Submix 的输出音量（主音量 0.0-1.0）
29
        // UGameplayStatics 提供了直接控制 Submix 的静态方法
30
    }
31
}
32

33
// ---------- AudioComponent 级别的 Submix Send ----------
34
void SetupSubmixSend(UAudioComponent* AudioComp, USoundSubmix* ReverbSubmix)
35
{
36
    // 将单个 AudioComponent 的输出发送到指定 Submix
37
    // SendLevel: 0.0 = 不发送，1.0 = 全量发送
38
    AudioComp->SetSubmixSend(ReverbSubmix, 0.5f);
39

40
    // 典型用途：
41
    // - 特定角色的脚步声额外发送到"洞穴混响"Submix
42
    // - 关键对话发送到"无线电滤波"Submix（模拟对讲机效果）
43
}

1
// ===== AudioBus：运行时音频数据总线 =====
2
//
3
// AudioBus 是一条"音频数据管道"，但路由拓扑有严格的物理边界：
4
//
5
// ① AudioComponent → Submix → AudioBus（正统路径）
6
//    普通 AudioComponent 只有 SetSubmixSend 权限——不能直接裸连 UAudioBus。
7
//    音频数据必须流经 USoundSubmix，在 Submix 层级配置 AudioBusSends。
8
//
9
// ② USoundSourceBus → AudioBus（直连路径）
10
//    如果想让一个声源纯粹作为总线输入，使用 USoundSourceBus（继承自 USoundBase），
11
//    通过 SetSound 直接播放——它本身就是 AudioBus 的声源适配器。
12
//
13
// 典型场景：
14
//   - 音频可视化——Music Submix → AudioBus → EnvelopeAnalyzer → 驱动灯光/UI
15
//   - 语音聊天混合——多个玩家的语音发送到 Bus → 统一处理后输出
16
//   - 自定义 DSP——将特定音频路由到 Bus → 音频分析器做 FFT 频谱分析
17

18
// ---------- 音频可视化：Submix → AudioBus → 包络分析 ----------
19
UCLASS()
20
class UAudioVisualizer : public UActorComponent
21
{
22
    GENERATED_BODY()
23

24
public:
25
    void BeginPlay() override
26
    {
27
        Super::BeginPlay();
28

29
        // 创建 AudioComponent 播放音乐
30
        MusicComp = UGameplayStatics::SpawnSound2D(
31
            GetWorld(),
32
            BackgroundMusic,
33
            1.0f, 1.0f, 0.0f,
34
            nullptr,
35
            true,  // bPersistAcrossLevelTransition
36
            false  // bAutoDestroy——手动管理生命周期
37
        );
38

39
        // ★ 正统路径：将音频发送到自定义 Submix（而非直接连 AudioBus）
40
        //   Submix 到 AudioBus 的路由在编辑器中配置（Submix → AudioBusSends）
41
        if (MusicComp && MusicSubmix)
42
        {
43
            MusicComp->SetSubmixSend(MusicSubmix, 1.0f);
44
        }
45

46
        // ★ UE5 正统音频包络分析方式：
47
        //   使用 UAudioMixerBlueprintLibrary::RegisterSubmixEnvelopeFollowerDelegate
48
        //   注册回调 → 音频线程异步推送包络数据到 GameThread
49
        //   或者使用 UEnvelopeFollowerListener（ActorComponent 封装）
50
        //   ⚠️ 引擎不存在 UAudioBusEnvelopeAnalyzer 这个 UObject 类——
51
        //     音频包络分析是严格的音频线程异步回调机制，不能在 GameThread 上
52
        //     通过虚构的对象主动 Pull 变量
53
        SetupEnvelopeCallback();
54

55
        // 启动定时读取（从缓存的包络值）
56
        GetWorld()->GetTimerManager().SetTimer(
57
            AnalysisTimerHandle,
58
            this,
59
            &UAudioVisualizer::OnEnvelopeUpdate,
60
            0.05f,   // 每 50ms 更新一次 UI（20Hz 刷新率）
61
            true
62
        );
63
    }
64

65
    void SetupEnvelopeCallback()
66
    {
67
        // ✓ UE5 正统做法：通过 UAudioMixerBlueprintLibrary 注册包络跟随器
68
        //   FOnSubmixEnvelopeBP delegate;  // 存储为成员变量
69
        //   UAudioMixerBlueprintLibrary::RegisterSubmixEnvelopeFollowerDelegate(
70
        //       GetWorld(), MusicSubmix, delegate);
71
        //   delegate 被触发时，将包络值缓存到成员变量 CurrentAmplitude 中
72
    }
73

74
    void OnEnvelopeUpdate()
75
    {
76
        // 从缓存的包络值中读取（由音频线程回调更新）
77
        // 驱动 UI / 灯光强度
78
        UpdateVisuals(CurrentAmplitude);
79
    }
80

81
    UFUNCTION(BlueprintImplementableEvent, Category = "Visualization")
82
    void UpdateVisuals(float Amplitude);
83

84
protected:
85
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
86
    TObjectPtr<USoundBase> BackgroundMusic;
87

88
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
89
    TObjectPtr<USoundSubmix> MusicSubmix;    // ★ 音频通过 Submix 路由
90

91
    UPROPERTY()
92
    TObjectPtr<UAudioComponent> MusicComp;
93

94
    FTimerHandle AnalysisTimerHandle;
95

96
    float CurrentAmplitude = 0.0f;  // 由音频线程回调更新，GameThread 读取
97
};

1
### 18.5.3 SoundConcurrency：并发数控制
2

3
```cpp
4
// ===== SoundConcurrency：防止"音频齐射" =====
5
//
6
// 问题：10 个敌人同时死亡 → 10 个死亡音效同时播放 → 音频削波、刺耳
7
// 解决：USoundConcurrency 限制同一组音频的最大并发数
8

9
void SetupConcurrency(USoundBase* DeathSound)
10
{
11
    // 方式 1：在编辑器中为 SoundCue / MetaSound 指定 Concurrency 资产
12
    // 方式 2：在 C++ 播放时动态指定
13

14
    USoundConcurrency* DeathConcurrency = LoadObject<USoundConcurrency>(nullptr,
15
        TEXT("/Game/Audio/Concurrency/Death_Limit_3.Death_Limit_3"));
16

17
    // Concurrency 资产配置：
18
    //   Max Count = 3         → 最多同时播放 3 个
19
    //   Resolution Rule = Stop Oldest → 超出时停止最早的那个
20
    //   Volume Scale = 0.8    → 同时播放 3 个时每个降 20%
21

22
    UGameplayStatics::PlaySoundAtLocation(
23
        GetWorld(),
24
        DeathSound,
25
        GetActorLocation(),
26
        FRotator::ZeroRotator,
27
        1.0f, 1.0f, 0.0f,
28
        nullptr,           // Attenuation
29
        DeathConcurrency   // ★ Concurrency
30
    );
31
}
32

33
// ===== Concurrency 规则速查 =====
34
//
35
// Max Count：最大同时播放数
36
// Resolution Rule（超出时行为）：
37
//   Stop Oldest         → 停止最早的
38
//   Stop Farthest       → 停止距离最远的
39
//   Stop Lowest Priority → 停止优先级最低的
40
//   Stop Quietest       → 停止音量最小的
41
//   Prevent New         → 拒绝新播放请求
42
//
43
// 常用策略：
44
//   脚步声 Concurrency = 4, Stop Oldest     → 同一角色最多 4 个脚步同时响
45
//   死亡音效 Concurrency = 3, Stop Farthest → 只播放最近 3 个死亡音效

1
// ===== USoundAttenuation：定义"声音在空间中怎么衰减" =====
2
//
3
// 核心设置项：
4
//   Attenuation Shape：Sphere / Capsule / Box / Cone —— 衰减体的形状
5
//   Distance Algorithm：Linear / Logarithmic / Inverse / Natural Sound
6
//   Attenuation Range：Min（全音量半径）→ Max（听不见的半径）
7
//   Air Absorption：高频随距离衰减——远距离枪声变闷
8
//   Focus / Azimuth：声源方向性（声音朝前方比朝后方更响）
9

10
// ---------- C++ 中动态控制衰减 ----------
11
void DynamicAttenuationControl(UAudioComponent* AudioComp)
12
{
13
    // ① 加载 Attenuation 资产
14
    USoundAttenuation* LongRangeAttenuation = LoadObject<USoundAttenuation>(nullptr,
15
        TEXT("/Game/Audio/Attenuation/LongRange_Gunshot.LongRange_Gunshot"));
16

17
    USoundAttenuation* ShortRangeAttenuation = LoadObject<USoundAttenuation>(nullptr,
18
        TEXT("/Game/Audio/Attenuation/ShortRange_Footstep.ShortRange_Footstep"));
19

20
    // ② 动态控制衰减——先勾选 Override，再修改 AttenuationOverrides 结构体
21
    // 注意：没有 AdjustAttenuation() 函数——运行时只能通过 AttenuationOverrides 修改
22
    // 例如：同一把枪——室内用短衰减（声音被墙反射），室外用长衰减（声音传播远）
23
    AudioComp->bOverrideAttenuation = true;  // ★ 必须先启用覆盖
24

25
    // ③ 修改覆盖参数——例如暴风雨天气下所有音效衰减更快
26
    AudioComp->SetVolumeMultiplier(0.6f);  // 整体音量降低以模拟远距离
27
}
28

29
// ===== Attenuation 形状选择指南 =====
30
//
31
// Sphere    → 全向均匀衰减（爆炸、环境音）
32
// Capsule   → 垂直方向更长的衰减体（高楼上的声音——上下传播更远）
33
// Box       → 房间内的声音（走廊、房间）
34
// Cone      → 方向性声源（NPC 对话——正前方比背后听得远）

1
// ===== HRTF（Head-Related Transfer Function）：3D 定位的终极方案 =====
2
//
3
// 传统 Stereo：只能分辨左右——无法分辨"前面"还是"后面"
4
// 传统 5.1/7.1：需要多声道音响——成本高
5
// HRTF：用一副普通耳机就能分辨上下左右前后——模拟人耳对声波的物理过滤
6
//
7
// 原理：声音从不同方向到达双耳时，被头部、耳廓、肩膀遮挡和反射，
8
//       产生微妙的时间差（ITD）、音量差（ILD）和频谱变化（HRTF 滤波）。
9
//       引擎实时应用这些滤波 → 大脑"被欺骗"感知到 3D 位置。
10
//
11
// 在 Project Settings → Audio → Spatialization Plugin 中启用
12
// 支持的插件：内置 HRTF / Steam Audio / Oculus Audio / Resonance Audio
13

14
// ---------- C++ 中启用 HRTF ----------
15
void EnableHRTFForSound(USoundBase* Sound)
16
{
17
    // HRTF 是一种 Spatialization 方式——在 Attenuation 资产中配置
18
    // 编辑器中：Attenuation → Spatialization → Enable Spatialization + HRTF
19
    // C++ 中：通过 USoundAttenuation 的 SpatializationAlgorithm 属性
20

21
    // 运行时验证 HRTF 是否可用：
22
    if (FAudioDevice* AudioDevice = GEngine->GetMainAudioDeviceRaw())
23
    {
24
        // AudioDevice 提供了查询当前空间化插件的能力
25
        // 具体实现依赖插件 API
26
        UE_LOG(LogAudio, Log, TEXT("HRTF Spatialization enabled"));
27
    }
28
}
29

30
// ===== 空间音频面试要点速记 =====
31
//
32
// Attenuation：
33
//   声音随距离变小的数学模型（线性 / 对数 / 自然衰减）
34
//   + 空气吸收（高频衰减 → 远处枪声比近处闷）
35
//   + 方向性（Focus / Azimuth——声源不是全向等强的）
36
//
37
// HRTF：
38
//   用一对滤波器模拟声波绕过头颅和耳廓的物理路径
39
//   渲染结果：普通耳机就能听到准确的 3D 定位
40
//   注意：HRTF 必须用耳机听——扬声器会破坏双耳线索
41
//
42
// Occlusion（遮挡）：
43
//   声源与听者之间有障碍物 → 声音被"闷化"（低通滤波）
44
//   与 Attenuation 不同——Occlusion 是"有一个墙挡住了"的动态效果
45
//
46
// Obstruction（阻塞）：
47
//   部分遮挡——不是全闷，而是部分频率被阻挡
48
//   内置音频引擎通过射线检测自动计算 Occlusion/Obstruction

1
// ===== 枪声的完整空间音频：衰减 + HRTF + 遮挡 + 混响 Send =====
2
UCLASS()
3
class AGunAudioController : public AActor
4
{
5
    GENERATED_BODY()
6

7
public:
8
    void PlayGunshotAt(const FVector& MuzzleLocation, const FVector& AimDirection)
9
    {
10
        if (!GunshotSound) return;
11

12
        // ① 生成枪声
13
        UAudioComponent* GunAudio = UGameplayStatics::SpawnSoundAtLocation(
14
            GetWorld(),
15
            GunshotSound,
16
            MuzzleLocation,
17
            AimDirection.Rotation(),
18
            1.0f, 1.0f, 0.0f,
19
            GunAttenuation,     // ★ 枪声专用衰减（长距离 + Cone 方向性）
20
            GunConcurrency      // ★ 同一时刻最多 5 个枪声
21
        );
22

23
        if (!GunAudio) return;
24

25
        // ② 室内/室外切换混响量
26
        bool bIsIndoor = CheckIfIndoor(MuzzleLocation);
27
        if (bIsIndoor && IndoorReverbSubmix)
28
        {
29
            GunAudio->SetSubmixSend(IndoorReverbSubmix, 0.4f);  // 室内混响
30
        }
31

32
        // ③ HRTF 由 Attenuation 资产中的配置控制——无需 C++ 额外处理
33
    }
34

35
    bool CheckIfIndoor(const FVector& Location) const
36
    {
37
        // 简化检测：向上 Trace 看是否有天花板
38
        FHitResult Hit;
39
        return GetWorld()->LineTraceSingleByChannel(
40
            Hit,
41
            Location,
42
            Location + FVector(0, 0, 500.0f),
43
            ECC_Visibility
44
        );
45
    }
46

47
protected:
48
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
49
    TObjectPtr<USoundBase> GunshotSound;
50

51
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
52
    TObjectPtr<USoundAttenuation> GunAttenuation;
53

54
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
55
    TObjectPtr<USoundConcurrency> GunConcurrency;
56

57
    UPROPERTY(EditDefaultsOnly, Category = "Audio")
58
    TObjectPtr<USoundSubmix> IndoorReverbSubmix;
59
};

1
// ===== 陷阱 #1：SpawnSoundAttached 忘了保存返回的 AudioComponent =====
2
void BadOneShot()
3
{
4
    // ✗ 返回的 UAudioComponent* 被丢弃——无法淡出、无法提前停止
5
    //   如果需要在声音结束前做任何控制，这就是个资源泄漏点
6
    UGameplayStatics::SpawnSoundAttached(Sound, RootComp);
7
}
8
// ✓ 保存引用或使用 PlaySoundAtLocation（如果不需要控制）
9
// UAudioComponent* Comp = UGameplayStatics::SpawnSoundAttached(...);
10

11
// ===== 陷阱 #2：脚步声音效每帧都产生新的 AudioComponent =====
12
void ABadCharacter::Tick(float DeltaTime)
13
{
14
    // ✗ 不检查是否已经在播放——每秒 30 帧 = 30 个脚步声音组件被创建
15
    //   音频线程崩溃、内存暴涨、超过语音数上限
16
    UGameplayStatics::PlaySoundAtLocation(GetWorld(), FootstepSound,
17
        GetActorLocation());
18
}
19
// ✓ 由 AnimNotify 按需触发 + Concurrency 限制最大并发数
20

21
// ===== 陷阱 #3：2D 和 3D 音效用混了 =====
22
void BadUISound()
23
{
24
    // ✗ PlaySoundAtLocation 对 UI 按钮使用——播放位置在 (0,0,0)
25
    //   听者与 (0,0,0) 有距离 → UI 点击声随距离变小甚至听不到！
26
    UGameplayStatics::PlaySoundAtLocation(GetWorld(), UIClickSound,
27
        FVector::ZeroVector);
28
}
29
// ✓ UI 音效用 PlaySound2D——不经过空间化，始终全音量
30

31
// ===== 陷阱 #4：忘记 bAutoDestroy = true =====
32
void BadManualComponent()
33
{
34
    UAudioComponent* Comp = NewObject<UAudioComponent>(this);
35
    Comp->RegisterComponent();
36
    Comp->SetSound(MySound);
37
    Comp->Play();
38
    // ✗ bAutoDestroy = false（默认）→ 播放完毕组件仍在内存中
39
    //   场景中有 100+ 个"已播放完毕但未销毁"的 AudioComponent —— 内存泄漏
40
}
41
// ✓ Comp->bAutoDestroy = true;  // 播放完自动销毁
42

43
// ===== 陷阱 #5：MetaSounds 参数名大小写不匹配 =====
44
void BadMetaSoundParam(UAudioComponent* Comp)
45
{
46
    // ✗ MetaSound 图中定义的 Input 节点名是 "EngineRPM"（精确大小写）
47
    //   但代码中写的是 "engineRPM" 或 "EngineRpm"
48
    //   → SetFloatParameter 静默失败——参数不生效，无任何警告
49
    Comp->SetFloatParameter(FName(TEXT("engineRPM")), 5000.0f);
50
}
51
// ✓ 参数名必须与 MetaSound Input 节点名称完全一致（包括大小写）
52
// ✓ 最佳实践：项目中定义 FName 常量统一管理
53
//   namespace MetaSoundParams { const FName EngineRPM(TEXT("EngineRPM")); }
54

55
// ===== 陷阱 #6：Occlusion 阻塞 SoundCue 的 Attenuation 节点 =====
56
// 当音频 Source 的 Attenuation → Occlusion 设置勾选了
57
// "Use Complex Collision for Occlusion" 时，如果场景碰撞体是 Complex Mesh
58
// → 每帧 Occlusion 检测消耗惊人（对 10000 面的 Mesh 做射线检测）
59
// ✓ 为 Occlusion 射线检测单独设置简单碰撞通道，或关闭 Complex Collision 选项

1
Q: "MetaSounds 和 SoundCue 的核心区别？各自适用什么场景？"
2
A: SoundCue 是传统节点编辑器——通过连线组织 WavePlayer/Random/Mixer 等固定节点，
3
   做简单的声音播放逻辑。MetaSounds 是 UE5 的新一代可编程音频源——
4
   有完整的参数系统（Float/Bool/Int/Trigger/Wave/String）、支持 Generator（无 .wav 合成）、
5
   允许条件分支和运行时实时参数控制。
6
   简单音效（枪声、UI 点击）用 SoundCue → 简单够用。
7
   复杂音效（动态引擎声、实时参数驱动的音频合成）用 MetaSounds → 灵活强大。
8

9
Q: "Submix 是什么？和 AudioBus 的区别？"
10
A: Submix 是音频分类的"DSP 后处理管线"——SFX/Music/Voice 各自独立的混响/均衡/压缩链。
11
   AudioBus 是"运行时音频数据路由管道"——将音频输出重定向到总线，供其他系统（UI 可视化、
12
   音频分析、自定义 DSP）读取或再处理。
13
   Submix = 声音按类别做效果（所有枪声加混响）。
14
   AudioBus = 声音数据流到另一个地方用（音乐包络驱动灯光）。
15

16
Q: "HRTF 空间化是什么原理？和普通 Stereo 的区别？"
17
A: 普通 Stereo 通过左右声道音量差判断方向——只能分辨左右，无法分辨前后上下。
18
   HRTF 用头部传递函数模拟声波绕过头部和耳廓的物理路径——一对滤波器复现
19
   时间差（ITD）+ 音量差（ILD）+ 频谱变化 → 大脑被"欺骗"感知到精确 3D 定位。
20
   一副普通耳机就能听到上下左右前后。但必须在耳机上使用——扬声器会破坏双耳线索。