Gen_Hack-and-Slash-Roguelite/Client/Assets/Scripts/Base/Launcher.cs

using System.Collections;
using System.Collections.Generic; // 提供List等通用集合类型
using Logging; // 提供日志记录功能
using Managers; // 提供管理器接口和实现
using TMPro; // TextMeshPro文本组件命名空间
using UnityEngine; // Unity引擎核心命名空间
using UnityEngine.SceneManagement; // 场景管理命名空间

namespace Base
{
    /// <summary>
    /// <c>Launcher</c> 类负责管理游戏的初始化加载流程，包括管理器加载、进度条显示和场景切换。
    /// </summary>
    /// <remarks>
    /// <para>请注意：虽然此处的 <c>progressBar</c> 变量类型被声明为 <c>Gradient</c>，
    /// 但其在代码中的使用方式（如访问 <c>color1</c>, <c>color2</c> 属性和调用 <c>Refresh()</c> 方法）
    /// 强烈暗示它应引用一个具有类似 API 的自定义进度条组件，例如 <c>CustomProgressBar</c>。</para>
    /// <para>如果您使用的是标准 <c>UnityEngine.UI.Image</c> 或其他组件来显示进度，
    /// 则 <c>Progress</c> 和 <c>Opacity</c> 属性的实现逻辑需要根据实际组件的 API 进行大幅修改。</para>
    /// </remarks>
    public class Launcher : MonoBehaviour
    {
        /// <summary>
        /// 加载界面UI的根游戏对象。
        /// </summary>
        public GameObject loadingUI;

        /// <summary>
        /// 用于显示加载进度的自定义进度条组件。
        /// <para>请参阅类注释以了解其声明类型与预期API的差异。</para>
        /// </summary>
        public Gradient progressBar;

        /// <summary>
        /// 用于显示当前加载步骤描述的文本组件。
        /// </summary>
        public TMP_Text describeText;

        /// <summary>
        /// 进度条每个加载步骤的平滑过渡时间（秒）。
        /// </summary>
        public float duration = 0.5f;

        /// <summary>
        /// 加载完成后UI元素渐隐的时间（秒）。
        /// </summary>
        public float fadeDuration = 2f;

        private float _currentProgressValue = 0f; // 实际的当前进度值（在0到1之间）
        private Color _initialTextColor; // 描述文本的原始颜色，用于渐隐效果
        private Color _initialProgressBarColor1; // 进度条颜色1的原始值，用于渐变
        private Color _initialProgressBarColor2; // 进度条颜色2的原始值，用于渐变

        /// <summary>
        /// 存储所有需要在启动时加载和在重载时清理的管理器实例列表。
        /// </summary>
        private List<ILaunchManager> _managersToLoad;

        /// <summary>
        /// 获取或设置加载进度值，范围为0到1。
        /// 设置此属性将更新进度条的视觉显示和颜色。
        /// </summary>
        public float Progress
        {
            set
            {
                // 确保进度值在0到1之间，提高系统健壮性
                _currentProgressValue = Mathf.Clamp01(value);

                if (progressBar)
                {
                    // 根据进度值平滑改变进度条的颜色
                    if (_currentProgressValue < 0.5f)
                    {
                        // 前半段：color2 从初始色渐变到白色
                        progressBar.color2 = Color.Lerp(_initialProgressBarColor2, Color.white, _currentProgressValue * 2);
                    }
                    else
                    {
                        progressBar.color2 = Color.white;
                        // 后半段：color2 保持白色，color1 从初始色渐变到白色
                        progressBar.color1 = Color.Lerp(_initialProgressBarColor1, Color.white, (_currentProgressValue - 0.5f) * 2);
                    }
                    // 通知自定义进度条组件更新显示。
                    // 注意：UnityEngine.Gradient 作为数据结构没有 Refresh() 方法，
                    // 此调用表明 progressBar 实际上预期是一个具有此方法的自定义组件。
                    progressBar.Refresh();
                }
            }
            get => _currentProgressValue;
        }

        /// <summary>
        /// 获取或设置UI元素的整体不透明度，范围0（完全透明）到1（完全不透明）。
        /// 设置此属性将更新进度条和描述文本的透明度。
        /// </summary>
        public float Opacity
        {
            set
            {
                var alpha = Mathf.Clamp01(value); // 确保透明度值在0到1之间

                if (progressBar)
                {
                    // 更新进度条颜色的透明度
                    Color c1 = progressBar.color1;
                    c1.a = alpha;
                    progressBar.color1 = c1;

                    Color c2 = progressBar.color2;
                    c2.a = alpha;
                    progressBar.color2 = c2;

                    // 通知自定义进度条组件更新显示。
                    // 注意：UnityEngine.Gradient 作为数据结构没有 Refresh() 方法，
                    // 此调用表明 progressBar 实际上预期是一个具有此方法的自定义组件。
                    progressBar.Refresh();
                }

                if (describeText)
                {
                    // 更新描述文本颜色的透明度
                    // 渐隐时，描述文本的透明度在 Opacity > 0.5f 时才开始从0渐变到其原始透明度
                    var textAlpha = alpha > 0.5f ? Mathf.Lerp(0f, _initialTextColor.a, (alpha - 0.5f) * 2) : 0f;
                    describeText.color = new Color(_initialTextColor.r, _initialTextColor.g, _initialTextColor.b, textAlpha);
                }
            }
        }

