Add docs to ICustomRole, remove GetNetData from ICustomRole to prevent overriding it

MiraAPI.Example/MiraDebugWindow.cs

@@ -1,6 +1,4 @@
-using MiraAPI.Example.Modifiers;
-using MiraAPI.Utilities;
-using Reactor.Utilities.Attributes;
+using Reactor.Utilities.Attributes;
 using Reactor.Utilities.ImGui;
 using System;
 using UnityEngine;
@@ -28,4 +26,4 @@ public class MiraDebugWindow(IntPtr ptr) : MonoBehaviour(ptr)
     {
         DebuggingWindow.OnGUI();
     }
-}
+}

MiraAPI.Example/Roles/FreezerRole.cs

@@ -9,7 +9,7 @@ public class FreezerRole : ImpostorRole, ICustomRole
 {
     public string RoleName => "Freezer";
     public string RoleLongDescription => "Freeze another player for a duration of time.";
-    public string RoleDescription => this.RoleLongDescription;
+    public string RoleDescription => RoleLongDescription;
     public Color RoleColor => Palette.Blue;
     public ModdedRoleTeams Team => ModdedRoleTeams.Impostor;
     public LoadableAsset<Sprite> OptionsScreenshot => ExampleAssets.Banner;

MiraAPI/GameModes/CustomGameModeManager.cs

@@ -1,5 +1,4 @@
-#nullable enable
-using Reactor.Utilities;
+using Reactor.Utilities;
 using System;
 using System.Collections.Generic;
 using System.Linq;

MiraAPI/Hud/CustomActionButton.cs

@@ -1,5 +1,4 @@
-#nullable enable
-using MiraAPI.Utilities.Assets;
+using MiraAPI.Utilities.Assets;
 using UnityEngine;
 using UnityEngine.Events;
 using UnityEngine.UI;

MiraAPI/Hud/CustomButtonSingleton.cs

@@ -1,5 +1,4 @@
-#nullable enable
-using System;
+using System;
 using System.Linq;
 
 namespace MiraAPI.Hud;

MiraAPI/MiraApiPlugin.cs

@@ -2,7 +2,6 @@
 using BepInEx.Unity.IL2CPP;
 using HarmonyLib;
 using MiraAPI.PluginLoading;
-using MiraAPI.Utilities;
 using Reactor;
 using Reactor.Networking;
 using Reactor.Networking.Attributes;

MiraAPI/Patches/HudManagerPatches.cs

@@ -1,5 +1,4 @@
-using System;
-using HarmonyLib;
+using HarmonyLib;
 using InnerNet;
 using MiraAPI.Hud;
 using MiraAPI.Roles;

MiraAPI/Patches/Options/GameSettingMenuPatches.cs

@@ -1,5 +1,4 @@
-#nullable enable
-using HarmonyLib;
+using HarmonyLib;
 using MiraAPI.PluginLoading;
 using MiraAPI.Utilities.Assets;
 using Reactor.Utilities.Extensions;

MiraAPI/Patches/Options/LobbyViewPanePatches.cs

@@ -1,5 +1,4 @@
-#nullable enable
-using System;
+using System;
 using System.Collections.Generic;
 using System.Linq;
 using HarmonyLib;

MiraAPI/Patches/Roles/RoleManagerPatches.cs

@@ -3,7 +3,6 @@ using HarmonyLib;
 using MiraAPI.Modifiers;
 using MiraAPI.Roles;
 using System.Linq;
-using UnityEngine;
 
 namespace MiraAPI.Patches.Roles;
 

MiraAPI/Roles/ICustomRole.cs

@@ -1,92 +1,159 @@
 using AmongUs.GameOptions;
 using BepInEx.Configuration;
-using HarmonyLib;
 using MiraAPI.Modifiers;
-using MiraAPI.Networking;
 using MiraAPI.PluginLoading;
 using MiraAPI.Utilities;
 using MiraAPI.Utilities.Assets;
-using System;
 using System.Text;
 using UnityEngine;
 
 namespace MiraAPI.Roles;
 
+/// <summary>
+/// Interface for custom roles.
+/// </summary>
 public interface ICustomRole
 {
+    /// <summary>
+    /// Gets the name of the role.
+    /// </summary>
     string RoleName { get; }
 
+    /// <summary>
+    /// Gets the description of the role. Used in the Intro Cutscene.
+    /// </summary>
     string RoleDescription { get; }
 
+    /// <summary>
+    /// Gets the long description of the role. Used in the Role Tab and Role Options.
+    /// </summary>
     string RoleLongDescription { get; }
 
+    /// <summary>
+    /// Gets the color of the role.
+    /// </summary>
     Color RoleColor { get; }
 
+    /// <summary>
+    /// Gets the team of the role.
+    /// </summary>
     ModdedRoleTeams Team { get; }
 
+    /// <summary>
+    /// Gets the **maximum amount** of players that can have this role at a time. This is not the same as the **number** of players that can have this role in a game.
+    /// </summary>
     int MaxPlayers => 15;
 
+    /// <summary>
+    /// Gets the Sprite used for the Role Options menu screenshot.
+    /// </summary>
     LoadableAsset<Sprite> OptionsScreenshot => MiraAssets.Empty;
 
+    /// <summary>
+    /// Gets the Sprite used for the Role Icon.
+    /// </summary>
     LoadableAsset<Sprite> Icon => MiraAssets.Empty;
 
-    ConfigDefinition NumConfigDefinition => new("Roles", $"Num {this.GetType().FullName}");
+    /// <summary>
+    /// Gets the BepInEx ConfigDefinition for the amount of players that can have this role.
+    /// </summary>
+    ConfigDefinition NumConfigDefinition => new("Roles", $"Num {GetType().FullName}");
 
-    ConfigDefinition ChanceConfigDefinition => new("Roles", $"Chance {this.GetType().FullName}");
+    /// <summary>
+    /// Gets the BepInEx ConfigDefinition for the chance of this role being selected.
+    /// </summary>
+    ConfigDefinition ChanceConfigDefinition => new("Roles", $"Chance {GetType().FullName}");
 
-    bool AffectedByLight => this.Team == ModdedRoleTeams.Crewmate;
+    /// <summary>
+    /// Gets a value indicating whether the role is affected by light sabotages.
+    /// </summary>
+    bool AffectedByLight => Team == ModdedRoleTeams.Crewmate;
 
-    bool CanGetKilled => this.Team == ModdedRoleTeams.Crewmate;
+    /// <summary>
+    /// Gets a value indicating whether the role can be killed by others.
+    /// </summary>
+    bool CanGetKilled => Team == ModdedRoleTeams.Crewmate;
 
-    bool CanKill => this.Team == ModdedRoleTeams.Impostor;
+    /// <summary>
+    /// Gets a value indicating whether the role can kill others.
+    /// </summary>
+    bool CanKill => Team == ModdedRoleTeams.Impostor;
 
-    bool CanUseVent => this.Team == ModdedRoleTeams.Impostor;
+    /// <summary>
+    /// Gets a value indicating whether the role can use vents.
+    /// </summary>
+    bool CanUseVent => Team == ModdedRoleTeams.Impostor;
 
-    bool TasksCount => this.Team == ModdedRoleTeams.Crewmate;
+    /// <summary>
+    /// Gets a value indicating whether the role's tasks count towards task progress.
+    /// </summary>
+    bool TasksCount => Team == ModdedRoleTeams.Crewmate;
 
+    /// <summary>
+    /// Gets a value indicating whether the role is a Ghost.
+    /// </summary>
     bool IsGhostRole => false;
 
+    /// <summary>
+    /// Unused for some reason.
+    /// </summary>
+    // TODO: change this to an enum
     bool CreateCustomTab => true;
 
-    bool HideSettings => this.IsGhostRole;
+    /// <summary>
+    /// Gets a value indicating whether the role should show up in the Role Options menu.
+    /// </summary>
+    bool HideSettings => IsGhostRole;
 
-    RoleTypes GhostRole => this.Team == ModdedRoleTeams.Impostor ? RoleTypes.ImpostorGhost : RoleTypes.CrewmateGhost;
+    /// <summary>
+    /// Gets the Ghost role that is applied when the player is killed.
+    /// </summary>
+    RoleTypes GhostRole => Team == ModdedRoleTeams.Impostor ? RoleTypes.ImpostorGhost : RoleTypes.CrewmateGhost;
 
+    /// <summary>
+    /// Gets the parent mod of this role.
+    /// </summary>
     MiraPluginInfo ParentMod => CustomRoleManager.FindParentMod(this);
 
     /// <summary>
-    /// Runs on the PlayerControl FixedUpdate method for any player with this role
+    /// This method runs on the PlayerControl.FixedUpdate method for ALL players with this role.
     /// </summary>
-    /// <param name="playerControl">The PlayerControl that has this role</param>
-    void PlayerControlFixedUpdate(PlayerControl playerControl) { }
+    /// <param name="playerControl">The PlayerControl that has this role.</param>
+    void PlayerControlFixedUpdate(PlayerControl playerControl)
+    {
+    }
 
     /// <summary>
-    /// Only runs for local player on HudManager Update method
+    /// This method runs on the HudManager.Update method ONLY when the LOCAL player has this role.
     /// </summary>
-    /// <param name="hudManager">Reference to HudManager instance</param>
-    void HudUpdate(HudManager hudManager) { }
+    /// <param name="hudManager">Reference to HudManager instance.</param>
+    void HudUpdate(HudManager hudManager)
+    {
+    }
 
+    /// <summary>
+    /// Gets a custom ejection message for the role. Return null to use the default message.
+    /// </summary>
+    /// <param name="player">The NetworkedPlayerInfo object for this player.</param>
+    /// <returns>A string with a custom ejection message or null.</returns>
     string? GetCustomEjectionMessage(NetworkedPlayerInfo player)
     {
-        return this.Team == ModdedRoleTeams.Impostor ? $"{player.PlayerName} was The {this.RoleName}" : null;
+        return Team == ModdedRoleTeams.Impostor ? $"{player.PlayerName} was The {RoleName}" : null;
     }
 
-    StringBuilder SetTabText()
-    {
-        var taskStringBuilder = Helpers.CreateForRole(this);
-        return taskStringBuilder;
-    }
+    /// <summary>
+    /// Get the custom Role Tab text for this role.
+    /// </summary>
+    /// <returns>A StringBuilder with the role tab text.</returns>
+    StringBuilder SetTabText() => Helpers.CreateForRole(this);
 
+    /// <summary>
+    /// Determine whether a given modifier can be applied to this role.
+    /// </summary>
+    /// <param name="modifier">The modifier to be tested.</param>
+    /// <returns>True if the modifier is valid on this role, false otherwise.</returns>
     bool IsModifierApplicable(BaseModifier modifier)
     {
         return true;
     }
-
-    NetData GetNetData()
-    {
-        this.ParentMod.PluginConfig.TryGetEntry<int>(this.NumConfigDefinition, out var numEntry);
-        this.ParentMod.PluginConfig.TryGetEntry<int>(this.ChanceConfigDefinition, out var chanceEntry);
-
-        return new NetData(RoleId.Get(this.GetType()), BitConverter.GetBytes(numEntry.Value).AddRangeToArray(BitConverter.GetBytes(chanceEntry.Value)));
-    }
 }

MiraAPI/Utilities/Extensions.cs

@@ -1,18 +1,36 @@
-#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using HarmonyLib;
 using MiraAPI.GameOptions;
 using MiraAPI.Modifiers;
 using MiraAPI.Networking;
+using MiraAPI.Roles;
 using Reactor.Networking.Attributes;
 using Reactor.Utilities;
-using System.Collections.Generic;
-using System.Linq;
 using UnityEngine;
 
 namespace MiraAPI.Utilities;
 
+/// <summary>
+/// Extension methods for various classes.
+/// </summary>
 public static class Extensions
 {
-    public static bool IsStatic(this System.Type type)
+    internal static NetData GetNetData(this ICustomRole role)
+    {
+        role.ParentMod.PluginConfig.TryGetEntry<int>(role.NumConfigDefinition, out var numEntry);
+        role.ParentMod.PluginConfig.TryGetEntry<int>(role.ChanceConfigDefinition, out var chanceEntry);
+
+        return new NetData(RoleId.Get(role.GetType()), BitConverter.GetBytes(numEntry.Value).AddRangeToArray(BitConverter.GetBytes(chanceEntry.Value)));
+    }
+
+    /// <summary>
+    /// Checks if a type is static.
+    /// </summary>
+    /// <param name="type">The type being checked.</param>
+    /// <returns>True if the type is static, false otherwise.</returns>
+    public static bool IsStatic(this Type type)
     {
         return type is { IsClass: true, IsAbstract: true, IsSealed: true };
     }