From 592e636903001c8c600a1363d3ff6d3a1ba4f3a0 Mon Sep 17 00:00:00 2001 From: XtraCube <72575280+XtraCube@users.noreply.github.com> Date: Fri, 30 Aug 2024 11:25:15 -0400 Subject: [PATCH] document Extensions.cs --- MiraAPI.Example/ExamplePlugin.cs | 3 +- MiraAPI.Example/MiraDebugWindow.cs | 2 +- MiraAPI/Modifiers/ModifierManager.cs | 12 +- MiraAPI/Utilities/Extensions.cs | 166 +++++++++++++++++++++++---- MiraAPI/Utilities/Helpers.cs | 2 +- 5 files changed, 153 insertions(+), 32 deletions(-) diff --git a/MiraAPI.Example/ExamplePlugin.cs b/MiraAPI.Example/ExamplePlugin.cs index 79ddabd..89ba051 100644 --- a/MiraAPI.Example/ExamplePlugin.cs +++ b/MiraAPI.Example/ExamplePlugin.cs @@ -22,6 +22,5 @@ public partial class ExamplePlugin : BasePlugin, IMiraPlugin public override void Load() { Harmony.PatchAll(); - AddComponent(); } -} \ No newline at end of file +} diff --git a/MiraAPI.Example/MiraDebugWindow.cs b/MiraAPI.Example/MiraDebugWindow.cs index f01d3ac..9b0fa7e 100644 --- a/MiraAPI.Example/MiraDebugWindow.cs +++ b/MiraAPI.Example/MiraDebugWindow.cs @@ -19,7 +19,7 @@ public class MiraDebugWindow(IntPtr ptr) : MonoBehaviour(ptr) } }) { - Enabled = true + Enabled = true, }; public void OnGUI() diff --git a/MiraAPI/Modifiers/ModifierManager.cs b/MiraAPI/Modifiers/ModifierManager.cs index ad0d71d..4a0f418 100644 --- a/MiraAPI/Modifiers/ModifierManager.cs +++ b/MiraAPI/Modifiers/ModifierManager.cs @@ -52,7 +52,7 @@ public static class ModifierManager continue; } - if (!plrs.Any(x=>IsGameModifierValid(x, mod, modifier.Key))) + if (!plrs.Exists(x=>IsGameModifierValid(x, mod, modifier.Key))) { Logger.Warning("No players are valid for modifier: " + mod.ModifierName); continue; @@ -79,25 +79,25 @@ public static class ModifierManager { shuffledModifiers = shuffledModifiers.GetRange(0, plrs.Count); } - + while (shuffledModifiers.Count > 0) { var id = shuffledModifiers[0]; var mod = (GameModifier)Activator.CreateInstance(IdToTypeModifiers[id]); - + if (mod is null) { Logger.Error($"Failed to create instance of {IdToTypeModifiers[id].Name}"); continue; } - - if (!plrs.Any(x=>IsGameModifierValid(x, mod, id))) + + if (!plrs.Exists(x=>IsGameModifierValid(x, mod, id))) { shuffledModifiers.RemoveAt(0); continue; } - + var plr = plrs.Random(); if (!IsGameModifierValid(plr, mod, id)) diff --git a/MiraAPI/Utilities/Extensions.cs b/MiraAPI/Utilities/Extensions.cs index ab51417..0ea5415 100644 --- a/MiraAPI/Utilities/Extensions.cs +++ b/MiraAPI/Utilities/Extensions.cs @@ -35,13 +35,29 @@ public static class Extensions return type is { IsClass: true, IsAbstract: true, IsSealed: true }; } + /// + /// Gets a darkened version of a color. + /// + /// The original color. + /// A darkness amount between 0 and 255. + /// The darkened color. public static Color32 GetShadowColor(this Color32 color, byte darknessAmount) { return - new Color32((byte)Mathf.Clamp(color.r - darknessAmount, 0, 255), (byte)Mathf.Clamp(color.g - darknessAmount, 0, 255), - (byte)Mathf.Clamp(color.b - darknessAmount, 0, 255), byte.MaxValue); + new Color32( + (byte)Mathf.Clamp(color.r - darknessAmount, 0, 255), + (byte)Mathf.Clamp(color.g - darknessAmount, 0, 255), + (byte)Mathf.Clamp(color.b - darknessAmount, 0, 255), + byte.MaxValue); } + /// + /// Truncates a string to a specified length. + /// + /// The original string. + /// The maximum length. + /// An option suffix to attach at the end of the truncated string. + /// A truncated string of maxLength with the attached suffix. public static string? Truncate(this string? value, int maxLength, string truncationSuffix = "…") { return value?.Length > maxLength @@ -49,6 +65,12 @@ public static class Extensions : value; } + /// + /// Chunks a collection of NetData into smaller arrays. + /// + /// A collection of NetData objects. + /// The max chunk size in bytes. + /// A Queue of NetData arrays. public static Queue ChunkNetData(this IEnumerable dataCollection, int chunkSize) { Queue chunks = []; @@ -83,14 +105,23 @@ public static class Extensions return chunks; } - + /// + /// Determines if a given OptionBehaviour is for a custom option. + /// + /// The OptionBehaviour to be tested. + /// True if the OptionBehaviour is for a custom options, false otherwise. public static bool IsCustom(this OptionBehaviour optionBehaviour) { return ModdedOptionsManager.ModdedOptions.Values.Any(opt => opt.OptionBehaviour && opt.OptionBehaviour.Equals(optionBehaviour)); } - public static readonly Dictionary ModifierComponents = new(); + private static readonly Dictionary ModifierComponents = []; + /// + /// Gets the ModifierComponent for a player. + /// + /// The PlayerControl object. + /// A ModifierComponent if there is one, null otherwise. public static ModifierComponent? GetModifierComponent(this PlayerControl player) { if (ModifierComponents.TryGetValue(player, out var component)) @@ -107,6 +138,12 @@ public static class Extensions return component; } + /// + /// Randomizes a list. + /// + /// The list object. + /// The type of object the list contains. + /// A randomized list made from the original list. public static List Randomize(this List list) { List randomizedList = []; @@ -120,39 +157,88 @@ public static class Extensions return randomizedList; } + /// + /// Gets a modifier by its type, or null if the player doesn't have it. + /// + /// The PlayerControl object. + /// The Type of the Modifier. + /// The Modifier if it is found, null otherwise. public static T? GetModifier(this PlayerControl? player) where T : BaseModifier { return player?.GetModifierComponent()?.ActiveModifiers.Find(x => x is T) as T; } + /// + /// Checks if a player has a modifier. + /// + /// The PlayerControl object. + /// The Type of the Modifier. + /// True if the Modifier is present, false otherwise. public static bool HasModifier(this PlayerControl? player) where T : BaseModifier { return player?.GetModifierComponent() != null && player.GetModifierComponent()!.ActiveModifiers.Exists(x => x is T); } + /// + /// Checks if a player has a modifier by its ID. + /// + /// The PlayerControl object. + /// The Modifier ID. + /// True if the Modifier is present, false otherwise. public static bool HasModifier(this PlayerControl? player, uint id) { return player?.GetModifierComponent() != null && player.GetModifierComponent()!.ActiveModifiers.Exists(x => x.ModifierId == id); } + /// + /// Remote Procedure Call to remove a modifier from a player. + /// + /// The player to remove the modifier from. + /// The ID of the modifier. [MethodRpc((uint)MiraRpc.RemoveModifier)] public static void RpcRemoveModifier(this PlayerControl target, uint modifierId) { target.GetModifierComponent()?.RemoveModifier(modifierId); } + /// + /// Remote Procedure Call to remove a modifier from a player. + /// + /// The player to remove the modifier from. + /// The Type of the Modifier. + public static void RpcRemoveModifier(this PlayerControl player) where T : BaseModifier + { + if (!ModifierManager.TypeToIdModifiers.TryGetValue(typeof(T), out var id)) + { + Logger.Error($"Cannot add modifier {typeof(T).Name} because it is not registered."); + return; + } + + player.RpcRemoveModifier(id); + } + + /// + /// Remote Procedure Call to add a modifier to a player. + /// + /// The player to add the modifier to. + /// The modifier ID. [MethodRpc((uint)MiraRpc.AddModifier)] - public static BaseModifier? RpcAddModifier(this PlayerControl target, uint modifierId) + public static void RpcAddModifier(this PlayerControl target, uint modifierId) { if (ModifierManager.IdToTypeModifiers.TryGetValue(modifierId, out var type)) { - return target.GetModifierComponent()?.AddModifier(type); + target.GetModifierComponent()?.AddModifier(type); + return; } Logger.Error($"Cannot add modifier with id {modifierId} because it is not registered."); - return null; } + /// + /// Remote Procedure Call to add a modifier to a player. + /// + /// The player to add the modifier to. + /// The modifier Type. public static void RpcAddModifier(this PlayerControl player) where T : BaseModifier { if (!ModifierManager.TypeToIdModifiers.TryGetValue(typeof(T), out var id)) @@ -164,46 +250,82 @@ public static class Extensions player.RpcAddModifier(id); } - public static void RpcRemoveModifier(this PlayerControl player) where T : BaseModifier - { - if (!ModifierManager.TypeToIdModifiers.TryGetValue(typeof(T), out var id)) - { - Logger.Error($"Cannot add modifier {typeof(T).Name} because it is not registered."); - return; - } - - player.RpcAddModifier(id); - } - + /// + /// Darkens a color by a specified amount. + /// + /// The original color. + /// A float amount between 0 and 1. + /// The darkened color. public static Color DarkenColor(this Color color, float amount = 0.45f) { return new Color(color.r - amount, color.g - amount, color.b - amount); } + + /// + /// Gets an alternate color based on the original color. + /// + /// The original color. + /// The amount to darken or lighten the original color by between 0.0 and 1.0. + /// An alternate color that has been darkened or lightened. public static Color GetAlternateColor(this Color color, float amount = 0.45f) { return color.IsColorDark() ? LightenColor(color, amount) : DarkenColor(color, amount); } + /// + /// Lightens a color by a specified amount. + /// + /// The original color. + /// A float amount between 0.0 and 1.0. + /// The lightened color. public static Color LightenColor(this Color color, float amount = 0.45f) { return new Color(color.r + amount, color.g + amount, color.b + amount); } + /// + /// Checks if a color is dark. + /// + /// The color to check. + /// True if the color is dark, false otherwise. public static bool IsColorDark(this Color color) { return color.r < 0.5f && color is { g: < 0.5f, b: < 0.5f }; } + /// + /// Gets the nearest dead body to a player. + /// + /// The player object. + /// The radius to search within. + /// The dead body if it is found, or null there is none within the radius. public static DeadBody? GetNearestDeadBody(this PlayerControl playerControl, float radius) { - return Helpers.GetNearestDeadBodies(playerControl.GetTruePosition(), radius).FirstOrDefault(component => component && !component.Reported); + return Helpers.GetNearestDeadBodies(playerControl.GetTruePosition(), radius).Find(component => component && !component.Reported); } - public static T? GetNearestObjectOfType(this PlayerControl playerControl, float radius, string? colliderTag = null, System.Func? predicate = null) where T : Component + /// + /// Finds the nearest object of a specified type to a player. It will only work if the object has a collider. + /// + /// The player object. + /// The radius to search within. + /// An optional collider tag. + /// Optional predicate to test if the object is valid. + /// The type of the object. + /// The object if it was found, or null if there is none within the radius. + public static T? GetNearestObjectOfType(this PlayerControl playerControl, float radius, string? colliderTag = null, Predicate? predicate = null) where T : Component { - return Helpers.GetNearestObjectsOfType(playerControl.GetTruePosition(), radius, colliderTag).FirstOrDefault(predicate ?? (component => component)); + return Helpers.GetNearestObjectsOfType(playerControl.GetTruePosition(), radius, colliderTag).Find(predicate ?? (component => component)); } + /// + /// Gets the nearest player to a player. + /// + /// The player object. + /// Whether impostors should be included in the search. + /// The radius to search within. + /// Whether colliders should be ignored when searching. + /// The closest player if there is one, false otherwise. public static PlayerControl? GetClosestPlayer(this PlayerControl playerControl, bool includeImpostors, float distance, bool ignoreColliders = false) { if (!ShipStatus.Instance) @@ -217,4 +339,4 @@ public static class Extensions return filteredPlayers.First(); } -} \ No newline at end of file +} diff --git a/MiraAPI/Utilities/Helpers.cs b/MiraAPI/Utilities/Helpers.cs index 232fb3e..ab2cf63 100644 --- a/MiraAPI/Utilities/Helpers.cs +++ b/MiraAPI/Utilities/Helpers.cs @@ -25,7 +25,7 @@ public static class Helpers .Select(collider2D => collider2D.GetComponent()).ToList(); } - public static List GetNearestObjectsOfType(Vector2 source, float radius, string colliderTag = null) where T : Component + public static List GetNearestObjectsOfType(Vector2 source, float radius, string? colliderTag = null) where T : Component { var results = new Il2CppSystem.Collections.Generic.List(); Physics2D.OverlapCircle(source, radius, Filter, results);