Remove singleton pattern, add static game class, pool sfx players, cleanup events, docs and more, wip (#188)

* Remove singleton pattern from Services

* Remove singleton pattern from AudioManager

* Remove singleton pattern from SceneManager

* Remove singleton pattern from GameConsole

* Remove singleton pattern from MetricsOverlay

* Remove singleton pattern from Profiler

* Adjust all references to refactored managers

* Add static Game class for global managers

Introduces a static Game class providing global access to core managers and services via the Autoloads singleton.

* Refactor namespaces from GodotUtils to __TEMPLATE__

Updated all Framework and UI classes to use the __TEMPLATE__ namespace instead of GodotUtils, and adjusted using directives accordingly.

* Improve SFX player cleanup in AudioManager

* Updated documentation for AudioManager.cs

* Refactor scene switching to use dedicated methods

Introduced dedicated methods in SceneManager for switching to specific menu scenes (MainMenu, Options, ModLoader, Credits) and updated all usages to call these methods instead of accessing MenuScenes directly.

* Improve event cleanup on Button

* Update GodotUtils.dll

* Create GodotUtils.xml

* Pool sfx players in audio manager for performance

* Prefer [Export] over unique lookup with %

* Fire and forget on exit game

* Catch PreQuit subscriber exceptions

* Prefer [Export] over GetNode<T>(...)

* Update GodotUtils.dll

* Remove singleton pattern from Logger and more

- All messages are dequeued instead of one at a time to prevent backlog buildup
- Removed duplicate ResetColor() calls
- Removed hard game console dependency (optional now)
- Made _messages and _console readonly

* Separate BBColor in its own file from Logger.cs

* Remove unused code in Logger

* Improve readability of Logger by removing lines

* Create BBColor.cs.uid

* Call Quit() after Editor.Restart()

* Search window title instead of process name

* Revert from [Export] to GetNode due to Godot Bug

* Fix crash: Assign popup menu console in _Ready()

* Remove unused code in PopupMenu and improve readability

Author: valkyrienyanko

Framework/Autoloads/AudioManager.cs

@@ -1,122 +1,154 @@
 using Godot;
-using GodotUtils.UI;
+using GodotUtils;
 using System;
-using System.Collections.Generic;
-using System.Diagnostics;
 
-namespace GodotUtils;
+namespace __TEMPLATE__;
 
 public class AudioManager : IDisposable
 {
-    private const float MinDefaultRandomPitch        = 0.8f;
-    private const float MaxDefaultRandomPitch        = 1.2f;
-    private const float RandomPitchThreshold  = 0.1f;
-    private const int   MutedVolume           = -80;
-    private const int   MutedVolumeNormalized = -40;
+    private const float MinDefaultRandomPitch = 0.8f;   // Default minimum pitch value for SFX.
+    private const float MaxDefaultRandomPitch = 1.2f;   // Default maximum pitch value for SFX.
+    private const float RandomPitchThreshold  = 0.1f;   // Minimum difference in pitch between repeated sounds.
+    private const int   MutedVolume           = -80;    // dB value representing mute.
+    private const int   MutedVolumeNormalized = -40;    // Normalized muted volume for volume mapping.
 
-    private static AudioManager _instance;
     private AudioStreamPlayer   _musicPlayer;
     private ResourceOptions     _options;
     private Autoloads           _autoloads;
     private float               _lastPitch;
 
-    private List<AudioStreamPlayer2D> _activeSfxPlayers = [];
+    private GodotNodePool<AudioStreamPlayer2D> _sfxPool;
 
+    /// <summary>
+    /// Initializes the AudioManager by attaching a music player to the given autoload node.
+    /// </summary>
     public AudioManager(Autoloads autoloads)
     {
-        if (_instance != null)
-            throw new InvalidOperationException($"{nameof(AudioManager)} was initialized already");
-
-        _instance = this;
         _autoloads = autoloads;
-        _options = OptionsManager.GetOptions();
+        _options = Game.Options.GetOptions();
 
         _musicPlayer = new AudioStreamPlayer();
         autoloads.AddChild(_musicPlayer);
+
+        _sfxPool = new GodotNodePool<AudioStreamPlayer2D>(autoloads, 
+            () => new AudioStreamPlayer2D());
     }
 
+    /// <summary>
+    /// Frees all managed players and clears references for cleanup.
+    /// </summary>
     public void Dispose()
     {
         _musicPlayer.QueueFree();
-        _activeSfxPlayers.Clear();
-
-        _instance = null;
+        _sfxPool.Clear();
     }
 
-    public static void PlayMusic(AudioStream song, bool instant = true, double fadeOut = 1.5, double fadeIn = 0.5)
+    /// <summary>
+    /// Plays a music track, instantly or with optional fade between tracks. Music volume is in config scale (0-100).
+    /// </summary>
+    public void PlayMusic(AudioStream song, bool instant = true, double fadeOut = 1.5, double fadeIn = 0.5)
     {
-        if (!instant && _instance._musicPlayer.Playing)
+        if (!instant && _musicPlayer.Playing)
         {
             // Slowly transition to the new song
-            PlayAudioCrossfade(_instance._musicPlayer, song, _instance._options.MusicVolume, fadeOut, fadeIn);
+            PlayAudioCrossfade(_musicPlayer, song, _options.MusicVolume, fadeOut, fadeIn);
         }
         else
         {
             // Instantly switch to the new song
-            PlayAudio(_instance._musicPlayer, song, _instance._options.MusicVolume);
+            PlayAudio(_musicPlayer, song, _options.MusicVolume);
         }
     }
 
     /// <summary>
-    /// Plays a <paramref name="sound"/> at <paramref name="position"/>.
+    /// Plays a sound effect at the specified global position with randomized pitch to reduce repetition. Volume is normalized (0-100).
     /// </summary>
-    /// <param name="parent"></param>
-    /// <param name="sound"></param>
-    public static void PlaySFX(AudioStream sound, Vector2 position, float minPitch = MinDefaultRandomPitch, float maxPitch = MaxDefaultRandomPitch)
+    public void PlaySFX(AudioStream sound, Vector2 position, float minPitch = MinDefaultRandomPitch, float maxPitch = MaxDefaultRandomPitch)
     {
-        AudioStreamPlayer2D sfxPlayer = new()
-        {
-            Stream = sound,
-            VolumeDb = NormalizeConfigVolume(_instance._options.SFXVolume),
-            PitchScale = GetRandomPitch(minPitch, maxPitch)
-        };
-
-        sfxPlayer.Finished += () =>
-        {
-            sfxPlayer.QueueFree();
-            _instance._activeSfxPlayers.Remove(sfxPlayer);
-        };
-        
-        _instance._autoloads.AddChild(sfxPlayer);
-        _instance._activeSfxPlayers.Add(sfxPlayer);
+        AudioStreamPlayer2D sfxPlayer = _sfxPool.Get();
 
         sfxPlayer.GlobalPosition = position;
+        sfxPlayer.Stream = sound;
+        sfxPlayer.VolumeDb = NormalizeConfigVolume(_options.SFXVolume);
+        sfxPlayer.PitchScale = GetRandomPitch(minPitch, maxPitch);
+        sfxPlayer.Finished += OnFinished;
         sfxPlayer.Play();
+
+        void OnFinished()
+        {
+            sfxPlayer.Finished -= OnFinished;
+            _sfxPool.Release(sfxPlayer);
+        }
     }
 
-    public static void FadeOutSFX(double fadeTime = 1)
+    /// <summary>
+    /// Fades out all currently playing sound effects over the specified duration in seconds.
+    /// </summary>
+    public void FadeOutSFX(double fadeTime = 1)
     {
-        foreach (AudioStreamPlayer2D sfxPlayer in _instance._activeSfxPlayers)
+        foreach (AudioStreamPlayer2D sfxPlayer in _sfxPool.ActiveNodes)
         {
             new GodotTween(sfxPlayer).Animate(AudioStreamPlayer.PropertyName.VolumeDb, MutedVolume, fadeTime);
         }
     }
 
-    public static void SetMusicVolume(float volume)
+    /// <summary>
+    /// Sets the music volume, affecting current playback. Volume is in config scale (0-100).
+    /// </summary>
+    public void SetMusicVolume(float volume)
     {
-        _instance._musicPlayer.VolumeDb = NormalizeConfigVolume(volume);
-        _instance._options.MusicVolume = volume;
+        _musicPlayer.VolumeDb = NormalizeConfigVolume(volume);
+        _options.MusicVolume = volume;
     }
 
-    public static void SetSFXVolume(float volume)
+    /// <summary>
+    /// Sets the SFX volume for all active sound effect players. Volume is in config scale (0-100).
+    /// </summary>
+    public void SetSFXVolume(float volume)
     {
-        _instance._options.SFXVolume = volume;
+        _options.SFXVolume = volume;
 
         float mappedVolume = NormalizeConfigVolume(volume);
 
-        foreach (AudioStreamPlayer2D sfxPlayer in _instance._activeSfxPlayers)
+        foreach (AudioStreamPlayer2D sfxPlayer in _sfxPool.ActiveNodes)
         {
             sfxPlayer.VolumeDb = mappedVolume;
         }
     }
 
+    /// <summary>
+    /// Generates a random pitch between min and max, avoiding values too similar to the previous sound.
+    /// </summary>
+    private float GetRandomPitch(float min, float max)
+    {
+        RandomNumberGenerator rng = new();
+        rng.Randomize();
+
+        float pitch = rng.RandfRange(min, max);
+
+        while (Mathf.Abs(pitch - _lastPitch) < RandomPitchThreshold)
+        {
+            rng.Randomize();
+            pitch = rng.RandfRange(min, max);
+        }
+
+        _lastPitch = pitch;
+        return pitch;
+    }
+
+    /// <summary>
+    /// Instantly plays the given audio stream with the specified player and volume.
+    /// </summary>
     private static void PlayAudio(AudioStreamPlayer player, AudioStream song, float volume)
     {
         player.Stream = song;
         player.VolumeDb = NormalizeConfigVolume(volume);
         player.Play();
     }
 
+    /// <summary>
+    /// Smoothly crossfades between songs by fading out the current and fading in the new one. Volume is in config scale (0-100).
+    /// </summary>
     private static void PlayAudioCrossfade(AudioStreamPlayer player, AudioStream song, float volume, double fadeOut, double fadeIn)
     {
         new GodotTween(player)
@@ -126,25 +158,11 @@ private static void PlayAudioCrossfade(AudioStreamPlayer player, AudioStream son
             .AnimateProp(NormalizeConfigVolume(volume), fadeIn).EaseIn();
     }
 
+    /// <summary>
+    /// Maps a config volume value (0-100) to an AudioStreamPlayer VolumeDb value, returning mute if zero.
+    /// </summary>
     private static float NormalizeConfigVolume(float volume)
     {
         return volume == 0 ? MutedVolume : volume.Remap(0, 100, MutedVolumeNormalized, 0);
     }
-
-    private static float GetRandomPitch(float min, float max)
-    {
-        RandomNumberGenerator rng = new();
-        rng.Randomize();
-
-        float pitch = rng.RandfRange(min, max);
-
-        while (Mathf.Abs(pitch - _instance._lastPitch) < RandomPitchThreshold)
-        {
-            rng.Randomize();
-            pitch = rng.RandfRange(min, max);
-        }
-
-        _instance._lastPitch = pitch;
-        return pitch;
-    }
 }

Framework/Autoloads/Autoloads.cs

@@ -1,13 +1,16 @@
+using __TEMPLATE__.Debugging;
+using __TEMPLATE__.UI;
+using __TEMPLATE__.UI.Console;
 using Godot;
-using GodotUtils.UI;
-using GodotUtils.UI.Console;
+using GodotUtils;
+using System;
+using System.Threading.Tasks;
+
 #if DEBUG
 using GodotUtils.Debugging;
 #endif
-using System;
-using System.Threading.Tasks;
 
-namespace GodotUtils;
+namespace __TEMPLATE__;
 
 // Autoload
 // Access this with GetNode<Autoloads>("/root/Autoloads")
@@ -19,17 +22,17 @@ public partial class Autoloads : Node
 
     public static Autoloads Instance { get; private set; }
 
-    // Game developers should be able to access each individual manager
-    public ComponentManager ComponentManager { get; private set; }
+    public ComponentManager ComponentManager { get; private set; } // Cannot use [Export] here because Godot will bug out and unlink export path in editor after setup completes and restarts the editor
+    public GameConsole      GameConsole      { get; private set; } // Cannot use [Export] here because Godot will bug out and unlink export path in editor after setup completes and restarts the editor
     public AudioManager     AudioManager     { get; private set; }
     public OptionsManager   OptionsManager   { get; private set; }
     public Services         Services         { get; private set; }
     public MetricsOverlay   MetricsOverlay   { get; private set; }
     public SceneManager     SceneManager     { get; private set; }
-    public GameConsole      GameConsole      { get; private set; }
+    public Profiler         Profiler         { get; private set; }
 
 #if NETCODE_ENABLED
-    private Logger _logger;
+    public Logger Logger { get; private set; }
 #endif
 
 #if DEBUG
@@ -43,13 +46,14 @@ public override void _EnterTree()
 
         Instance = this;
         ComponentManager = GetNode<ComponentManager>("ComponentManager");
-        GameConsole = GetNode<GameConsole>("%Console");
         SceneManager = new SceneManager(this, _scenes);
         Services = new Services(this);
         MetricsOverlay = new MetricsOverlay();
+        Profiler = new Profiler();
+        GameConsole = GetNode<GameConsole>("%Console");
 
 #if NETCODE_ENABLED
-        _logger = new Logger(GameConsole);
+        Logger = new Logger(GameConsole);
 #endif
     }
 
@@ -76,7 +80,7 @@ public override void _Process(double delta)
 #endif
 
 #if NETCODE_ENABLED
-        _logger.Update();
+        Logger.Update();
 #endif
     }
 
