From d30fe61ca07d9565a2142d5a044f2cd4558e7aa6 Mon Sep 17 00:00:00 2001
From: EliteMasterEric <ericmyllyoja@gmail.com>
Date: Wed, 18 Sep 2024 05:03:04 -0400
Subject: [PATCH] Add a bunch of other functions to funkin.Assets, and add
 documentation

---
 source/funkin/Assets.hx | 150 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 134 insertions(+), 16 deletions(-)

diff --git a/source/funkin/Assets.hx b/source/funkin/Assets.hx
index 05423c572..967e4b0ca 100644
--- a/source/funkin/Assets.hx
+++ b/source/funkin/Assets.hx
@@ -1,43 +1,161 @@
 package funkin;
 
+import openfl.utils.Future;
+
 /**
  * A wrapper around `openfl.utils.Assets` which disallows access to the harmful functions.
  * Later we'll add Funkin-specific caching to this.
  */
 class Assets
 {
-  public static function getText(path:String):String
-  {
-    return openfl.utils.Assets.getText(path);
-  }
-
+  /**
+   * Get the file system path for an asset
+   * @param path The asset path to load from, relative to the assets folder
+   * @return The path to the asset on the file system
+   */
   public static function getPath(path:String):String
   {
     return openfl.utils.Assets.getPath(path);
   }
 
-  public static function getMusic(path:String):openfl.media.Sound
-  {
-    return openfl.utils.Assets.getMusic(path);
-  }
-
-  public static function getBitmapData(path:String):openfl.display.BitmapData
-  {
-    return openfl.utils.Assets.getBitmapData(path);
-  }
-
+  /**
+   * Load bytes from an asset
+   * May cause stutters or throw an error if the asset is not cached
+   * @param path The asset path to load from
+   * @return The byte contents of the file
+   */
   public static function getBytes(path:String):haxe.io.Bytes
   {
     return openfl.utils.Assets.getBytes(path);
   }
 
+  /**
+   * Load bytes from an asset asynchronously
+   * @param path The asset path to load from
+   * @return A future which promises to return the byte contents of the file
+   */
+  public static function loadBytes(path:String):Future<openfl.utils.ByteArray>
+  {
+    return openfl.utils.Assets.loadBytes(path);
+  }
+
+  /**
+   * Load text from an asset.
+   * May cause stutters or throw an error if the asset is not cached
+   * @param path The asset path to load from
+   * @return The text contents of the file
+   */
+  public static function getText(path:String):String
+  {
+    return openfl.utils.Assets.getText(path);
+  }
+
+  /**
+   * Load text from an asset asynchronously
+   * @param path The asset path to load from
+   * @return A future which promises to return the text contents of the file
+   */
+  public static function loadText(path:String):Future<String>
+  {
+    return openfl.utils.Assets.loadText(path);
+  }
+
+  /**
+   * Load a Sound file from an asset
+   * May cause stutters or throw an error if the asset is not cached
+   * @param path The asset path to load from
+   * @return The loaded sound
+   */
+  public static function getSound(path:String):openfl.media.Sound
+  {
+    return openfl.utils.Assets.getSound(path);
+  }
+
+  /**
+   * Load a Sound file from an asset asynchronously
+   * @param path The asset path to load from
+   * @return A future which promises to return the loaded sound
+   */
+  public static function loadSound(path:String):Future<openfl.media.Sound>
+  {
+    return openfl.utils.Assets.loadSound(path);
+  }
+
+  /**
+   * Load a Sound file from an asset, with optimizations specific to long-duration music
+   * May cause stutters or throw an error if the asset is not cached
+   * @param path The asset path to load from
+   * @return The loaded sound
+   */
+  public static function getMusic(path:String):openfl.media.Sound
+  {
+    return openfl.utils.Assets.getMusic(path);
+  }
+
+  /**
+   * Load a Sound file from an asset asynchronously, with optimizations specific to long-duration music
+   * @param path The asset path to load from
+   * @return A future which promises to return the loaded sound
+   */
+  public static function loadMusic(path:String):Future<openfl.media.Sound>
+  {
+    return openfl.utils.Assets.loadMusic(path);
+  }
+
+  /**
+   * Load a Bitmap from an asset
+   * May cause stutters or throw an error if the asset is not cached
+   * @param path The asset path to load from
+   * @return The loaded Bitmap image
+   */
+  public static function getBitmapData(path:String):openfl.display.BitmapData
+  {
+    return openfl.utils.Assets.getBitmapData(path);
+  }
+
+  /**
+   * Load a Bitmap from an asset asynchronously
+   * @param path The asset path to load from
+   * @return The future which promises to return the loaded Bitmap image
+   */
+  public static function loadBitmapData(path:String):Future<openfl.display.BitmapData>
+  {
+    return openfl.utils.Assets.loadBitmapData(path);
+  }
+
+  /**
+   * Determines whether the given asset of the given type exists.
+   * @param path The asset path to check
+   * @param type The asset type to check
+   * @return Whether the asset exists
+   */
   public static function exists(path:String, ?type:openfl.utils.AssetType):Bool
   {
     return openfl.utils.Assets.exists(path, type);
   }
 
-  public static function list(type:openfl.utils.AssetType):Array<String>
+  /**
+   * Retrieve a list of all assets of the given type
+   * @param type The asset type to check
+   * @return A list of asset paths
+   */
+  public static function list(?type:openfl.utils.AssetType):Array<String>
   {
     return openfl.utils.Assets.list(type);
   }
+
+  public static function hasLibrary(name:String):Bool
+  {
+    return openfl.utils.Assets.hasLibrary(name);
+  }
+
+  public static function getLibrary(name:String):lime.utils.AssetLibrary
+  {
+    return openfl.utils.Assets.getLibrary(name);
+  }
+
+  public static function loadLibrary(name:String):Future<openfl.utils.AssetLibrary>
+  {
+    return openfl.utils.Assets.loadLibrary(name);
+  }
 }