From 87a1be741020a4a53a1a5afcd130f27bd67c26ec Mon Sep 17 00:00:00 2001 From: XtraCube <72575280+XtraCube@users.noreply.github.com> Date: Tue, 27 Aug 2024 14:59:16 -0400 Subject: [PATCH] modifiers README --- MiraAPI.Example/Buttons/ExampleButton.cs | 5 +++-- MiraAPI.Example/MiraDebugWindow.cs | 1 + .../GameModifierExample.cs} | 9 +++++---- .../{ => Modifiers}/ModifierTimerExample.cs | 5 +++-- MiraAPI/Modifiers/RegisterModifierAttribute.cs | 2 ++ .../Patches/Options/RoleSettingMenuPatches.cs | 2 +- MiraAPI/Utilities/Extensions.cs | 12 ++++++------ README.md | 17 ++++++++++++++++- 8 files changed, 37 insertions(+), 16 deletions(-) rename MiraAPI.Example/{ModifierExample.cs => Modifiers/GameModifierExample.cs} (53%) rename MiraAPI.Example/{ => Modifiers}/ModifierTimerExample.cs (82%) diff --git a/MiraAPI.Example/Buttons/ExampleButton.cs b/MiraAPI.Example/Buttons/ExampleButton.cs index e6dc949..4c9c7d6 100644 --- a/MiraAPI.Example/Buttons/ExampleButton.cs +++ b/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(); + return PlayerControl.LocalPlayer.HasModifier(); } } \ No newline at end of file diff --git a/MiraAPI.Example/MiraDebugWindow.cs b/MiraAPI.Example/MiraDebugWindow.cs index 5fa9a08..56718e8 100644 --- a/MiraAPI.Example/MiraDebugWindow.cs +++ b/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; diff --git a/MiraAPI.Example/ModifierExample.cs b/MiraAPI.Example/Modifiers/GameModifierExample.cs similarity index 53% rename from MiraAPI.Example/ModifierExample.cs rename to MiraAPI.Example/Modifiers/GameModifierExample.cs index aea6b77..2b491ae 100644 --- a/MiraAPI.Example/ModifierExample.cs +++ b/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() { diff --git a/MiraAPI.Example/ModifierTimerExample.cs b/MiraAPI.Example/Modifiers/ModifierTimerExample.cs similarity index 82% rename from MiraAPI.Example/ModifierTimerExample.cs rename to MiraAPI.Example/Modifiers/ModifierTimerExample.cs index 04d810b..e4b7832 100644 --- a/MiraAPI.Example/ModifierTimerExample.cs +++ b/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 diff --git a/MiraAPI/Modifiers/RegisterModifierAttribute.cs b/MiraAPI/Modifiers/RegisterModifierAttribute.cs index 3b25497..4c2fb56 100644 --- a/MiraAPI/Modifiers/RegisterModifierAttribute.cs +++ b/MiraAPI/Modifiers/RegisterModifierAttribute.cs @@ -1,4 +1,6 @@ using System; +namespace MiraAPI.Modifiers; + [AttributeUsage(AttributeTargets.Class)] public class RegisterModifierAttribute : Attribute; \ No newline at end of file diff --git a/MiraAPI/Patches/Options/RoleSettingMenuPatches.cs b/MiraAPI/Patches/Options/RoleSettingMenuPatches.cs index b7b46cd..fbcdb37 100644 --- a/MiraAPI/Patches/Options/RoleSettingMenuPatches.cs +++ b/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.Instance.GetString(role.StringName, Array.Empty()); + __instance.roleTitleText.text = DestroyableSingleton.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; diff --git a/MiraAPI/Utilities/Extensions.cs b/MiraAPI/Utilities/Extensions.cs index 60e4b9d..0dd4231 100644 --- a/MiraAPI/Utilities/Extensions.cs +++ b/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(); } public static List Randomize(this List list) { - List randomizedList = new List(); + List randomizedList = []; System.Random rnd = new(); while (list.Count > 0) { @@ -89,13 +89,13 @@ public static class Extensions return randomizedList; } - public static bool HasModifier(this PlayerControl player) where T : BaseModifier + public static bool HasModifier(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(this PlayerControl player) where T : BaseModifier diff --git a/README.md b/README.md index d57449c..c6eaba9 100644 --- a/README.md +++ b/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.