引入 BGM 切换+文档初版草稿

Assets/GameMain/Scripts/CustomComponent/CombineComponent.cs

@@ -1,5 +1,6 @@
 using System.Collections.Generic;
 using Event;
+using Sound;
 using UI;
 using UnityEngine;
 using UnityEngine.Events;
@@ -53,6 +54,15 @@ namespace CustomComponent
         /// </summary>
         [SerializeField] private UnityEvent _onPuzzleCompleted = new UnityEvent();
 
+        [SerializeField] [Tooltip("开始拼装时是否自动切换 BGM。")]
+        private bool _autoSwitchBgmOnStart = true;
+
+        [SerializeField] [Tooltip("拼装阶段 BGM Id。")]
+        private int _combineBgmId = 5;
+
+        [SerializeField] [Tooltip("拼装结束后是否自动恢复被打断的 BGM（带进度）。")]
+        private bool _autoRestoreInterruptedBgm = true;
+
         #endregion
 
         #region Runtime State
@@ -105,6 +115,10 @@ namespace CustomComponent
         /// </summary>
         private int _nextLevelStructureIndex = 0;
 
+        private bool _hasInterruptedBgm = false;
+        private int _interruptedBgmId = 0;
+        private float _interruptedBgmTimeSeconds = 0f;
+
         #endregion
 
         #region Public Query
@@ -139,6 +153,16 @@ namespace CustomComponent
             }
         }
 
+        private void Start()
+        {
+            GameEntry.Event.Subscribe(CombineCompletedEventArgs.EventId, OnCombineCompleted);
+        }
+
+        private void OnDestroy()
+        {
+            GameEntry.Event.Unsubscribe(CombineCompletedEventArgs.EventId, OnCombineCompleted);
+        }
+
         #endregion
 
         #region Level Lifecycle
@@ -167,6 +191,7 @@ namespace CustomComponent
                 return null;
             }
 
+            SwitchToCombineBgm();
             _nextLevelStructureIndex++;
             return serialId;
         }
@@ -178,6 +203,7 @@ namespace CustomComponent
         {
             _formController?.CloseUI();
             ClearRuntimeContext();
+            RestoreInterruptedBgmIfNeeded();
         }
 
         #endregion
@@ -435,6 +461,53 @@ namespace CustomComponent
             _isPaused = false;
         }
 
+        private void OnCombineCompleted(object sender, GameFramework.Event.GameEventArgs e)
+        {
+            if (!(e is CombineCompletedEventArgs))
+            {
+                return;
+            }
+
+            RestoreInterruptedBgmIfNeeded();
+        }
+
+        private void SwitchToCombineBgm()
+        {
+            if (!_autoSwitchBgmOnStart || _combineBgmId <= 0 || GameEntry.Sound == null)
+            {
+                return;
+            }
+
+            if (!_hasInterruptedBgm && GameEntry.Sound.TryGetCurrentBgmSnapshot(out int bgmId, out float timeSeconds))
+            {
+                if (bgmId != _combineBgmId)
+                {
+                    _hasInterruptedBgm = true;
+                    _interruptedBgmId = bgmId;
+                    _interruptedBgmTimeSeconds = Mathf.Max(0f, timeSeconds);
+                }
+            }
+
+            GameEntry.Sound.PlayBGM(_combineBgmId);
+        }
+
+        private void RestoreInterruptedBgmIfNeeded()
+        {
+            if (!_autoRestoreInterruptedBgm || !_hasInterruptedBgm || GameEntry.Sound == null)
+            {
+                return;
+            }
+
+            if (_interruptedBgmId > 0)
+            {
+                GameEntry.Sound.PlayBGM(_interruptedBgmId, _interruptedBgmTimeSeconds);
+            }
+
+            _hasInterruptedBgm = false;
+            _interruptedBgmId = 0;
+            _interruptedBgmTimeSeconds = 0f;
+        }
+
         /// <summary>
         /// 获取当前拖拽根节点。
         /// </summary>

Assets/GameMain/Scripts/CustomComponent/StoryDirective/StoryChangeBgmDirectiveAsset.cs

@@ -0,0 +1,23 @@
+using UnityEngine;
+
+namespace CustomComponent
+{
+    [CreateAssetMenu(menuName = "Story/Directive/Change BGM", fileName = "Directive_ChangeBGM")]
+    public sealed class StoryChangeBgmDirectiveAsset : StoryDirectiveAsset
+    {
+        [SerializeField] [Tooltip("BGM 配置表 Id；<=0 表示停止当前 BGM。")]
+        private int _bgmId = 0;
+
+        public override string ActionName => "ChangeBGM";
+
+        public override void Execute(StoryDirectorComponent director)
+        {
+            if (director == null)
+            {
+                return;
+            }
+
+            director.ExecuteChangeBgm(_bgmId);
+        }
+    }
+}

Assets/GameMain/Scripts/CustomComponent/StoryDirective/StoryChangeBgmDirectiveAsset.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: b2f756304e6e46b48c7cabf5887971fc
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Assets/GameMain/Scripts/CustomComponent/StoryDirectorComponent.cs

@@ -1,6 +1,7 @@
 using System.Collections;
 using System.Collections.Generic;
 using Event;
+using Sound;
 using UI;
 using UnityEngine;
 using UnityGameFramework.Runtime;
@@ -273,6 +274,27 @@ namespace CustomComponent
             }
         }
 
+        public void ExecuteChangeBgm(int bgmId)
+        {
+            if (GameEntry.Sound == null)
+            {
+                Log.Warning("StoryDirector change BGM failed. Sound component is missing.");
+                return;
+            }
+
+            if (bgmId <= 0)
+            {
+                GameEntry.Sound.StopMusic();
+                return;
+            }
+
+            int? serialId = GameEntry.Sound.PlayBGM(bgmId);
+            if (!serialId.HasValue)
+            {
+                Log.Warning("StoryDirector change BGM failed. bgmId={0}", bgmId.ToString());
+            }
+        }
+
         public void ExecuteEndChapter(int chapterId)
         {
             int finalChapterId = chapterId > 0