modifiers README

MiraAPI.Example/Buttons/ExampleButton.cs

@@ -1,4 +1,5 @@
-using MiraAPI.Hud;
+using MiraAPI.Example.Modifiers;
+using MiraAPI.Hud;
 using MiraAPI.Utilities;
 using MiraAPI.Utilities.Assets;
 using Reactor.Utilities;
@@ -23,6 +24,6 @@ public class ExampleButton : CustomActionButton
 
     public override bool Enabled(RoleBehaviour role)
     {
-        return PlayerControl.LocalPlayer.HasModifier<ModifierExample>();
+        return PlayerControl.LocalPlayer.HasModifier<GameModifierExample>();
     }
 }

MiraAPI.Example/MiraDebugWindow.cs

@@ -2,6 +2,7 @@
 using Reactor.Utilities.Attributes;
 using Reactor.Utilities.ImGui;
 using System;
+using MiraAPI.Example.Modifiers;
 using UnityEngine;
 
 namespace MiraAPI.Example;

MiraAPI.Example/Modifiers/GameModifierExample.cs

@@ -1,11 +1,12 @@
-using MiraAPI.Modifiers.Types;
+using MiraAPI.Modifiers;
+using MiraAPI.Modifiers.Types;
 
-namespace MiraAPI.Example;
+namespace MiraAPI.Example.Modifiers;
 
 [RegisterModifier]
-public class ModifierExample : GameModifier
+public class GameModifierExample : GameModifier
 {
-    public override string ModifierName => "Example Modifier";
+    public override string ModifierName => "Example Game Modifier";
 
     public override bool CanVent()
     {

MiraAPI.Example/Modifiers/ModifierTimerExample.cs

@@ -1,6 +1,7 @@
-using MiraAPI.Modifiers.Types;
+using MiraAPI.Modifiers;
+using MiraAPI.Modifiers.Types;
 
-namespace MiraAPI.Example;
+namespace MiraAPI.Example.Modifiers;
 
 [RegisterModifier]
 public class ModifierTimerExample : TimedModifier

MiraAPI/Modifiers/RegisterModifierAttribute.cs

@@ -1,4 +1,6 @@
 using System;
 
+namespace MiraAPI.Modifiers;
+
 [AttributeUsage(AttributeTargets.Class)]
 public class RegisterModifierAttribute : Attribute;

MiraAPI/Patches/Options/RoleSettingMenuPatches.cs

@@ -223,7 +223,7 @@ public static class RoleSettingMenuPatches
     {
         ICustomRole customRole = role as ICustomRole;
         __instance.roleDescriptionText.text = customRole.RoleLongDescription;
-        __instance.roleTitleText.text = DestroyableSingleton<TranslationController>.Instance.GetString(role.StringName, Array.Empty<Il2CppSystem.Object>());
+        __instance.roleTitleText.text = DestroyableSingleton<TranslationController>.Instance.GetString(role.StringName, []);
         __instance.roleScreenshot.sprite = Sprite.Create(customRole.OptionsScreenshot.LoadAsset().texture, new Rect(0, 0, 370, 230), Vector2.one / 2, 100);
         __instance.roleScreenshot.drawMode = SpriteDrawMode.Sliced;
         __instance.roleHeaderSprite.color = customRole.RoleColor;

MiraAPI/Utilities/Extensions.cs

@@ -71,14 +71,14 @@ public static class Extensions
         return ModdedOptionsManager.ModdedOptions.Values.Any(opt => opt.OptionBehaviour && opt.OptionBehaviour.Equals(optionBehaviour));
     }
 
-    public static ModifierComponent GetModifierComponent(this PlayerControl player)
+    public static ModifierComponent? GetModifierComponent(this PlayerControl player)
     {
         return player.GetComponent<ModifierComponent>();
     }
 
     public static List<T> Randomize<T>(this List<T> list)
     {
-        List<T> randomizedList = new List<T>();
+        List<T> randomizedList = [];
         System.Random rnd = new();
         while (list.Count > 0)
         {
@@ -89,13 +89,13 @@ public static class Extensions
         return randomizedList;
     }
 
-    public static bool HasModifier<T>(this PlayerControl player) where T : BaseModifier
+    public static bool HasModifier<T>(this PlayerControl? player) where T : BaseModifier
     {
-        return player is not null && player.GetModifierComponent() is not null && player.GetModifierComponent().ActiveModifiers.Exists(x => x is T);
+        return player?.GetModifierComponent() != null && player.GetModifierComponent().ActiveModifiers.Exists(x => x is T);
     }
-    public static bool HasModifier(this PlayerControl player, uint id)
+    public static bool HasModifier(this PlayerControl? player, uint id)
     {
-        return player is not null && player.GetModifierComponent() is not null && player.GetModifierComponent().ActiveModifiers.Exists(x => x.ModifierId == id);
+        return player?.GetModifierComponent() != null && player.GetModifierComponent().ActiveModifiers.Exists(x => x.ModifierId == id);
     }
 
     public static void AddModifier<T>(this PlayerControl player) where T : BaseModifier

README.md

@@ -5,10 +5,10 @@
 A thorough, but simple, Among Us modding API and utility library that covers:
 - Roles
 - Options
+- Modifiers
 - Buttons
 - Assets
 - Compatibility
-- ~~Modifiers~~ (coming soon)
 - ~~Game Modes~~ (coming soon)
 
 Mira API strives to be simple and easy to use, while also using as many base game elements as possible. The result is a less intrusive, better modding API that covers general use cases.
@@ -62,6 +62,21 @@ Mira API handles everything else, from adding the proper options to the settings
 
 See [this file](https://github.com/All-Of-Us-Mods/MiraAPI/blob/master/MiraAPI.Example/Roles/CustomRole.cs) for a code example.
 
+## Modifiers
+Mira API uses a different definition of 'modifiers' than other Among Us mods. For example, in Town Of Us, a modifier is an extra "ability" that is applied on top of the base role. However, in Mira API, modifiers are very flexible. A modifier is anything that "modifiers" a player's abilities or interactions.
+
+Mira provides 3 classes for working with modifiers:
+- `BaseModifier`: The base for every modifier. You MUST add and remove this modifier from a player manually!
+- `TimedModifier`: A modifier that has a time limit. This modifier has to be added manually, but will automatically remove itself after the time limit
+- `GameModifier`: This works like the typical TOU modifier, where it is automatically applied at the beginning of the game, then removed at the end.
+
+Modifiers provide various overridable functions and properties for custom behaviour. They can also be used for "tagging" a player. You can check if a player has a modifier through the extension method `HasModifier` on a `PlayerControl` object.
+
+To start using a modifier, pick one of the base classes above and create a class that inherits from it. Implement the properties and methods you would like, then add the `[RegisterModifier]` attribute to the class.
+
+An example Game modifier can be found [here](https://github.com/All-Of-Us-Mods/MiraAPI/blob/master/MiraAPI.Example/Modifiers/ExampleGameModifier.cs).
+An example Timer modifier can be found [here](https://github.com/All-Of-Us-Mods/MiraAPI/blob/master/MiraAPI.Example/Modifiers/ModifierTimerExample.cs).
+
 ## Options
 Options are also very simple in Mira API. Mira API handles all the hard work behind the scenes, so developers only have to follow a few steps to create their custom options. The Options API is split up into Groups and Options. Every Option needs to be in a Group.