        /// <summary>
        /// 当脚本实例被启用时调用一次。
        /// 用于初始化管理器列表并缓存UI元素的初始颜色。
        /// </summary>
        private void Awake()
        {
            // 在 Awake 中初始化管理器列表，确保在 Start 之前完成所有管理器实例的注册
            _managersToLoad = new List<ILaunchManager>
            {
                new LoggerManagerWrapper(), // Unity日志的包装器
                DefineManager.Instance,
                PackagesImageManager.Instance,
                TileManager.Instance,
                AffiliationManager.Instance,
                ItemResourceManager.Instance,
                EventManager.Instance,
                AudioManager.Instance,
            };

            // 缓存UI的初始颜色，以便后续操作（如渐隐）或重置
            _initialTextColor = describeText != null ? describeText.color : Color.white; // 如果为空，则使用默认值
            
            if (progressBar != null)
            {
                _initialProgressBarColor1 = progressBar.color1;
                _initialProgressBarColor2 = progressBar.color2;
            }
            else
            {
                // 警告日志：自定义进度条组件未赋值给启动器。
                Debug.LogWarning("自定义进度条组件未赋值给启动器，进度条可能无法正常显示。");
            }
        }

        /// <summary>
        /// 在Awake方法之后、首次帧更新之前调用。
        /// 用于判断是否需要执行完整的加载流程，并根据需要启动加载或隐藏加载UI。
        /// </summary>
        private void Start()
        {
            // 如果 Program.Instance.needLoad 为 false，表示游戏已加载或不需要重新加载，直接隐藏加载UI
            if (!Program.Instance.needLoad)
            {
                loadingUI.SetActive(false);
                return;
            }

            // 如果需要加载，则先清理所有管理器（用于重载或确保干净启动），再启动加载流程
            ClearAllManagers();

            // 初始化游戏设置
            Setting.Instance.Init();

#if !DEBUG
            // 在非DEBUG模式下，从游戏设置中获取加载和渐隐的持续时间
            duration = Base.Setting.Instance.CurrentSettings.progressStepDuration;
            fadeDuration = Base.Setting.Instance.CurrentSettings.exitAnimationDuration;
#endif
            Load(); // 启动加载流程（内部会调用LoadAllManagers）
            Program.Instance.needLoad = false; // 加载完成后重置加载标志
        }

        /// <summary>
        /// 启动游戏的加载流程。
        /// 该方法会激活加载UI，重置进度与透明度，并启动所有管理器的异步加载协程。
        /// </summary>
        public void Load()
        {
            loadingUI.SetActive(true); // 激活加载UI
            Progress = 0f; // 将进度重置为0
            Opacity = 1f; // 将UI透明度重置为完全不透明
            StartCoroutine(LoadAllManagers());
        }

        /// <summary>
        /// 清理所有管理器，然后重新加载游戏数据。
        /// 此方法适用于游戏重载、场景切换后需要重新初始化所有数据的情况。
        /// </summary>
        public void Reload()
        {
            // 日志：正在执行所有管理器的完整重新加载...
            Debug.Log("<color=yellow>正在执行所有管理器的完整重新加载...</color>");
            StopAllCoroutines(); // 停止当前所有正在运行的加载协程，避免冲突
            ClearAllManagers(); // 清理所有管理器数据
            Load(); // 重新加载游戏数据
        }

        /// <summary>
        /// 遍历所有已注册的管理器，并安全地调用它们的 Clear 方法以释放资源或重置状态。
        /// </summary>
        private void ClearAllManagers()
        {
            foreach (var manager in _managersToLoad)
            {
                try
                {
                    manager.Clear();
                }
                catch (System.Exception ex)
                {
                    // 错误日志：清理管理器时发生异常。
                    Debug.LogError($"<color=red>清理管理器 '{manager.StepDescription}' 时出错:</color> {ex.Message}\n{ex.StackTrace}");
                }
            }
        }