@@ -85,11 +89,11 @@ public override void _PhysicsProcess(double delta)
         MetricsOverlay.UpdatePhysics();
     }
 
-    public override async void _Notification(int what)
+    public override void _Notification(int what)
     {
         if (what == NotificationWMCloseRequest)
         {
-            await QuitAndCleanup();
+            ExitGame().FireAndForget();
         }
     }
 
@@ -98,32 +102,27 @@ public override void _ExitTree()
         AudioManager.Dispose();
         OptionsManager.Dispose();
         SceneManager.Dispose();
-        Services.Dispose();
-        MetricsOverlay.Dispose();
 
 #if DEBUG
         _visualizeAutoload.Dispose();
 #endif
 
 #if NETCODE_ENABLED
-        _logger.Dispose();
+        Logger.Dispose();
 #endif
 
         Profiler.Dispose();
 
         Instance = null;
     }
 
-    // Using deferred is always complicated...
+    // I'm pretty sure Deferred must be called from a script that extends from Node
     public void DeferredSwitchSceneProxy(string rawName, Variant transTypeVariant)
     {
-        if (SceneManager.Instance == null)
-            return;
-
-        SceneManager.Instance.DeferredSwitchScene(rawName, transTypeVariant);
+        SceneManager.DeferredSwitchScene(rawName, transTypeVariant);
     }
 
