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.
AdvancedRole	Type	No	The role that will have access to these options. If not specified, the options will be available to all roles.

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;
}

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.

Here are the available Option Attributes and their signatures:

ModdedEnumOption(string name, Type enumType, Type roleType = null)
    
ModdedNumberOption(
    string name,
    float min,
    float max,
    float increment=1
    NumberSuffixes suffixType = NumberSuffixes.None,
    bool zeroInfinity = false,
    Type roleType = null)

ModdedToggleOption(string name, Type roleType = null)

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,
}

Role Options

In order to mark your options as role-specific, you need to specify the role type for the option or the group. Options that are marked as role-specific will only show up in the settings for that role.

To set the role type for an entire group, set the AdvancedRole property on that group like this:

public class MyOptionsGroup : AbstractOptionGroup
{
    public override string GroupName => "My Options";
    public override Type AdvancedRole => typeof(MyRole); // this is the role that will have these options
    
    [ModdedNumberOption("Ability Uses", min: 0, max: 10)]
    public float AbilityUses { get; set; } = 5f;
}

To set the role type for individual options, specify the roleType parameter in the option like this:

// this group doesnt specify a role, so it will show up in the global settings
public class MyOptionsGroup : AbstractOptionGroup
{
    public override string GroupName => "My Options";
    
    // this option will only show up in the settings for MyRole
    [ModdedNumberOption("Ability Uses", min: 0, max: 10, roleType: typeof(MyRole))]
    public float AbilityUses { get; set; } = 5f;
}

Here is an example class that specifies the role:

public class TeleporterOptions : AbstractOptionGroup
{
    public override string GroupName => "Teleporter";

    public override Type AdvancedRole => typeof(TeleporterRole); // this is the role that will have these options

    [ModdedNumberOption("Teleport Cooldown", 5, 60, 2.5f, MiraNumberSuffixes.Seconds)]
    public float TeleportCooldown { get; set; } = 5;

    [ModdedNumberOption("Teleport Duration", 5, 25, 1, MiraNumberSuffixes.Seconds)]
    public float TeleportDuration { get; set; } = 10;

    [ModdedNumberOption("Zoom Distance", 4, 15)]
    public float ZoomDistance { get; set; } = 6;
}