Options

Options are pretty 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 is required to be part of a Group.

Option Groups

To create a group, you need to create a class that inherits from the AbstractOptionGroup abstract class. This class contains the following properties:

Property	Type	Required	Description
GroupName	string	Yes	The name of the group.
GroupVisible	Func<bool>	No	A function that determines if the option is visible or not.
GroupColor	Color	No	The color of the group.
OptionableType	Type?	No	The "object" this option group will be associated with. Mira currently supports roles and modifiers as "Optionable" types.

Here is an example of a group class:

public class MyOptionsGroup : AbstractOptionGroup
{
    public override string GroupName => "My Options"; // this is required
    
    [ModdedNumberOption("My Number Option", min: 0, max: 10)]
    public float MyNumberOption { get; set; } = 5f;
}

To associate a group with a specific role or modifier, you can set the OptionableType property or use the generic parameter. This is useful for role-specific options or modifier-specific options.

Associating a group with a role will display the options in the role's settings menu, found by clicking the cog icon next to a role name.

Associating a group with a modifier will display the options in the modifier's settings menu.

public class MyRoleOptionsGroup : AbstractOptionGroup<MyRole> // using generic parameter
{
    public override string GroupName => "My Role Options";
    
    [ModdedNumberOption("My Role Uses", min: 0, max: 10)]
    public float MyRoleUses { get; set; } = 5f;
}

public class MyModifierOptionsGroup : AbstractOptionGroup
{
    public override string GroupName => "My Modifier Options";

    public override Type OptionableType => typeof(MyModifier); // setting the OptionableType property
    
    [ModdedNumberOption("My Modifier Uses", min: 0, max: 10)]
    public float MyRoleUses { get; set; } = 5f;
}

Accessing Option Groups

You can access any group class from any place in your code using the OptionGroupSingleton class like this:

// MyOptionsGroup is a class that inherits from AbstractOptionGroup
var myGroup = OptionGroupSingleton<MyOptionsGroup>.Instance; // gets the instance of the group
Logger<MyPlugin>.Info(myGroup.MyNumberOption); // prints the value of the option to the console

Creating Options

Once you have an options group, there are two ways to make the actual options:

• Use an Option Attribute with a property.
• Create a ModdedOption property.

Option Attributes

This is an example of using an Option Attribute on a property:

// The first parameter is always the name of the option. The rest are dependent on the type of option.
[ModdedNumberOption("Sussy level", min: 0, max: 10)]
public float SussyLevel { get; set; } = 4f; // You can set a default value here.

The following option attributes are currently available in Mira API:

ModdedEnumOption(string name, Type enumType, string[]? values = null)
    
ModdedNumberOption(
    string title,
    float min,
    float max,
    float increment=1
    NumberSuffixes suffixType = NumberSuffixes.None,
    string? formatString = null,
    bool zeroInfinity = false)

ModdedToggleOption(string name)

ModdedOption Properties

The main advantage to ModdedOption properties is the ability to set the Visible and ChangedEvent properties.

The Visible property is a function that determines if the option is visible or not. The ChangedEvent property is a function that is called when the option is changed.

Here is a list of the ModdedOption classes that Mira provides:

• ModdedEnumOption
• ModdedNumberOption
• ModdedToggleOption

Here is an example class that uses these properties:

public class ExampleOptions2 : AbstractOptionGroup
{
    public override string GroupName => "Example Options 2";

    public ModdedToggleOption ToggleOpt1 { get; } = new("Toggle Option 1", false);

    public ModdedToggleOption ToggleOpt2 { get; } = new("Toggle Option 2", false)
    {
        Visible = () => OptionGroupSingleton<ExampleOptions2>.Instance.ToggleOpt1.Value,
    };

    public ModdedEnumOption EnumOpt { get; } = new("Enum Opt", 0, typeof(TestingData))
    {
        ChangedEvent = x => Logger<ExamplePlugin>.Info($"changed Enum Opt to {x}"),
    };
}

public enum TestingData
{
    Happy,
    Sad,
    Neutral,
}