chore(release): merge dev into main for v0.2.21

Author: BAKAOLC

Audio/FmodStudioDeferredBankRegistration.cs

@@ -1,97 +1,91 @@
 namespace STS2RitsuLib.Audio
 {
     /// <summary>
-    ///     Convenience helpers for loading FMOD Studio banks after the game has finished deferred initialization.
+    ///     Queues FMOD Studio bank and GUID mapping paths until <see cref="DeferredInitializationCompletedEvent" />,
+    ///     then loads them in one batch with a single <see cref="FmodStudioServer.TryWaitForAllLoads" />.
     /// </summary>
     public static class FmodStudioDeferredBankRegistration
     {
+        private static readonly Lock Gate = new();
+        private static readonly HashSet<string> PendingBanks = new(StringComparer.Ordinal);
+        private static readonly HashSet<string> PendingGuidFiles = new(StringComparer.Ordinal);
+        private static bool _flushHookRegistered;
+
         /// <summary>
-        ///     Schedules loading one FMOD Studio bank and optional GUID path mappings once, after
-        ///     <see cref="STS2RitsuLib.DeferredInitializationCompletedEvent" /> (or immediately if that milestone already
-        ///     occurred).
+        ///     Queues a bank path to load after deferred initialization (deduplicated).
         /// </summary>
-        /// <param name="bankResourcePath">
-        ///     Godot resource path to the <c>.bank</c> file (for example <c>res://Mod/audios/x.bank</c>
-        ///     ).
-        /// </param>
-        /// <param name="studioGuidMappingsResourcePath">
-        ///     Optional <c>GUIDs.txt</c>-style resource path; pass <c>null</c> when the bank does not need addon GUID mapping.
-        /// </param>
-        /// <param name="waitForAllLoadsAfterBanks">
-        ///     When true, calls <see cref="FmodStudioServer.TryWaitForAllLoads" /> after all banks in this batch have been
-        ///     submitted.
-        /// </param>
-        /// <returns>
-        ///     Subscription token; it is disposed automatically after the deferred load attempt finishes.
-        /// </returns>
-        public static IDisposable QueueLoadBankAfterDeferredInitialization(
-            string bankResourcePath,
-            string? studioGuidMappingsResourcePath = null,
-            bool waitForAllLoadsAfterBanks = true)
+        public static void RegisterBank(string resourcePath)
         {
-            ArgumentException.ThrowIfNullOrWhiteSpace(bankResourcePath);
+            if (string.IsNullOrWhiteSpace(resourcePath))
+                return;
 
-            return QueueLoadBanksAfterDeferredInitialization(
-                [bankResourcePath],
-                studioGuidMappingsResourcePath,
-                waitForAllLoadsAfterBanks);
+            lock (Gate)
+            {
+                PendingBanks.Add(resourcePath.Trim());
+                EnsureFlushHookRegisteredLocked();
+            }
         }
 
         /// <summary>
-        ///     Schedules loading multiple FMOD Studio banks (in order) and optional GUID path mappings once, after
-        ///     <see cref="STS2RitsuLib.DeferredInitializationCompletedEvent" /> (or immediately if that milestone already
-        ///     occurred).
+        ///     Queues a GUID mapping file for <see cref="FmodStudioServer.TryLoadStudioGuidMappings" /> after deferred
+        ///     initialization (deduplicated).
         /// </summary>
-        /// <param name="bankResourcePaths">Non-empty sequence of Godot resource paths to <c>.bank</c> files.</param>
-        /// <param name="studioGuidMappingsResourcePath">
-        ///     Optional <c>GUIDs.txt</c>-style resource path; pass <c>null</c> when no GUID table should be applied.
-        /// </param>
-        /// <param name="waitForAllLoadsAfterBanks">
-        ///     When true, calls <see cref="FmodStudioServer.TryWaitForAllLoads" /> after all banks in this batch have been
-        ///     submitted.
-        /// </param>
-        /// <returns>
-        ///     Subscription token; it is disposed automatically after the deferred load attempt finishes.
-        /// </returns>
-        public static IDisposable QueueLoadBanksAfterDeferredInitialization(
-            IEnumerable<string> bankResourcePaths,
-            string? studioGuidMappingsResourcePath = null,
-            bool waitForAllLoadsAfterBanks = true)
+        public static void RegisterStudioGuidMappings(string guidMapResourcePath)
+        {
+            if (string.IsNullOrWhiteSpace(guidMapResourcePath))
+                return;
+
+            lock (Gate)
+            {
+                PendingGuidFiles.Add(guidMapResourcePath.Trim());
+                EnsureFlushHookRegisteredLocked();
+            }
+        }
+
+        private static void EnsureFlushHookRegisteredLocked()
+        {
+            if (_flushHookRegistered)
+                return;
+
+            _flushHookRegistered = true;
+            RitsuLibFramework.SubscribeLifecycle<DeferredInitializationCompletedEvent>(_ => FlushPending());
+        }
+
+        private static void FlushPending()
         {
-            ArgumentNullException.ThrowIfNull(bankResourcePaths);
+            if (FmodStudioServer.TryGet() is null)
+            {
+                RitsuLibFramework.Logger.Warn(
+                    "[Audio] deferred FMOD: FmodServer singleton missing; pending banks/GUID files kept for a later flush."
+                );
+                return;
+            }
 
-            var banks = bankResourcePaths as string[] ?? bankResourcePaths.ToArray();
-            if (banks.Length == 0)
-                throw new ArgumentException("At least one bank path is required.", nameof(bankResourcePaths));
+            List<string> banks;
+            List<string> guids;
 
-            return RitsuLibFramework.SubscribeDeferredInitializationOneShot(() =>
+            lock (Gate)
             {
-                if (FmodStudioServer.TryGet() is null)
-                {
-                    RitsuLibFramework.Logger.Warn(
-                        "[Audio] Deferred FMOD bank load skipped: FmodServer singleton is missing.");
-                    return;
-                }
+                banks = [.. PendingBanks];
+                guids = [.. PendingGuidFiles];
+                PendingBanks.Clear();
+                PendingGuidFiles.Clear();
+            }
 
-                foreach (var path in banks)
-                {
-                    if (string.IsNullOrWhiteSpace(path))
-                        continue;
+            if (banks.Count == 0 && guids.Count == 0)
+                return;
 
-                    if (!FmodStudioServer.TryLoadBank(path))
-                        RitsuLibFramework.Logger.Warn($"[Audio] Deferred FMOD bank load failed: {path}");
-                }
+            foreach (var path in banks)
+                FmodStudioServer.TryLoadBank(path);
 
-                if (waitForAllLoadsAfterBanks)
-                    FmodStudioServer.TryWaitForAllLoads();
+            foreach (var path in guids)
+                FmodStudioServer.TryLoadStudioGuidMappings(path);
 
-                if (string.IsNullOrWhiteSpace(studioGuidMappingsResourcePath))
-                    return;
+            FmodStudioServer.TryWaitForAllLoads();
 
-                if (!FmodStudioServer.TryLoadStudioGuidMappings(studioGuidMappingsResourcePath))
-                    RitsuLibFramework.Logger.Warn(
-                        $"[Audio] Deferred FMOD guid map failed: {studioGuidMappingsResourcePath}");
-            });
+            RitsuLibFramework.Logger.Info(
+                $"[Audio] deferred FMOD flush complete (banks={banks.Count}, guid files={guids.Count})."
+            );
         }
     }
 }

