refactor(ModSettings): enhance prewarming and entry management for mod settings UI

- Introduced a new ModSettingsReusableEntryNodePool to manage reusable UI components, improving memory efficiency and performance.
- Implemented background prewarming for mod settings to reduce initial load times and enhance user experience.
- Updated various controls to support dynamic binding and clear action handling, ensuring better responsiveness in the UI.
- Refactored existing methods to streamline the creation and management of mod settings entries, enhancing maintainability and clarity.

Author: BAKAOLC

Settings/Integration/Patches/ModSettingsUiPatches.cs

@@ -120,11 +120,16 @@ public class SettingsScreenModSettingsButtonPatch : IPatchMethod
         private const string GeneralSettingsResizeHookMeta = "ritsulib_general_settings_content_resize_hook";
 
         private const string PrewarmScheduledMeta = "ritsulib_mod_settings_prewarm_scheduled";
+        private const double PrewarmInitialDelaySeconds = 3.0d;
+        private const int PrewarmFrameDelay = 1;
 
         private const string EntryLineNodeName = "RitsuLibModSettings";
 
         private const string EntryDividerNodeName = "RitsuLibModSettingsDivider";
 
+        private static readonly ConditionalWeakTable<NSettingsScreen, ModSettingsMirrorPrewarmSession> PrewarmSessions =
+            new();
+
         /// <inheritdoc />
         public static string PatchId => "ritsulib_mod_settings_button";
 
