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

Author: BAKAOLC

.github/workflows/issue-auto-label.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Parse issue form fields and label
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         with:
           script: |
             const issue = context.payload.issue;

.github/workflows/labels-sync.yml

@@ -15,7 +15,7 @@ jobs:
           fetch-depth: 1
 
       - name: Apply labels.yml
-        uses: crazy-max/ghaction-github-labeler@v5
+        uses: crazy-max/ghaction-github-labeler@v6
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           yaml-file: .github/labels.yml

Audio/FmodStudioDeferredBankRegistration.cs

@@ -0,0 +1,97 @@
+namespace STS2RitsuLib.Audio
+{
+    /// <summary>
+    ///     Convenience helpers for loading FMOD Studio banks after the game has finished deferred initialization.
+    /// </summary>
+    public static class FmodStudioDeferredBankRegistration
+    {
+        /// <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).
+        /// </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)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(bankResourcePath);
+
+            return QueueLoadBanksAfterDeferredInitialization(
+                [bankResourcePath],
+                studioGuidMappingsResourcePath,
+                waitForAllLoadsAfterBanks);
+        }
+
+        /// <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).
+        /// </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)
+        {
+            ArgumentNullException.ThrowIfNull(bankResourcePaths);
+
+            var banks = bankResourcePaths as string[] ?? bankResourcePaths.ToArray();
+            if (banks.Length == 0)
+                throw new ArgumentException("At least one bank path is required.", nameof(bankResourcePaths));
+
+            return RitsuLibFramework.SubscribeDeferredInitializationOneShot(() =>
+            {
+                if (FmodStudioServer.TryGet() is null)
+                {
+                    RitsuLibFramework.Logger.Warn(
+                        "[Audio] Deferred FMOD bank load skipped: FmodServer singleton is missing.");
+                    return;
+                }
+
+                foreach (var path in banks)
+                {
+                    if (string.IsNullOrWhiteSpace(path))
+                        continue;
+
+                    if (!FmodStudioServer.TryLoadBank(path))
+                        RitsuLibFramework.Logger.Warn($"[Audio] Deferred FMOD bank load failed: {path}");
+                }
+
+                if (waitForAllLoadsAfterBanks)
+                    FmodStudioServer.TryWaitForAllLoads();
+
+                if (string.IsNullOrWhiteSpace(studioGuidMappingsResourcePath))
+                    return;
+
+                if (!FmodStudioServer.TryLoadStudioGuidMappings(studioGuidMappingsResourcePath))
+                    RitsuLibFramework.Logger.Warn(
+                        $"[Audio] Deferred FMOD guid map failed: {studioGuidMappingsResourcePath}");
+            });
+        }
+    }
+}

Audio/FmodStudioStreamingFiles.cs

@@ -1,13 +1,15 @@
 using System.Collections.Concurrent;
 using Godot;
 using STS2RitsuLib.Audio.Internal;
