feat(resource-kit): 添加 ResourceSystem 和 SceneResourceLoader 实现场景级资源管理

2026-03-12 17:44:56 +08:00
parent 49c71fa39d
commit 622b12aa04
5 changed files with 310 additions and 114 deletions
@@ -0,0 +1,134 @@
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEngine.ResourceManagement.AsyncOperations;
+using Object = UnityEngine.Object;
+
+namespace AibisDream.Framework
+{
+    /// <summary>
+    /// 资源加载系统静态门面。管理 Persistent / Scene 两级 Loader，提供面向业务的统一 API。
+    /// 调用方可通过 LoadAsync（自动路由）、LoadPersistentAsync（显式持久化）、LoadSceneAsync（显式场景级）选择目标。
+    /// </summary>
+    public static class ResourceSystem
+    {
+        private static SceneResourceLoader _persistentLoader;
+        private static SceneResourceLoader _sceneLoader;
+
+        #region Loader Registration
+
+        public static void RegisterPersistentLoader(SceneResourceLoader loader)
+        {
+            if (_persistentLoader != null && _persistentLoader != loader)
+                Debug.LogWarning("[ResourceSystem] Replacing existing persistent loader.");
+            _persistentLoader = loader;
+        }
+
+        public static void UnregisterPersistentLoader(SceneResourceLoader loader)
+        {
+            if (_persistentLoader == loader)
+                _persistentLoader = null;
+        }
+
+        public static void RegisterSceneLoader(SceneResourceLoader loader)
+        {
+            if (_sceneLoader != null && _sceneLoader != loader)
+                Debug.LogWarning("[ResourceSystem] Replacing existing scene loader. Was the previous scene properly unloaded?");
+            _sceneLoader = loader;
+        }
+
+        public static void UnregisterSceneLoader(SceneResourceLoader loader)
+        {
+            if (_sceneLoader == loader)
+                _sceneLoader = null;
+        }
+
+        public static void UnregisterSceneLoader()
+        {
+            _sceneLoader = null;
+        }
+
+        #endregion
+
+        #region Loader Access
+
+        public static SceneResourceLoader PersistentLoader => _persistentLoader;
+        public static SceneResourceLoader CurrentSceneLoader => _sceneLoader;
+
+        private static SceneResourceLoader ActiveLoader
+        {
+            get
+            {
+                if (_sceneLoader != null) return _sceneLoader;
+                if (_persistentLoader != null) return _persistentLoader;
+                Debug.LogError("[ResourceSystem] No loader registered. Ensure a SceneResourceLoader exists in the scene.");
+                return null;
+            }
+        }
+
+        #endregion
+
+        #region Auto-Routed API (uses ActiveLoader: scene first, falls back to persistent)
+
+        public static AsyncOperationHandle<T> LoadAsync<T>(string key) where T : Object
+            => ActiveLoader.LoadAsync<T>(key);
+
+        public static void LoadAsync<T>(string key, Action<T> onComplete, Action<string> onError = null) where T : Object
+            => ActiveLoader.LoadAsync(key, onComplete, onError);
+
+        #endregion
+
+        #region Persistent Loader API
+
+        public static AsyncOperationHandle<T> LoadPersistentAsync<T>(string key) where T : Object
+        {
+            EnsureLoader(_persistentLoader, "persistent");
+            return _persistentLoader.LoadAsync<T>(key);
+        }
+
+        public static void LoadPersistentAsync<T>(string key, Action<T> onComplete, Action<string> onError = null)
+            where T : Object
+        {
+            EnsureLoader(_persistentLoader, "persistent");
+            _persistentLoader.LoadAsync(key, onComplete, onError);
+        }
+
+        #endregion
+
+        #region Scene Loader API
+
+        public static AsyncOperationHandle<T> LoadSceneAsync<T>(string key) where T : Object
+        {
+            EnsureLoader(_sceneLoader, "scene");
+            return _sceneLoader.LoadAsync<T>(key);
+        }
+
+        public static void LoadSceneAsync<T>(string key, Action<T> onComplete, Action<string> onError = null)
+            where T : Object
+        {
+            EnsureLoader(_sceneLoader, "scene");
+            _sceneLoader.LoadAsync(key, onComplete, onError);
+        }
+
+        #endregion
+
+        #region Preload & Release
+
+        public static AsyncOperationHandle<IList<T>> PreloadByLabel<T>(string label) where T : Object
+            => ActiveLoader.PreloadByLabel<T>(label);
+
+        public static void EarlyRelease(string key)
+            => ActiveLoader.EarlyRelease(key);
+
+        public static void EarlyRelease<T>(AsyncOperationHandle<T> handle)
+            => ActiveLoader.EarlyRelease(handle);
+
+        #endregion
+
+        private static void EnsureLoader(SceneResourceLoader loader, string loaderName)
+        {
+            if (loader == null)
+                Debug.LogError($"[ResourceSystem] No {loaderName} loader registered.");
+        }
+    }
+}