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

Author: BAKAOLC

Audio/AudioAdaptiveMusicDirector.cs

@@ -0,0 +1,136 @@
+using System.Collections.Concurrent;
+
+namespace STS2RitsuLib.Audio
+{
+    /// <summary>
+    ///     Coordinates adaptive room/combat/victory music playback in response to game lifecycle transitions.
+    /// </summary>
+    public sealed class AudioAdaptiveMusicDirector : IDisposable
+    {
+        private readonly ConcurrentDictionary<AudioAdaptiveMusicHandle, AudioAdaptiveMusicPlan> _active = new();
+        private readonly IDisposable _combatEndedSubscription;
+        private readonly IDisposable _combatStartingSubscription;
+        private readonly IDisposable _combatVictorySubscription;
+        private readonly IDisposable _roomEnteredSubscription;
+        private readonly IDisposable _runEndedSubscription;
+        private readonly IDisposable _runLoadedSubscription;
+        private readonly IDisposable _runStartedSubscription;
+
+        private AudioAdaptiveMusicDirector()
+        {
+            _runStartedSubscription = RitsuLibFramework.SubscribeLifecycle<RunStartedEvent>(_ => RefreshRoomState());
+            _runLoadedSubscription = RitsuLibFramework.SubscribeLifecycle<RunLoadedEvent>(_ => RefreshRoomState());
+            _roomEnteredSubscription = RitsuLibFramework.SubscribeLifecycle<RoomEnteredEvent>(_ => RefreshRoomState());
+            _combatStartingSubscription =
+                RitsuLibFramework.SubscribeLifecycle<CombatStartingEvent>(_ => SwitchCombatState());
+            _combatVictorySubscription =
+                RitsuLibFramework.SubscribeLifecycle<CombatVictoryEvent>(_ => SwitchVictoryState());
+            _combatEndedSubscription =
+                RitsuLibFramework.SubscribeLifecycle<CombatEndedEvent>(_ => RestoreAfterCombat());
+            _runEndedSubscription = RitsuLibFramework.SubscribeLifecycle<RunEndedEvent>(_ => ClearAll(false));
+        }
+
+        /// <summary>
+        ///     Shared singleton director.
+        /// </summary>
+        public static AudioAdaptiveMusicDirector Shared { get; } = new();
+
+        /// <summary>
+        ///     Disposes framework lifecycle subscriptions owned by this director.
+        /// </summary>
+        public void Dispose()
+        {
+            _runStartedSubscription.Dispose();
+            _runLoadedSubscription.Dispose();
+            _roomEnteredSubscription.Dispose();
+            _combatStartingSubscription.Dispose();
+            _combatVictorySubscription.Dispose();
+            _combatEndedSubscription.Dispose();
+            _runEndedSubscription.Dispose();
+        }
+
+        /// <summary>
+        ///     Starts following the supplied adaptive music plan and returns a handle for later shutdown.
+        /// </summary>
+        public AudioAdaptiveMusicHandle Attach(AudioAdaptiveMusicPlan plan)
+        {
+            var handle = new AudioAdaptiveMusicHandle(plan);
+            _active[handle] = plan;
+            RefreshRoomState(handle, plan);
+            return handle;
+        }
+
+        /// <summary>
+        ///     Removes a previously attached adaptive music handle from lifecycle tracking.
+        /// </summary>
+        public void Detach(AudioAdaptiveMusicHandle handle)
+        {
+            _active.TryRemove(handle, out _);
+        }
+
+        private void RefreshRoomState()
+        {
+            foreach (var pair in _active)
+                RefreshRoomState(pair.Key, pair.Value);
+        }
+
+        private static void RefreshRoomState(AudioAdaptiveMusicHandle handle, AudioAdaptiveMusicPlan plan)
+        {
+            if (plan.RoomSource is null)
+            {
+                if (plan.RefreshVanillaRoomStateOnRoomEnter)
+                    AudioVanillaBridge.RefreshTrackAndAmbience();
+                return;
+            }
+
+            var music = GameFmod.Playback.PlayMusic(plan.RoomSource, plan.RoomOptions);
+            handle.SwitchTo(music);
+        }
+
+        private void SwitchCombatState()
+        {
+            foreach (var pair in _active)
+            {
+                if (pair.Value.CombatSource is null)
+                    continue;
+
+                var music = GameFmod.Playback.PlayMusic(pair.Value.CombatSource, pair.Value.CombatOptions);
+                pair.Key.SwitchTo(music);
+            }
+        }
+
+        private void SwitchVictoryState()
+        {
+            foreach (var pair in _active)
+            {
+                if (pair.Value.VictorySource is null)
+                    continue;
+
+                var music = GameFmod.Playback.PlayMusic(pair.Value.VictorySource, pair.Value.VictoryOptions);
+                pair.Key.SwitchTo(music);
+            }
+        }
+
+        private void RestoreAfterCombat()
+        {
+            foreach (var pair in _active)
+            {
+                if (pair.Value.RestoreVanillaMusicOnCombatEnd)
+                {
+                    pair.Key.Stop();
+                    continue;
+                }
+
+                RefreshRoomState(pair.Key, pair.Value);
+            }
+        }
+
+        private void ClearAll(bool restoreVanillaMusic)
+        {
+            foreach (var handle in _active.Keys)
+                handle.Stop(restoreVanillaMusic);
+
+            _active.Clear();
+        }
+    }
+}