+using FileAccess = Godot.FileAccess;
 
 namespace STS2RitsuLib.Audio
 {
     /// <summary>
-    ///     Load loose audio files into the FMOD runtime (wav/ogg/mp3 per addon) from absolute filesystem paths.
-    ///     Rejects <c>res://</c>, but resolves <c>user://</c> to an absolute filesystem path first. Tracks loaded paths so
-    ///     you can unload deterministically.
+    ///     Load loose audio files into the FMOD runtime (wav/ogg/mp3 per addon). For <c>res://</c>, only paths that are
+    ///     still visible as raw files to <see cref="FileAccess" /> are accepted (e.g. Import dock &quot;Keep File (No Import)
+    ///     &quot;).
+    ///     Resolves <c>user://</c> to an absolute filesystem path. Tracks loaded paths so you can unload deterministically.
     /// </summary>
     public static class FmodStudioStreamingFiles
     {
@@ -81,7 +83,8 @@ public static bool TryPreloadAsStreamingMusic(string absolutePath)
         /// <summary>
         ///     Returns a playable sound instance for the loose audio file at <paramref name="absolutePath" />, preloading as sound
         ///     when needed.
-        ///     Accepts absolute filesystem paths and resolves <c>user://</c> to an absolute filesystem path.
+        ///     Accepts <c>res://</c> only when the path is a raw file for <see cref="FileAccess" />, absolute paths, and
+        ///     <c>user://</c> (globalized).
         /// </summary>
         public static GodotObject? TryCreateSoundInstance(string absolutePath)
         {
@@ -103,7 +106,8 @@ public static bool TryPreloadAsStreamingMusic(string absolutePath)
 
         /// <summary>
         ///     Returns a streaming music instance, preloading as music when needed.
-        ///     Accepts absolute filesystem paths and resolves <c>user://</c> to an absolute filesystem path.
+        ///     Accepts <c>res://</c> only when the path is a raw file for <see cref="FileAccess" />, absolute paths, and
+        ///     <c>user://</c> (globalized).
         /// </summary>
         public static GodotObject? TryCreateStreamingMusicInstance(string absolutePath)
         {
@@ -151,8 +155,11 @@ public static bool TryPlaySoundFile(string absolutePath, float volume = 1f, floa
         /// </summary>
         public static bool TryUnloadFile(string absolutePath)
         {
-            return !Loaded.TryRemove(absolutePath, out _) ||
-                   FmodStudioGateway.TryCall(FmodStudioMethodNames.UnloadFile, absolutePath);
+            if (!TryResolveSupportedPath(absolutePath, out var resolvedPath))
+                return false;
+
+            return !Loaded.TryRemove(resolvedPath, out _) ||
+                   FmodStudioGateway.TryCall(FmodStudioMethodNames.UnloadFile, resolvedPath);
         }
 
         /// <summary>
@@ -173,16 +180,42 @@ private static bool TryResolveSupportedPath(string path, out string resolvedPath
                 return false;
             }
 
-            if (path.StartsWith("res://", StringComparison.OrdinalIgnoreCase))
+            if (path.StartsWith("user://", StringComparison.OrdinalIgnoreCase))
             {
-                RitsuLibFramework.Logger.Error($"[Audio] FMOD file playback does not accept res:// paths: {path}");
+                resolvedPath = ProjectSettings.GlobalizePath(path);
+                if (!Path.IsPathRooted(resolvedPath))
+                {
+                    RitsuLibFramework.Logger.Error($"[Audio] FMOD file playback requires an absolute path: {path}");
+                    return false;
+                }
+
+                if (File.Exists(resolvedPath)) return true;
+                RitsuLibFramework.Logger.Error($"[Audio] FMOD file playback file not found: {resolvedPath}");
                 return false;
             }
 
-            resolvedPath = path.StartsWith("user://", StringComparison.OrdinalIgnoreCase)
-                ? ProjectSettings.GlobalizePath(path)
-                : path;
+            if (path.StartsWith("res://", StringComparison.OrdinalIgnoreCase))
+            {
+                if (FileAccess.FileExists(path))
+                {
+                    resolvedPath = path;
+                    return true;
+                }
+
+                if (ResourceLoader.Exists(path))
+                {
+                    RitsuLibFramework.Logger.Warn(
+                        "[Audio] FMOD file playback: path resolves only as imported/packed resource, not as a raw file for FileAccess. " +
+                        "Avoid default import for assets you stream through FMOD: use the Import dock \"Keep File (No Import)\" " +
+                        "(or ship a loose file / FMOD Studio bank). Path: " + path);
+                    return false;
+                }
+
+                RitsuLibFramework.Logger.Error($"[Audio] FMOD file playback file not found: {path}");
+                return false;
+            }
 
+            resolvedPath = path;
             if (!Path.IsPathRooted(resolvedPath))
             {
                 RitsuLibFramework.Logger.Error($"[Audio] FMOD file playback requires an absolute path: {path}");

Const.cs

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

Content/DynamicCharacterStarterContentPatcher.cs

@@ -5,6 +5,7 @@
 using MegaCrit.Sts2.Core.Models;
 using STS2RitsuLib.Patching.Builders;
 using STS2RitsuLib.Patching.Core;
+using STS2RitsuLib.Scaffolding.Characters;
 
 namespace STS2RitsuLib.Content
 {
@@ -84,7 +85,7 @@ private static void TryAddCharacterPropertyGetter(
             Logger logger)
         {
             var getter = FindDeclaredPropertyGetter(concreteCharacterType, propertyName);
-            if (getter == null || !queuedGetters.Add(getter))
+            if (getter == null || IsModCharacterTemplateGetter(getter) || !queuedGetters.Add(getter))
                 return;
 
             try
@@ -118,6 +119,13 @@ private static void TryAddCharacterPropertyGetter(
             return null;
         }
 
+        private static bool IsModCharacterTemplateGetter(MethodInfo getter)
+        {
+            var declaringType = getter.DeclaringType;
+            return declaringType is { IsGenericType: true }
+                   && declaringType.GetGenericTypeDefinition() == typeof(ModCharacterTemplate<,,>);
+        }
+
         // ReSharper disable InconsistentNaming
         private static void StartingDeckPostfix(CharacterModel __instance, ref IEnumerable<CardModel> __result)
             // ReSharper restore InconsistentNaming

RitsuLibFramework.PatcherSetup.cs

@@ -314,6 +314,7 @@ private static void RegisterCharacterAssetPatches()
             patcher.RegisterPatch<NCreatureNonSpineReviveAnimationTriggerPatch>();
             patcher.RegisterPatch<ModMerchantCharacterVisualPlaybackPatch>();
             patcher.RegisterPatch<NMerchantRoomProceduralCharacterInstantiationPatch>();
+            patcher.RegisterPatch<NFakeMerchantProceduralCharacterInstantiationPatch>();
             patcher.RegisterPatch<NRestSiteCharacterCreateProceduralPatch>();
             patcher.RegisterPatch<NRestSiteRoomProceduralVisualPlaybackPatch>();
             patcher.RegisterPatch<CardLibraryCompendiumPatch>();

RitsuLibFramework.cs

@@ -100,16 +100,18 @@ public static IDisposable SubscribeLifecycle(ILifecycleObserver observer, bool r
                     : [];
             }
 
-            foreach (var evt in lifecycleSnapshot)
-                SafeNotify(observer, evt, evt.GetType().Name);
-
-            return new FrameworkLifecycleSubscription(() =>
+            var observerSubscription = new FrameworkLifecycleSubscription(() =>
             {
                 lock (SyncRoot)
                 {
                     _lifecycleObservers = RemoveItem(_lifecycleObservers, observer);
                 }
             });
+
+            foreach (var evt in lifecycleSnapshot)
+                SafeNotify(observer, evt, evt.GetType().Name);
+
+            return observerSubscription;
         }
 
         /// <summary>
@@ -141,16 +143,77 @@ public static IDisposable SubscribeLifecycle<TEvent>(Action<TEvent> handler, boo
                     ReplayableLifecycleEvents.TryGetValue(LifecycleEventTypeCache<TEvent>.EventType, out replayEvent);
             }
 
+            var subscription = new FrameworkLifecycleSubscription(() =>
+            {
+                lock (SyncRoot)
+                {
+                    topic.Remove(handler);
+                }
+            });
+
             if (replayEvent is TEvent typedReplayEvent)
                 SafeNotify(handler, typedReplayEvent, LifecycleEventTypeCache<TEvent>.EventName);
 
-            return new FrameworkLifecycleSubscription(() =>
+            return subscription;
+        }
+
+        /// <summary>
+        ///     Registers <paramref name="handler" /> to run once after deferred initialization has completed, replaying
+        ///     immediately if that milestone was already reached.
+        /// </summary>
+        /// <param name="handler">Work to run exactly once.</param>
+        /// <returns>
+        ///     Subscription token; it is also disposed automatically after <paramref name="handler" /> returns (including when
+        ///     replayed synchronously).
+        /// </returns>
+        /// <remarks>
+        ///     Use when a <see cref="MegaCrit.Sts2.Core.Modding.ModInitializerAttribute" /> entry point must wait for subsystems
+        ///     such as the
+        ///     Godot <c>FmodServer</c> singleton. Handlers that dispose the returned token from inside the callback can rely
+        ///     on the subscription object existing before any synchronous lifecycle replay runs.
+        /// </remarks>
+        public static IDisposable SubscribeDeferredInitializationOneShot(Action handler)
+        {
+            ArgumentNullException.ThrowIfNull(handler);
+
+            var topic = GetLifecycleTopic<DeferredInitializationCompletedEvent>();
+            object? replayEvent;
+            FrameworkLifecycleSubscription? subscription = null;
+
+            lock (SyncRoot)
+            {
+                topic.Add(Wrapped);
+
+                ReplayableLifecycleEvents.TryGetValue(
+                    LifecycleEventTypeCache<DeferredInitializationCompletedEvent>.EventType,
+                    out replayEvent);
+            }
+
+            subscription = new(() =>
             {
                 lock (SyncRoot)
                 {
-                    topic.Remove(handler);
+                    topic.Remove(Wrapped);
                 }
             });
+
+            if (replayEvent is DeferredInitializationCompletedEvent typedReplayEvent)
+                SafeNotify(Wrapped, typedReplayEvent,
+                    LifecycleEventTypeCache<DeferredInitializationCompletedEvent>.EventName);
+
+            return subscription;
+
+            void Wrapped(DeferredInitializationCompletedEvent _)
+            {
+                try
+                {
+                    handler();
+                }
+                finally
+                {
+                    subscription?.Dispose();
+                }
+            }
         }
 
         /// <summary>

STS2-RitsuLib.csproj

@@ -23,7 +23,7 @@
 
     <PropertyGroup Label="NuGet package">
         <IsPackable>true</IsPackable>
-        <Version>0.2.19</Version>
+        <Version>0.2.20</Version>
         <Authors>OLC</Authors>
         <Description>Shared framework library for Slay the Spire 2 mods.</Description>
         <PackageReadmeFile>README.md</PackageReadmeFile>