Add an ability to preload a sound file without decoding

PR #2006 made the preloaded sounds be decoded right away,
bringing back old memory consumption issues from before #431.
For games that want to download all their assets during
the loading screen, but don't want to actually decode all sounds
right away because of memory consumption concerns, being able to
dynamically load/unload Howler objects via events is not enough,
as the application may already go out-of-memory during loading,
and not doing that will cause the game to download additional
assets during gameplay. This change adds a new property,
"preloadInCache", which makes GDJS request the sound asset via XHR.
This puts the file into browser cache, so it can be reasonably
expected to be decoded later without issuing network requests.

While at it, add user visible descriptions for all preload options.

Author: dos1

Core/GDCore/Project/ResourcesManager.cpp

@@ -184,11 +184,17 @@ std::map<gd::String, gd::PropertyDescriptor> AudioResource::GetProperties()
     const {
   std::map<gd::String, gd::PropertyDescriptor> properties;
   properties[_("Preload as sound")]
+      .SetDescription(_("Loads the fully decoded file into cache, so it can be played right away as Sound with no further delays."))
       .SetValue(preloadAsSound ? "true" : "false")
       .SetType("Boolean");
   properties[_("Preload as music")]
+      .SetDescription(_("Prepares the file for immediate streaming as Music (does not wait for complete download)."))
       .SetValue(preloadAsMusic ? "true" : "false")
       .SetType("Boolean");
+  properties[_("Preload in cache")]
+      .SetDescription(_("Loads the complete file into cache, but does not decode it into memory until requested."))
+      .SetValue(preloadInCache ? "true" : "false")
+      .SetType("Boolean");
 
   return properties;
 }
@@ -199,6 +205,8 @@ bool AudioResource::UpdateProperty(const gd::String& name,
     preloadAsSound = value == "1";
   else if (name == _("Preload as music"))
     preloadAsMusic = value == "1";
+  else if (name == _("Preload in cache"))
+    preloadInCache = value == "1";
 
   return true;
 }

Core/GDCore/Project/ResourcesManager.h

@@ -223,7 +223,7 @@ class GD_CORE_API ImageResource : public Resource {
  */
 class GD_CORE_API AudioResource : public Resource {
  public:
-  AudioResource() : Resource(), preloadAsMusic(false), preloadAsSound(false) {
+  AudioResource() : Resource(), preloadAsMusic(false), preloadAsSound(false), preloadInCache(false) {
     SetKind("audio");
   };
   virtual ~AudioResource(){};
@@ -263,10 +263,21 @@ class GD_CORE_API AudioResource : public Resource {
    */
   void SetPreloadAsSound(bool enable = true) { preloadAsSound = enable; }
 
+  /**
+   * \brief Return true if the audio resource should be preloaded in cache (without decoding into memory).
+   */
+  bool PreloadInCache() const { return preloadInCache; }
+
+  /**
+   * \brief Set if the audio resource should be preloaded in cache (without decoding into memory).
+   */
+  void SetPreloadInCache(bool enable = true) { preloadInCache = enable; }
+
  private:
   gd::String file;
   bool preloadAsSound;
   bool preloadAsMusic;
+  bool preloadInCache;
 };
 
 /**

GDJS/Runtime/howler-sound-manager/howler-sound-manager.ts

@@ -802,24 +802,41 @@ namespace gdjs {
         if (!filesToLoad.length) return;
         const file = filesToLoad.shift()!;
         const fileData = files[file][0];
-        if (!fileData.preloadAsSound && !fileData.preloadAsMusic) {
-          onLoad();
-        } else if (fileData.preloadAsSound && fileData.preloadAsMusic) {
-          let loadedOnce = false;
-          const callback = (_, error) => {
-            if (!loadedOnce) {
-              loadedOnce = true;
-              return;
-            }
+
+        let loadCounter = 0;
+        const callback = (_?: any, error?: string) => {
+          loadCounter--;
+          if (!loadCounter) {
             onLoad(_, error);
-          };
+          }
+        };
 
+        if (fileData.preloadAsMusic) {
+          loadCounter++;
           preloadAudioFile(file, callback, /* isMusic= */ true);
+        }
+
+        if (fileData.preloadAsSound) {
+          loadCounter++;
           preloadAudioFile(file, callback, /* isMusic= */ false);
-        } else if (fileData.preloadAsSound) {
-          preloadAudioFile(file, onLoad, /* isMusic= */ false);
-        } else if (fileData.preloadAsMusic)
-          preloadAudioFile(file, onLoad, /* isMusic= */ true);
+        } else if (fileData.preloadInCache) {
+          // preloading as sound already does a XHR request, hence "else if"
+          loadCounter++;
+          const sound = new XMLHttpRequest();
+          sound.addEventListener('load', callback);
+          sound.addEventListener('error', (_) =>
+            callback(_, 'XHR error: ' + file)
+          );
+          sound.addEventListener('abort', (_) =>
+            callback(_, 'XHR abort: ' + file)
+          );
+          sound.open('GET', file);
+          sound.send();
+        }
+
+        if (!loadCounter) {
+          onLoad();
+        }
       };
       loadNextFile();
     }

GDJS/Runtime/types/project-data.d.ts

@@ -220,6 +220,7 @@ declare interface ResourceData {
   disablePreload?: boolean;
   preloadAsSound?: boolean;
   preloadAsMusic?: boolean;
+  preloadInCache?: boolean;
 }
 
 declare type ResourceKind =