Audio/Internal/FmodStudioGuidPathTable.cs

@@ -42,8 +42,21 @@ internal static bool TryLoadFromResourceFile(string resourcePath)
         internal static void ParseAndReplace(string text, string? sourceLabel = null)
         {
             var lines = text.Replace("\r\n", "\n").Split('\n');
-            var next = new Dictionary<string, string>(StringComparer.Ordinal);
+            Dictionary<string, string> next;
+            lock (Gate)
+            {
+                next = new(_eventPathToGuid, StringComparer.Ordinal);
+            }
+
             var guidKeyToFirstPath = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var kv in next)
+            {
+                if (!TryParseStoredGuid(kv.Value, out var parsed))
+                    continue;
+
+                guidKeyToFirstPath.TryAdd(parsed.ToString("N"), kv.Key);
+            }
+
             var prefix = string.IsNullOrEmpty(sourceLabel) ? "[Audio] guids.txt" : $"[Audio] guids.txt ({sourceLabel})";
 
             for (var lineIndex = 0; lineIndex < lines.Length; lineIndex++)
@@ -106,6 +119,15 @@ internal static void ParseAndReplace(string text, string? sourceLabel = null)
             }
         }
 
+        private static bool TryParseStoredGuid(string stored, out Guid parsed)
+        {
+            var s = stored.AsSpan().Trim();
+            if (s.Length >= 3 && s[0] == '{' && s[^1] == '}' && Guid.TryParse(s[1..^1], out parsed))
+                return true;
+
+            return Guid.TryParse(s, out parsed);
+        }
+
         internal static IReadOnlyList<KeyValuePair<string, string>> SnapshotEventMappings()
         {
             lock (Gate)

Const.cs

@@ -18,7 +18,7 @@ public static class Const
         /// <summary>
         ///     Assembly / manifest version string.
         /// </summary>
-        public const string Version = "0.2.20";
+        public const string Version = "0.2.21";
 
         /// <summary>
         ///     Root key for RitsuLib JSON settings under the mod’s user folder.

FrameworkLifecycleContracts.cs

@@ -81,6 +81,24 @@ public void OnEvent(IFrameworkLifecycleEvent evt)
         }
     }
 