-    public async Task QuitAndCleanup()
+    public async Task ExitGame()
     {
         GetTree().AutoAcceptQuit = false;
 
@@ -132,10 +131,16 @@ public async Task QuitAndCleanup()
         {
             // Since the PreQuit event contains a Task only the first subscriber will be invoked
             // with await PreQuit?.Invoke(); so need to ensure all subs are invoked.
-            Delegate[] invocationList = PreQuit.GetInvocationList();
-            foreach (Func<Task> subscriber in invocationList)
+            foreach (Func<Task> subscriber in PreQuit.GetInvocationList())
             {
-                await subscriber();
+                try
+                {
+                    await subscriber();
+                }
+                catch (Exception ex)
+                {
+                    GD.PrintErr($"PreQuit subscriber failed: {ex}");
+                }
             }
         }
 

Framework/Autoloads/Autoloads.tscn

@@ -17,10 +17,12 @@ Options = ExtResource("5_vm4c5")
 Credits = ExtResource("2_xdmsn")
 metadata/_custom_type_script = "uid://17yxgcswri77"
 
-[node name="Autoloads" type="Node"]
+[node name="Autoloads" type="Node" node_paths=PackedStringArray("GameConsole", "ComponentManager")]
 process_mode = 3
 script = ExtResource("1_00yjk")
 _scenes = SubResource("Resource_xdmsn")
+GameConsole = NodePath("Debug/Console")
+ComponentManager = NodePath("ComponentManager")
 
 [node name="ComponentManager" type="Node" parent="."]
 process_mode = 1