Audio/AudioAdaptiveMusicHandle.cs

@@ -0,0 +1,56 @@
+namespace STS2RitsuLib.Audio
+{
+    /// <summary>
+    ///     Represents an active adaptive music binding that can switch tracks and restore vanilla state when stopped.
+    /// </summary>
+    public sealed class AudioAdaptiveMusicHandle : IDisposable
+    {
+        private readonly AudioAdaptiveMusicPlan _plan;
+        private AudioMusicHandle? _current;
+        private bool _disposed;
+
+        internal AudioAdaptiveMusicHandle(AudioAdaptiveMusicPlan plan)
+        {
+            _plan = plan;
+        }
+
+        /// <summary>
+        ///     Stops adaptive playback and unregisters this handle from the shared director.
+        /// </summary>
+        public void Dispose()
+        {
+            if (_disposed)
+                return;
+
+            _disposed = true;
+            Stop();
+            AudioAdaptiveMusicDirector.Shared.Detach(this);
+        }
+
+        internal void SwitchTo(AudioMusicHandle? handle)
+        {
+            _current?.Dispose();
+            _current = handle;
+        }
+
+        internal void RefreshVolume(float volume)
+        {
+            _current?.TrySetVolume(volume);
+        }
+
+        /// <summary>
+        ///     Stops the current adaptive override and optionally restores vanilla run music.
+        /// </summary>
+        public void Stop(bool restoreVanillaMusic = true)
+        {
+            if (_disposed)
+                return;
+
+            _current?.Dispose();
+            _current = null;
+
+            if (restoreVanillaMusic && _plan.RestoreVanillaMusicOnStop)
+                AudioVanillaBridge.RefreshRunMusic();
+        }
+    }
+}

Audio/AudioAdaptiveMusicPlan.cs

