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

Author: BAKAOLC

Audio/FmodEventPath.cs

@@ -3,20 +3,33 @@ namespace STS2RitsuLib.Audio
     /// <summary>
     ///     FMOD Studio event path (e.g. <c>event:/sfx/block_gain</c>). Implicitly converts to <see cref="string" />.
     /// </summary>
+    /// <param name="Value">Raw Studio path string.</param>
     public readonly record struct FmodEventPath(string Value)
     {
+        /// <summary>
+        ///     True when <see cref="Value" /> is null or empty.
+        /// </summary>
         public bool IsEmpty => string.IsNullOrEmpty(Value);
 
+        /// <summary>
+        ///     Returns the wrapped path string.
+        /// </summary>
         public static implicit operator string(FmodEventPath path)
         {
             return path.Value;
         }
 
+        /// <summary>
+        ///     Wraps a string as an <see cref="FmodEventPath" />.
+        /// </summary>
         public static implicit operator FmodEventPath(string value)
         {
             return new(value);
         }
 
+        /// <summary>
+        ///     Returns <see cref="Value" />.
+        /// </summary>
         public override string ToString()
         {
             return Value;

Audio/FmodParameterMap.cs

@@ -1,18 +1,29 @@
 namespace STS2RitsuLib.Audio
 {
-    /// <summary>Builds parameter maps for <see cref="IFmodOneShotPlayback" /> multi-parameter overloads.</summary>
+    /// <summary>
+    ///     Builds parameter maps for <see cref="IFmodOneShotPlayback" /> multi-parameter overloads.
+    /// </summary>
     public static class FmodParameterMap
     {
+        /// <summary>
+        ///     Empty parameter map for overloads that require a dictionary instance.
+        /// </summary>
         public static Dictionary<string, float> Empty()
         {
             return [];
         }
 
+        /// <summary>
+        ///     Single named parameter suitable for one-shot playback helpers.
+        /// </summary>
         public static Dictionary<string, float> Single(string name, float value)
         {
             return new() { [name] = value };
         }
 
+        /// <summary>
+        ///     Builds a map from name/value tuples; duplicates last writer wins.
+        /// </summary>
         public static Dictionary<string, float> Of(params (string Name, float Value)[] pairs)
         {
             if (pairs.Length == 0)

Audio/FmodPathRoundRobinPool.cs

@@ -1,30 +1,41 @@
 namespace STS2RitsuLib.Audio
 {
-    /// <summary>In-memory pool of event or file paths with simple no-repeat random selection.</summary>
+    /// <summary>
+    ///     In-memory pool of event or file paths with simple no-repeat random selection.
+    /// </summary>
     public sealed class FmodPathRoundRobinPool
     {
         private readonly List<string> _entries;
         private readonly Random _rng = new();
         private int _lastIndex = -1;
 
+        /// <summary>
+        ///     Copies <paramref name="paths" /> into an internal list (may be empty).
+        /// </summary>
         public FmodPathRoundRobinPool(IEnumerable<string> paths)
         {
             ArgumentNullException.ThrowIfNull(paths);
             _entries = [.. paths];
         }
 
+        /// <summary>
+        ///     Snapshot of configured paths.
+        /// </summary>
         public IReadOnlyList<string> Entries => _entries;
 
+        /// <summary>
+        ///     Picks a random path, avoiding the same index as the previous pick when more than one entry exists.
+        /// </summary>
         public bool TryPickNext(out string path)
         {
             path = "";
-            if (_entries.Count == 0)
-                return false;
-
-            if (_entries.Count == 1)
+            switch (_entries.Count)
             {
-                path = _entries[0];
-                return true;
+                case 0:
+                    return false;
+                case 1:
+                    path = _entries[0];
+                    return true;
             }
 
             int index;

Audio/FmodPlaybackThrottle.cs

@@ -2,13 +2,17 @@
 
 namespace STS2RitsuLib.Audio
 {
-    /// <summary>Per-key cooldown for rapid triggers (ms, via <see cref="Stopwatch" /> ticks).</summary>
+    /// <summary>
+    ///     Per-key cooldown for rapid triggers (ms, via <see cref="Stopwatch" /> ticks).
+    /// </summary>
     public static class FmodPlaybackThrottle
     {
         private static readonly Lock Gate = new();
         private static readonly Dictionary<string, long> LastTicks = new(StringComparer.Ordinal);
 
-        /// <summary>Returns false if <paramref name="key" /> was used within <paramref name="cooldownMs" />.</summary>
+        /// <summary>
+        ///     Returns false if <paramref name="key" /> was used within <paramref name="cooldownMs" />.
+        /// </summary>
         public static bool TryEnter(string key, int cooldownMs)
         {
             if (cooldownMs <= 0)
@@ -27,6 +31,9 @@ public static bool TryEnter(string key, int cooldownMs)
             }
         }
 
+        /// <summary>
+        ///     Removes cooldown state for <paramref name="key" /> so the next <see cref="TryEnter" /> may pass.
+        /// </summary>
         public static void Clear(string key)
         {
             lock (Gate)
@@ -35,6 +42,9 @@ public static void Clear(string key)
             }
         }
 
+        /// <summary>
+        ///     Clears all throttle keys.
+        /// </summary>
         public static void ClearAll()
         {
             lock (Gate)

Audio/FmodStudioBusAccess.cs

@@ -3,21 +3,29 @@
 
 namespace STS2RitsuLib.Audio
 {
-    /// <summary>Direct bus objects from FMOD Studio (parallel to strings in <see cref="FmodStudioRouting" />).</summary>
+    /// <summary>
+    ///     Direct bus objects from FMOD Studio (parallel to strings in <see cref="FmodStudioRouting" />).
+    /// </summary>
     public static class FmodStudioBusAccess
     {
         private static readonly StringName GetVolume = new("get_volume");
         private static readonly StringName SetVolume = new("set_volume");
         private static readonly StringName SetMute = new("set_mute");
         private static readonly StringName SetPaused = new("set_paused");
 
+        /// <summary>
+        ///     Resolves a Studio bus object for <paramref name="busPath" />; null when the addon call fails.
+        /// </summary>
         public static GodotObject? TryGetBus(string busPath)
         {
             return !FmodStudioGateway.TryCall(out var v, FmodStudioMethodNames.GetBus, busPath)
                 ? null
                 : v.AsGodotObject();
         }
 
+        /// <summary>
+        ///     Reads linear volume for <paramref name="busPath" />; 0 when missing or on error.
+        /// </summary>
         public static float TryGetVolume(string busPath)
         {
             var bus = TryGetBus(busPath);
@@ -35,6 +43,9 @@ public static float TryGetVolume(string busPath)
             }
         }
 
+        /// <summary>
+        ///     Sets linear volume on the resolved bus.
+        /// </summary>
         public static bool TrySetVolume(string busPath, float linearVolume)
         {
             var bus = TryGetBus(busPath);
@@ -53,6 +64,9 @@ public static bool TrySetVolume(string busPath, float linearVolume)
             }
         }
 
+        /// <summary>
+        ///     Mutes or unmutes the bus.
+        /// </summary>
         public static bool TrySetMute(string busPath, bool muted)
         {
             var bus = TryGetBus(busPath);
@@ -71,6 +85,9 @@ public static bool TrySetMute(string busPath, bool muted)
             }
         }
 
+        /// <summary>
+        ///     Pauses or resumes the bus.
+        /// </summary>
         public static bool TrySetPaused(string busPath, bool paused)
         {
             var bus = TryGetBus(busPath);

Audio/FmodStudioDirectOneShots.cs

@@ -10,11 +10,17 @@ namespace STS2RitsuLib.Audio
     /// </summary>
     public static class FmodStudioDirectOneShots
     {
+        /// <summary>
+        ///     Plays a one-shot by event path via the Godot FMOD addon.
+        /// </summary>
         public static bool TryPlay(string eventPath)
         {
             return FmodStudioGateway.TryCall(FmodStudioMethodNames.PlayOneShot, eventPath);
         }
 
+        /// <summary>
+        ///     Plays a one-shot with initial parameter values.
+        /// </summary>
         public static bool TryPlay(string eventPath, IReadOnlyDictionary<string, float> parameters)
         {
             var server = FmodStudioGateway.TryGetServer();
@@ -37,6 +43,9 @@ public static bool TryPlay(string eventPath, IReadOnlyDictionary<string, float>
             }
         }
 
+        /// <summary>
+        ///     Plays a one-shot using a Studio event GUID string.
+        /// </summary>
         public static bool TryPlayUsingGuid(string eventGuid)
         {
             return FmodStudioGateway.TryCall(FmodStudioMethodNames.PlayOneShotUsingGuid, eventGuid);

Audio/FmodStudioEventInstances.cs

@@ -3,16 +3,24 @@
 
 namespace STS2RitsuLib.Audio
 {
-    /// <summary>Long-lived Studio event instances (manual start/stop/release).</summary>
+    /// <summary>
+    ///     Long-lived Studio event instances (manual start/stop/release).
+    /// </summary>
     public static class FmodStudioEventInstances
     {
+        /// <summary>
+        ///     Creates a Studio event or snapshot instance; null when creation fails.
+        /// </summary>
         public static GodotObject? TryCreate(string eventOrSnapshotPath)
         {
             return !FmodStudioGateway.TryCall(out var v, FmodStudioMethodNames.CreateEventInstance, eventOrSnapshotPath)
                 ? null
                 : v.AsGodotObject();
         }
 
+        /// <summary>
+        ///     Calls <c>start</c> on the instance when non-null.
+        /// </summary>
         public static bool TryStart(GodotObject? instance)
         {
             if (instance is null)
@@ -30,6 +38,9 @@ public static bool TryStart(GodotObject? instance)
             }
         }
 
+        /// <summary>
+        ///     Stops the instance; <paramref name="allowFadeOut" /> maps to FMOD stop mode.
+        /// </summary>
         public static bool TryStop(GodotObject? instance, bool allowFadeOut = true)
         {
             if (instance is null)
@@ -47,6 +58,9 @@ public static bool TryStop(GodotObject? instance, bool allowFadeOut = true)
             }
         }
 
+        /// <summary>
+        ///     Releases native resources for the instance; errors are logged only.
+        /// </summary>
         public static void TryRelease(GodotObject? instance)
         {
             if (instance is null)

Audio/FmodStudioLoadBankMode.cs

@@ -1,10 +1,23 @@
 namespace STS2RitsuLib.Audio
 {
-    /// <summary>Values for FMOD Studio load_bank via the Godot FMOD addon.</summary>
+    /// <summary>
+    ///     Values for FMOD Studio load_bank via the Godot FMOD addon.
+    /// </summary>
     public enum FmodStudioLoadBankMode
     {
+        /// <summary>
+        ///     Default blocking load.
+        /// </summary>
         Normal = 0,
+
+        /// <summary>
+        ///     Load without blocking the caller.
+        /// </summary>
         NonBlocking = 1,
+
+        /// <summary>
+        ///     Decompress sample data into memory (Studio load flag).
+        /// </summary>
         DecompressSamples = 2,
     }
 }