@@ -157,7 +162,7 @@ public static void Postfix(NSettingsScreen __instance)
             try
             {
                 var line = EnsureEntryPoint(__instance);
-                RefreshState(line);
+                RefreshState(line, __instance);
                 var generalPanel = __instance.GetNode<NSettingsPanel>("%GeneralSettings");
                 ScheduleRefreshGeneralSettingsPanelSize(generalPanel);
                 if (generalPanel.Content is { } generalVBox)
@@ -175,51 +180,100 @@ public static void Postfix(NSettingsScreen __instance)
         ///     Pre-warms the mod settings UI while the user is still on the vanilla settings screen — before they
         ///     click "Mod Settings (RitsuLib)". The first open otherwise runs a concentrated one-time
         ///     initialization (reflection-based mirror registration, sidebar build, first page build) all at once,
-        ///     producing a visible stall. The work is spread across idle frames so the vanilla screen does not
-        ///     stall either, and is scheduled once per screen instance.
+        ///     producing a visible stall. Reflection and data registration run on a background worker; only Godot node
+        ///     creation and UI refresh stay on the main thread.
         ///     在用户仍处于原版设置界面时(即点击 “Mod Settings (RitsuLib)” 之前)预热 mod 设置 UI。否则首次打开会一次性执行
-        ///     集中的一次性初始化(基于反射的镜像注册、侧边栏构建、首页构建),造成可见卡顿。该工作被分散到多个空闲帧,使原版界面
-        ///     也不卡,并对每个界面实例只调度一次。
+        ///     集中的一次性初始化(基于反射的镜像注册、侧边栏构建、首页构建),造成可见卡顿。反射和数据注册在后台线程执行；
+        ///     只有 Godot 节点创建和 UI 刷新留在主线程。
         /// </summary>
         private static void TrySchedulePrewarm(NSettingsScreen screen)
         {
             if (screen.HasMeta(PrewarmScheduledMeta))
                 return;
             screen.SetMeta(PrewarmScheduledMeta, true);
-            Callable.From(() => PrewarmStep(screen, 0)).CallDeferred();
+            ScheduleInitialPrewarmStep(screen);
         }
 
-        private static void PrewarmStep(NSettingsScreen screen, int step)
+        private static void PrewarmStep(NSettingsScreen screen)
         {
             if (!GodotObject.IsInstanceValid(screen))
                 return;
 
             try
             {
-                switch (step)
+                var session = PrewarmSessions.GetValue(screen, CreatePrewarmSession);
+
+                if (!session.Resume())
                 {
-                    case 0:
-                        RitsuLibModSettingsBootstrap.EnsureFrameworkPagesRegistered();
-                        break;
-                    case 1:
-                        ModSettingsMirrorRegistrarBootstrap.TryRegisterMirroredPages();
-                        RitsuLibModSettingsBootstrap.RefreshDynamicPages();
-                        break;
-                    case 2:
-                    {
-                        var stack = screen.GetAncestorOfType<NSubmenuStack>();
-                        if (stack != null)
-                            ModSettingsSubmenuPatch.Submenus.GetValue(stack, ModSettingsSubmenuPatch.CreateSubmenu);
-                        return;
-                    }
+                    SchedulePrewarmStep(screen, PrewarmFrameDelay);
+                    return;
                 }
+
+                RitsuLibModSettingsBootstrap.RefreshDynamicPages();
+                ScheduleSubmenuPrewarm(screen);
+                PrewarmSessions.Remove(screen);
+            }
+            catch (Exception ex)
+            {
+                PrewarmSessions.Remove(screen);
+                RitsuLibFramework.Logger.Warn($"[Settings] Mod settings prewarm failed: {ex.Message}");
+            }
+        }
+
+        private static void SchedulePrewarmStep(NSettingsScreen screen, int delayFrames)
+        {
+            if (delayFrames <= 0)
+            {
+                Callable.From(() => PrewarmStep(screen)).CallDeferred();
+                return;
+            }
+
+            Callable.From(() => SchedulePrewarmStep(screen, delayFrames - 1)).CallDeferred();
+        }
+
+        private static void ScheduleSubmenuPrewarm(NSettingsScreen screen)
+        {
+            if (!GodotObject.IsInstanceValid(screen))
+                return;
+
+            Callable.From(() => TryCreateSubmenuForPrewarm(screen)).CallDeferred();
+        }
+
+        private static void TryCreateSubmenuForPrewarm(NSettingsScreen screen)
+        {
+            if (!GodotObject.IsInstanceValid(screen))
+                return;
+
+            try
+            {
+                var stack = screen.GetAncestorOfType<NSubmenuStack>();
+                if (stack == null)
+                    return;
+
+                var submenu = ModSettingsSubmenuPatch.Submenus.GetValue(stack, ModSettingsSubmenuPatch.CreateSubmenu);
+                _ = submenu.WaitForFirstPageContentPrewarmedAsync();
             }
             catch (Exception ex)
             {
-                RitsuLibFramework.Logger.Warn($"[Settings] Mod settings prewarm step {step} failed: {ex.Message}");
+                RitsuLibFramework.Logger.Warn($"[Settings] Mod settings submenu prewarm failed: {ex.Message}");
+            }
+        }
+
+        private static void ScheduleInitialPrewarmStep(NSettingsScreen screen)
+        {
+            if (screen.GetTree() is not { } tree)
+            {
+                SchedulePrewarmStep(screen, PrewarmFrameDelay);
+                return;
             }
 
-            Callable.From(() => PrewarmStep(screen, step + 1)).CallDeferred();
+            var timer = tree.CreateTimer(PrewarmInitialDelaySeconds);
+            timer.Timeout += () => SchedulePrewarmStep(screen, 0);
+        }
+
+        private static ModSettingsMirrorPrewarmSession CreatePrewarmSession(NSettingsScreen _)
+        {
+            return ModSettingsMirrorRegistrarBootstrap.CreatePrewarmSession();
         }
 
         private static MarginContainer EnsureEntryPoint(NSettingsScreen screen)
@@ -251,6 +305,7 @@ private static MarginContainer EnsureEntryPoint(NSettingsScreen screen)
 
             void OpenSubmenu()
             {
+                SchedulePrewarmStep(screen, 0);
                 screen.GetAncestorOfType<NSubmenuStack>()?.PushSubmenuType(typeof(RitsuModSettingsSubmenu));
             }
         }
@@ -305,7 +360,7 @@ private static void ScheduleRefreshGeneralSettingsPanelSize(NSettingsPanel panel
             Callable.From(() => RefreshPanelSize(panel)).CallDeferred();
         }
 