@@ -0,0 +1,53 @@
+namespace STS2RitsuLib.Audio
+{
+    /// <summary>
+    ///     Declares room/combat/victory music sources that should follow the game's lifecycle transitions.
+    /// </summary>
+    public sealed class AudioAdaptiveMusicPlan
+    {
+        /// <summary>
+        ///     Music source to use while the player is in a room outside combat.
+        /// </summary>
+        public AudioSource? RoomSource { get; init; }
+
+        /// <summary>
+        ///     Music source to use while combat is active.
+        /// </summary>
+        public AudioSource? CombatSource { get; init; }
+
+        /// <summary>
+        ///     Music source to use after combat victory, when provided.
+        /// </summary>
+        public AudioSource? VictorySource { get; init; }
+
+        /// <summary>
+        ///     Restores vanilla run music when the adaptive handle is stopped.
+        /// </summary>
+        public bool RestoreVanillaMusicOnStop { get; init; } = true;
+
+        /// <summary>
+        ///     Restores vanilla run music after combat ends instead of returning to the room override.
+        /// </summary>
+        public bool RestoreVanillaMusicOnCombatEnd { get; init; } = true;
+
+        /// <summary>
+        ///     Refreshes vanilla room track and ambience when entering a room with no room override.
+        /// </summary>
+        public bool RefreshVanillaRoomStateOnRoomEnter { get; init; } = true;
+
+        /// <summary>
+        ///     Playback options applied when starting room music.
+        /// </summary>
+        public AudioPlaybackOptions RoomOptions { get; init; } = new() { Scope = AudioLifecycleScope.Room };
+
+        /// <summary>
+        ///     Playback options applied when starting combat music.
+        /// </summary>
+        public AudioPlaybackOptions CombatOptions { get; init; } = new() { Scope = AudioLifecycleScope.Combat };
+
+        /// <summary>
+        ///     Playback options applied when starting victory music.
+        /// </summary>
+        public AudioPlaybackOptions VictoryOptions { get; init; } = new() { Scope = AudioLifecycleScope.Combat };
+    }
+}

Audio/AudioAdaptivePlans.cs

@@ -0,0 +1,51 @@
+namespace STS2RitsuLib.Audio
+{
+    /// <summary>
+    ///     Convenience builders for common adaptive music override patterns.
+    /// </summary>
+    public static class AudioAdaptivePlans
+    {
+        /// <summary>
+        ///     Builds a plan that overrides combat music and optionally room and victory transitions.
+        /// </summary>
+        public static AudioAdaptiveMusicPlan CombatOverride(
+            AudioSource combatSource,
+            AudioSource? roomSource = null,
+            AudioSource? victorySource = null,
+            AudioPlaybackOptions? combatOptions = null,
+            AudioPlaybackOptions? roomOptions = null,
+            AudioPlaybackOptions? victoryOptions = null)
+        {
+            return new()
+            {
+                RoomSource = roomSource,
+                CombatSource = combatSource,
+                VictorySource = victorySource,
+                RoomOptions = roomOptions ?? new AudioPlaybackOptions { Scope = AudioLifecycleScope.Room },
+                CombatOptions = combatOptions ?? new AudioPlaybackOptions { Scope = AudioLifecycleScope.Combat },
+                VictoryOptions = victoryOptions ?? new AudioPlaybackOptions { Scope = AudioLifecycleScope.Combat },
+            };
+        }
+
+        /// <summary>
+        ///     Builds a plan that supplies room and combat overrides for the full run without restoring vanilla music after
+        ///     combat.
+        /// </summary>
+        public static AudioAdaptiveMusicPlan FullRunOverride(
+            AudioSource roomSource,
+            AudioSource combatSource,
+            AudioSource? victorySource = null)
+        {
+            return new()
+            {
+                RoomSource = roomSource,
+                CombatSource = combatSource,
+                VictorySource = victorySource,
+                RestoreVanillaMusicOnCombatEnd = false,
+                RoomOptions = new() { Scope = AudioLifecycleScope.Room },
+                CombatOptions = new() { Scope = AudioLifecycleScope.Combat },
+                VictoryOptions = new() { Scope = AudioLifecycleScope.Combat },
+            };
+        }
+    }
+}

Audio/AudioChannelMode.cs

@@ -0,0 +1,18 @@
+namespace STS2RitsuLib.Audio
+{
+    /// <summary>
+    ///     How a named channel should behave when new playback arrives.
+    /// </summary>
+    public enum AudioChannelMode
+    {
+        /// <summary>
+        ///     Keep the existing playback and ignore the new request.
+        /// </summary>
+        KeepExisting = 0,
+
+        /// <summary>
+        ///     Stop the existing playback and replace it with the new one.
+        /// </summary>
+        ReplaceExisting = 1,
+    }
+}