diff --git a/source/funkin/backend/system/ErrorCode.hx b/source/funkin/backend/system/ErrorCode.hx deleted file mode 100644 index c1121c0e..00000000 --- a/source/funkin/backend/system/ErrorCode.hx +++ /dev/null @@ -1,10 +0,0 @@ -package funkin.backend.system; - -enum abstract ErrorCode(Int) { - var OK = 0; - var FAILED = 1; - var MISSING_PROPERTY = 2; - var TYPE_INCORRECT = 3; - var VALUE_NULL = 4; - var REFLECT_ERROR = 5; -} \ No newline at end of file diff --git a/source/funkin/backend/system/github/GitHub.hx b/source/funkin/backend/system/github/GitHub.hx index ce7e61dc..1e29d143 100644 --- a/source/funkin/backend/system/github/GitHub.hx +++ b/source/funkin/backend/system/github/GitHub.hx @@ -7,6 +7,11 @@ import haxe.Json; import haxe.Exception; // TODO: Document further and perhaps make this a Haxelib. +/** + * Set of functions to interact with GitHub. + * Requires the `GITHUB_API` macro to be defined. + * This has no authentication, so it's limited to unauthenticated requests, and rate limits. +**/ class GitHub { /** * Gets all the releases from a specific GitHub repository using the GitHub API. diff --git a/source/funkin/backend/utils/CoolUtil.hx b/source/funkin/backend/utils/CoolUtil.hx index 86f68383..cd345844 100644 --- a/source/funkin/backend/utils/CoolUtil.hx +++ b/source/funkin/backend/utils/CoolUtil.hx @@ -40,9 +40,15 @@ import openfl.geom.ColorTransform; using StringTools; +/** + * Various utilities, that have no specific Util class. +**/ @:allow(funkin.game.PlayState) class CoolUtil { + /** + * Gets the last exception stack. Useful for debugging. + */ public static function getLastExceptionStack():String { return CallStack.toString(CallStack.exceptionStack()); } @@ -782,6 +788,15 @@ class CoolUtil return r; } + /** + * Quantizes a value to a certain amount. + * Example: `quantize(2.5543, 1)` will return `2.0` + * Example: `quantize(2.5543, 10)` will return `2.5` + * Example: `quantize(2.5543, 100)` will return `2.55` + * + * @param Value Value to quantize + * @param Quant Quantization amount + */ @:noUsing public static inline function quantize(Value:Float, Quant:Float) { return Math.fround(Value * Quant) / Quant; } @@ -799,9 +814,19 @@ class CoolUtil frontEnd.music = music; } + /** + * Gets the FlxEase from a string. + * @param mainEase Main ease + * @param suffix Suffix (Ignored if `mainEase` is `linear`) + */ @:noUsing public static inline function flxeaseFromString(mainEase:String, suffix:String) return Reflect.field(FlxEase, mainEase + (mainEase == "linear" ? "" : suffix)); + /** + * Sorts an array alphabetically. + * @param array Array to sort + * @param lowercase Whenever the array should be sorted in lowercase + */ public static function sortAlphabetically(array:Array, ?lowercase:Bool=false) { array.sort(function(a1, a2):Int { if(lowercase) { @@ -815,6 +840,11 @@ class CoolUtil return array; } + /** + * Pushes an element to an array, but only if it doesn't already exist. + * @param array Array to push to + * @param element Element to push + */ public static inline function pushOnce(array:Array, element:T) { #if (haxe >= "4.0.0") if (!array.contains(element)) @@ -826,6 +856,11 @@ class CoolUtil } #if !(haxe >= "4.0.0") + /** + * Checks if an array contains an element. + * @param array Array to check + * @param element Element to check + */ public static inline function contains(array:Array, element:T) { return array.indexOf(element) != -1; } @@ -927,6 +962,12 @@ class CoolUtil return result.join(separator); } + /** + * Deep flattens an array. + * Example: `deepFlatten([1, [2, 3], 4])` will return `[1, 2, 3, 4]` + * @param arr Array to flatten + * @param result Result array + */ public static function deepFlatten(arr:Array, ?result:Array):Array { if(arr == null) return []; if(result == null) result = []; @@ -942,7 +983,7 @@ class CoolUtil } /** - * SFXs to play using `playMenuSFX`. + * SFXs to play using `CoolUtil.playMenuSFX`. */ enum abstract CoolSfx(Int) from Int { var SCROLL = 0; diff --git a/source/funkin/backend/utils/MemoryUtil.hx b/source/funkin/backend/utils/MemoryUtil.hx index cd27cb0e..0d42e475 100644 --- a/source/funkin/backend/utils/MemoryUtil.hx +++ b/source/funkin/backend/utils/MemoryUtil.hx @@ -14,6 +14,12 @@ import openfl.system.System; using StringTools; +/** + * Tools that are related to memory. + * Including garbage collection, and memory usage, and hardware info. + * + * DISCLAIMER: Hardware info is only available on Native platforms. +**/ class MemoryUtil { public static var disableCount:Int = 0; @@ -34,12 +40,18 @@ class MemoryUtil { public static function init() {} + /** + * Does a minor garbage collection. + */ public static function clearMinor() { #if (cpp || java || neko) Gc.run(false); #end } + /** + * Does a full garbage collection. + */ public static function clearMajor() { #if cpp Gc.run(true); @@ -51,18 +63,29 @@ class MemoryUtil { #end } + /** + * Enables garbage collection. + */ public static function enable() { #if (cpp || hl) Gc.enable(true); #end } + /** + * Disables garbage collection. + * Fyi: doesn't fully disable garbage collection, but prevents it from running as much. + */ public static function disable() { #if (cpp || hl) Gc.enable(false); #end } + /** + * Gets the total memory of the system. + * Output depends on the hardware. + */ public static function getTotalMem():Float { #if windows @@ -76,6 +99,10 @@ class MemoryUtil { #end } + /** + * Gets the current memory usage of the app. + * DISCLAIMER: This gets the memory usage that is taken up by Haxe, not the actual memory usage of the app. + */ public static inline function currentMemUsage() { #if cpp return Gc.memInfo64(Gc.MEM_INFO_USAGE); @@ -89,6 +116,10 @@ class MemoryUtil { } + /** + * Gets the memory type of the system. + * Output depends on the platform, and hardware. + */ public static function getMemType():String { #if windows var memoryMap:Map = [ diff --git a/source/funkin/backend/utils/SortedArrayUtil.hx b/source/funkin/backend/utils/SortedArrayUtil.hx index ac317811..6afc0603 100644 --- a/source/funkin/backend/utils/SortedArrayUtil.hx +++ b/source/funkin/backend/utils/SortedArrayUtil.hx @@ -1,14 +1,16 @@ package funkin.backend.utils; /** - * All types of utils only usable in a sorted array. + * Tools to work with sorted arrays, in a more efficient way. + * + * DISCLAIMER: All types of utils only usable in a sorted array. */ class SortedArrayUtil { /** * Gets the index of a possible new element of an Array of T using an efficient algorithm. * @param array Array of T to check in * @param getVal Function that returns the position value of T - * @return Index + * @return The index of the element */ public static inline function binarySearch(array:Array, val:Float, getVal:T->Float):Int { if (array.length <= 0) return 0; // if the array is empty, it should be equal to zero (the beginning) @@ -46,4 +48,15 @@ class SortedArrayUtil { if (val != null) array.insert(binarySearch(array, getVal(val), getVal), val); } + + /** + * Removes from a sorted array, using binary search. + * @param array Array to remove from + * @param val Value to remove + * @param getVal Function that returns the value that needs to be sorted + */ + public static inline function removeSorted(array:Array, val:T, getVal:T->Float) { + if (val != null) + array.splice(binarySearch(array, getVal(val), getVal), 1); + } } \ No newline at end of file diff --git a/source/funkin/backend/utils/WindowUtils.hx b/source/funkin/backend/utils/WindowUtils.hx index 571f781a..43cd5f8d 100644 --- a/source/funkin/backend/utils/WindowUtils.hx +++ b/source/funkin/backend/utils/WindowUtils.hx @@ -3,9 +3,9 @@ package funkin.backend.utils; import openfl.Lib; class WindowUtils { - public static var winTitle(default, set):String; - private static function set_winTitle(value:String):String { - winTitle = value; + public static var title(default, set):String; + private static function set_title(value:String):String { + title = value; updateTitle(); return value; } @@ -28,7 +28,7 @@ class WindowUtils { static var __triedClosing:Bool = false; public static inline function resetClosing() __triedClosing = false; - public static inline function init() { + @:dox(hide) public static inline function init() { resetTitle(); resetClosing(); @@ -41,18 +41,27 @@ class WindowUtils { }); } + /** + * Resets the window title to the application name and resets the prefix and suffix. + **/ public static inline function resetTitle() { - winTitle = Lib.application.meta["name"]; + title = Lib.application.meta["name"]; resetAffixes(); } + /** + * Resets the prefix and suffix. + **/ public static inline function resetAffixes() { prefix = suffix = ""; updateTitle(); } + /** + * Updates the window title to have the current title and prefix/suffix. + **/ public static inline function updateTitle() - Lib.application.window.title = '$prefix$winTitle$suffix'; + Lib.application.window.title = '$prefix$title$suffix'; // backwards compat @:noCompletion public static var endfix(get, set):String; @@ -62,4 +71,12 @@ class WindowUtils { @:noCompletion private static function get_endfix():String { return suffix; } + + @:noCompletion public static var winTitle(get, set):String; + @:noCompletion private static function get_winTitle():String { + return title; + } + @:noCompletion private static function set_winTitle(value:String):String { + return title = value; + } } \ No newline at end of file diff --git a/source/funkin/backend/utils/XMLUtil.hx b/source/funkin/backend/utils/XMLUtil.hx index 95cb576a..0748323e 100644 --- a/source/funkin/backend/utils/XMLUtil.hx +++ b/source/funkin/backend/utils/XMLUtil.hx @@ -5,7 +5,6 @@ import flixel.util.typeLimit.OneOfTwo; import funkin.backend.FunkinSprite.XMLAnimType; import funkin.backend.FunkinSprite; import funkin.game.Character; -import funkin.backend.system.ErrorCode; import funkin.backend.FunkinSprite.XMLAnimType; import flixel.util.FlxColor; import haxe.xml.Access; @@ -18,17 +17,53 @@ import haxe.xml.Access; using StringTools; +@:dox(hide) +enum abstract ErrorCode(Int) { + var OK = 0; + var FAILED = 1; + var MISSING_PROPERTY = 2; + var TYPE_INCORRECT = 3; + var VALUE_NULL = 4; + var REFLECT_ERROR = 5; +} + +@:dox(hide) typedef TextFormat = { text:String, format:Dynamic } /** * Class made to make XML parsing easier. + * Used in Stage.hx, Character.hx, and more. */ class XMLUtil { - /** * Applies a property XML node to an object. + * The format for the XML is as follows: + * ```xml + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * ``` + * * @param object Object to which the xml property will be applied * @param property `property` node. + * @return Error code (0 = OK, 1 = FAILED, 2 = MISSING_PROPERTY, 3 = TYPE_INCORRECT, 4 = VALUE_NULL, 5 = REFLECT_ERROR) */ public static function applyXMLProperty(object:Dynamic, property:Access):ErrorCode { if (!property.has.name || !property.has.type || !property.has.value) { @@ -47,7 +82,8 @@ class XMLUtil { var value:Dynamic = switch(property.att.type.toLowerCase()) { case "f" | "float" | "number": Std.parseFloat(property.att.value); - case "i" | "int" | "integer" | "color": Std.parseInt(property.att.value); + case "i" | "int" | "integer": Std.parseInt(property.att.value); + case "c" | "color": FlxColor.fromString(property.att.value); case "s" | "string" | "str" | "text": property.att.value; case "b" | "bool" | "boolean": property.att.value.toLowerCase() == "true"; default: return TYPE_INCORRECT; @@ -72,7 +108,11 @@ class XMLUtil { } /** - * Overrides a sprite based on a XML node. + * Sets the properties of a sprite based on a XML node. + * @param spr The sprite + * @param node The XML node + * @param parentFolder The parent folder + * @param defaultAnimType The default animation type */ public static function loadSpriteFromXML(spr:FunkinSprite, node:Access, parentFolder:String = "", defaultAnimType:XMLAnimType = BEAT):FunkinSprite { if (parentFolder == null) parentFolder = ""; @@ -188,6 +228,11 @@ class XMLUtil { /** * Creates a new sprite based on a XML node. + * @param node The XML node + * @param parentFolder The parent folder + * @param defaultAnimType The default animation type + * @param cl The class to create (advanced) + * @param args The arguments to pass to the class (advanced) */ public static inline function createSpriteFromXML(node:Access, parentFolder:String = "", defaultAnimType:XMLAnimType = BEAT, ?cl:Class, ?args:Array):FunkinSprite { if(cl == null) cl = FunkinSprite; @@ -195,6 +240,12 @@ class XMLUtil { return loadSpriteFromXML(Type.createInstance(cl, args), node, parentFolder, defaultAnimType); } + /** + * Extracts an animation from an XML node. + * @param anim The animation node + * @param animType The animation type + * @param loop Whether the animation should loop + **/ public static function extractAnimFromXML(anim:Access, animType:XMLAnimType = NONE, loop:Bool = false):AnimData { var animData:AnimData = { name: null, @@ -233,6 +284,11 @@ class XMLUtil { return addAnimToSprite(sprite, extractAnimFromXML(anim, animType, loop)); } + /** + * Adds an animation to a sprite. + * @param sprite The sprite + * @param animData The animation data (gotten from `extractAnimFromXML`) + **/ public static function addAnimToSprite(sprite:FlxSprite, animData:AnimData):ErrorCode { if (animData.name != null) { if (animData.fps <= 0 #if web || animData.fps == null #end) animData.fps = 24; @@ -308,6 +364,17 @@ class XMLUtil { return node; } + /** + * Gets the text formats from an XML node. + * The format for the XML is as follows: + * ```xml + * Hello World + * ``` + * + * @param _node The XML node + * @param currentFormat The current format + * @param parsedSegments The parsed segments + **/ public static function getTextFormats(_node:OneOfTwo, currentFormat:Dynamic = null, parsedSegments:Array = null):Array { var node:Xml = cast _node; if (currentFormat == null)