+    internal sealed class LifecycleSubscriptionHolder
+    {
+        public IDisposable Subscription { get; set; } = null!;
+    }
+
+    internal sealed class DelegateLifecycleObserverWithSubscription<TEvent>(
+        Action<TEvent, IDisposable> handler,
+        LifecycleSubscriptionHolder holder
+    ) : ILifecycleObserver
+        where TEvent : IFrameworkLifecycleEvent
+    {
+        public void OnEvent(IFrameworkLifecycleEvent evt)
+        {
+            if (evt is TEvent typedEvent)
+                handler(typedEvent, holder.Subscription);
+        }
+    }
+
     internal sealed class FrameworkLifecycleSubscription(Action unsubscribe) : IDisposable
     {
         private bool _disposed;

RitsuLibFramework.LifecycleOnce.cs

@@ -0,0 +1,72 @@
+namespace STS2RitsuLib
+{
+    public static partial class RitsuLibFramework
+    {
+        /// <summary>
+        ///     Subscribes a typed callback that runs at most once per returned subscription: after each invocation the
+        ///     subscription is disposed and the handler is removed.
+        /// </summary>
+        /// <typeparam name="TEvent">Concrete lifecycle event type (must be a struct or sealed class).</typeparam>
+        /// <param name="handler">Invoked once when a matching event is delivered (including synchronous replay).</param>
+        /// <param name="replayCurrentState">
+        ///     When true, invokes <paramref name="handler" /> once if a replayable last event exists, then disposes.
+        /// </param>
+        /// <returns>Disposing unsubscribes without invoking the handler.</returns>
+        /// <exception cref="NotSupportedException">
+        ///     Thrown when <typeparamref name="TEvent" /> is not eligible for typed dispatch (same rule as
+        ///     <see cref="SubscribeLifecycle{TEvent}(Action{TEvent}, bool)" />).
+        /// </exception>
+        public static IDisposable SubscribeLifecycleOnce<TEvent>(
+            Action<TEvent> handler,
+            bool replayCurrentState = true
+        )
+            where TEvent : IFrameworkLifecycleEvent
+        {
+            ArgumentNullException.ThrowIfNull(handler);
+
+            if (!LifecycleEventTypeCache<TEvent>.SupportsTypedDispatch)
+                throw new NotSupportedException(
+                    "SubscribeLifecycleOnce requires a sealed or struct lifecycle event type (typed dispatch). " +
+                    $"Unsupported type: {typeof(TEvent).FullName}."
+                );
+
+            var topic = GetLifecycleTopic<TEvent>();
+            FrameworkLifecycleSubscription? subscription = null;
+
+            void Wrapped(TEvent evt)
+            {
+                try
+                {
+                    handler(evt);
+                }
+                finally
+                {
+                    subscription?.Dispose();
+                }
+            }
+
+            object? replayEvent = null;
+
+            lock (SyncRoot)
+            {
+                subscription = new(() =>
+                {
+                    lock (SyncRoot)
+                    {
+                        topic.Remove(Wrapped);
+                    }
+                });
+
+                topic.Add(Wrapped);
+
+                if (replayCurrentState)
+                    ReplayableLifecycleEvents.TryGetValue(LifecycleEventTypeCache<TEvent>.EventType, out replayEvent);
+            }
+
+            if (replayCurrentState && replayEvent is TEvent typedReplayEvent)
+                SafeNotify(Wrapped, typedReplayEvent, LifecycleEventTypeCache<TEvent>.EventName);
+
+            return subscription;
+        }
+    }
+}