-        private static void RefreshState(MarginContainer line)
+        private static void RefreshState(MarginContainer line, NSettingsScreen screen)
         {
             line.Visible = true;
 

Settings/ModSettings/Mirrors/ModSettingsMirrorRegistrarBootstrap.cs

@@ -2,6 +2,15 @@ namespace STS2RitsuLib.Settings
 {
     internal static class ModSettingsMirrorRegistrarBootstrap
     {
+        private static volatile bool _backgroundPrewarmComplete;
+
+        public static bool IsBackgroundPrewarmComplete => _backgroundPrewarmComplete;
+
+        internal static void MarkBackgroundPrewarmComplete()
+        {
+            _backgroundPrewarmComplete = true;
+        }
+
         public static int TryRegisterMirroredPages()
         {
             var added = 0;
@@ -12,5 +21,117 @@ public static int TryRegisterMirroredPages()
             added += BaseLibToRitsuGeneratedMirrorSource.TryRegisterMirroredPages();
             return added;
         }
+
+        public static ModSettingsMirrorPrewarmSession CreatePrewarmSession()
+        {
+            return new([
+                new BackgroundPrewarmWork(() => BaseLibMirrorSource.TryRegisterMirroredPages()),
+                new BackgroundPrewarmWork(() => ModConfigMirrorSource.TryRegisterMirroredPages()),
+                new BackgroundPrewarmWork(RuntimeInteropMirrorSource.TryRegisterMirroredPages),
+                new BackgroundPrewarmWork(RuntimeReflectionMirrorSource.TryRegisterMirroredPages),
+                new BackgroundPrewarmWork(() => BaseLibToRitsuGeneratedMirrorSource.TryRegisterMirroredPages()),
+            ]);
+        }
+
+        private sealed class BackgroundPrewarmWork(Func<int> register) : IModSettingsMirrorPrewarmWork
+        {
+            private volatile bool _complete;
+            private Exception? _error;
+            private bool _reportedFailure;
+            private int _result;
+            private bool _started;
+            private Thread? _thread;
+
+            public bool IsComplete => _complete;
+
+            public int Resume()
+            {
+                if (!_started)
+                    StartWorker();
+
+                if (!_complete)
+                    return 0;
+
+                if (_error == null) return _result;
+                if (_reportedFailure) return 0;
+                _reportedFailure = true;
+                RitsuLibFramework.Logger.Warn(
+                    $"[Settings] Mod settings background prewarm failed: {_error.Message}");
+
+                return 0;
+            }
+
+            private void StartWorker()
+            {
+                _started = true;
+                _thread = new(WorkerMain)
+                {
+                    IsBackground = true,
+                    Name = "RitsuLib Mod Settings Prewarm",
+                    Priority = ThreadPriority.Lowest,
+                };
+                _thread.Start();
+            }
+
+            private void WorkerMain()
+            {
+                try
+                {
+                    try
+                    {
+                        Thread.CurrentThread.Priority = ThreadPriority.Lowest;
+                    }
+                    catch
+                    {
+                        // Best effort only.
+                    }
+
+                    _result = register();
+                }
+                catch (Exception ex)
+                {
+                    _error = ex;
+                }
+                finally
+                {
+                    _complete = true;
+                }
+            }
+        }
+    }
+
+    internal interface IModSettingsMirrorPrewarmWork
+    {
+        bool IsComplete { get; }
+
+        int Resume();
+    }
+
+    internal sealed class ModSettingsMirrorPrewarmSession(IReadOnlyList<IModSettingsMirrorPrewarmWork> workItems)
+    {
+        private int _workIndex;
+
+        public int Added { get; private set; }
+
+        public bool IsComplete => _workIndex >= workItems.Count;
+
+        public bool Resume()
+        {
+            if (IsComplete)
+                return true;
+
+            while (_workIndex < workItems.Count)
+            {
+                var work = workItems[_workIndex];
+                Added += work.Resume();
+                if (!work.IsComplete)
+                    return false;
+
+                _workIndex++;
+            }
+
+            ModSettingsMirrorRegistrarBootstrap.MarkBackgroundPrewarmComplete();
+            return true;
+        }
     }
 }