        /// <summary>
        /// 协程：按顺序加载所有注册的管理器。
        /// 该方法会在加载过程中更新描述文本、平滑过渡进度条，并安全初始化每个管理器。
        /// </summary>
        /// <returns>一个 <see cref="IEnumerator"/>，用于协程。</returns>
        private IEnumerator LoadAllManagers()
        {
            for (var i = 0; i < _managersToLoad.Count; i++)
            {
                var manager = _managersToLoad[i];

                // 更新描述文本，显示当前正在加载的管理器步骤描述
                if (describeText != null)
                {
                    describeText.text = manager.StepDescription;
                }

                // 计算当前阶段的目标进度值
                var targetProgress = (float)(i + 1) / _managersToLoad.Count;

                // 平滑过渡进度条到下一个目标进度
                yield return SmoothTransitionTo(targetProgress);

                // 初始化对应的管理器，并处理可能发生的异常
                yield return InitializeManagerSafely(manager);

                // yield return new WaitForSeconds(0.1f); // 此行代码可用于模拟每个管理器加载的耗时，默认不启用。
            }

            // 所有管理器加载完成后的处理
            if (describeText != null)
            {
                describeText.text = "加载完成！";
            }
            // 确保进度条最终达到100%
            Progress = 1f;

            // 启动加载UI的渐隐效果
            yield return FadeOutProgressBar();

            // 所有加载和动画结束后，可以考虑卸载加载UI，或跳转到主场景
            // ToScene("MainGameScene"); // 如果有需要，可以在此处调用静态方法跳转到主游戏场景
        }

        /// <summary>
        /// 尝试安全地初始化单个管理器实例，并捕获任何可能发生的异常。
        /// 如果初始化失败，将记录错误日志并更新UI提示。
        /// </summary>
        /// <param name="manager">要初始化的管理器实例。</param>
        /// <returns>一个 <see cref="IEnumerator"/>，用于协程。</returns>
        private IEnumerator InitializeManagerSafely(ILaunchManager manager)
        {
            var initSuccess = false;
            System.Exception initException = null;

            try
            {
                manager.Init(); // 调用管理器的 Init 方法进行初始化
                initSuccess = true;
            }
            catch (System.Exception ex)
            {
                initException = ex; // 捕获初始化过程中抛出的异常
            }

            if (!initSuccess && initException != null)
            {
                // 记录错误日志：初始化管理器时出现错误。
                Debug.LogError($"<color=red>初始化管理器 '{manager.StepDescription}' 时出错:</color> {initException.Message}\n{initException.StackTrace}");
                if (describeText != null)
                {
                    describeText.text = $"{manager.StepDescription} (初始化失败)"; // 更新UI显示失败信息
                }
                // 这里可以添加更复杂的错误处理逻辑，例如显示错误弹窗、记录到特定日志文件或允许用户选择重试。
                // yield break; // 如果错误严重到无法继续，可以选择停止后续加载流程。
            }

            yield return null; // 确保协程继续执行，无论初始化成功与否
        }

        /// <summary>
        /// 协程：平滑地过渡进度条的当前值到指定的目标进度。
        /// 使用 <c>Mathf.SmoothStep</c> 实现自然加速和减速的过渡效果。
        /// </summary>
        /// <param name="targetProgress">目标进度值 (0到1之间)。</param>
        /// <returns>一个 <see cref="IEnumerator"/>，用于协程。</returns>
        private IEnumerator SmoothTransitionTo(float targetProgress)
        {
            var startProgress = _currentProgressValue; // 获取当前进度作为过渡的起始点
            var elapsedTime = 0f;

            while (elapsedTime < duration)
            {
                elapsedTime += Time.deltaTime;
                // 使用 SmoothStep 实现更自然的加速和减速过渡效果
                var t = Mathf.SmoothStep(0f, 1f, elapsedTime / duration);
                Progress = Mathf.Lerp(startProgress, targetProgress, t); // 在起始和目标进度之间插值
                yield return null;
            }

            Progress = targetProgress; // 确保最终进度精确达到目标值
        }

        /// <summary>
        /// 协程：平滑渐隐加载UI的所有元素，使其透明度从完全不透明过渡到完全透明。
        /// </summary>
        /// <returns>一个 <see cref="IEnumerator"/>，用于协程。</returns>
        private IEnumerator FadeOutProgressBar()
        {
            var elapsedTime = 0f;

            while (elapsedTime < fadeDuration)
            {
                elapsedTime += Time.deltaTime;
                // 使用 SmoothStep 实现平滑渐隐
                var t = Mathf.SmoothStep(0f, 1f, elapsedTime / fadeDuration);
                Opacity = 1f - t; // 透明度从 1 线性渐变到 0
                yield return null;
            }

            Opacity = 0f; // 确保最终不透明度为 0
            loadingUI.SetActive(false); // 完全隐藏加载UI
        }

        /// <summary>
        /// 静态方法：加载指定名称的Unity场景。
        /// </summary>
        /// <param name="scene">要加载的场景名称。</param>
        public static void ToScene(string scene)
        {
            SceneManager.LoadScene(scene);
        }
    }
}