Hamunii.ModMenuAPI 0.3.0-dev

ModMenuAPI

[!NOTE]
This API is not quite yet released.

An API to add your stuff as buttons on a menu that is accessible during gameplay.

Support

[!TIP]
Is your platform not supported? Open an issue, and let's discuss implementing it! ModMenuAPI is very lightweight, and it isn't heavily tied to any platform.

Mods using this API

[!NOTE]
First-party mods using this API are found in the ModMenuAPI.Plugin repository.

Usage For Developers

ModMenuAPI is used by registering menu items with an instance of ModMenu(string menuTitle):
public ModMenu RegisterItem(MMItemBase menuItem); which this can be chained, or via a static method:
public static T RegisterItem<T>(T menuItem, string menuTitle) where T : MMItemBase.

The fundamental building block for each mod menu item is MMItemBase, but we have specialized buttons for certain behaviors. The menu items are as follows:

• MMButtonAction
• MMButtonToggle
• MMButtonToggleInstantiable
• MMButtonMenu
• MMButtonMenuInstantiable

The Instantiable versions are like dummy buttons that don't do anything special, but we can still access their states (MMButtonToggle's Enabled value) or other data, like the MMButtonMenu's MenuItems field.

A menu button is just another submenu, but opened by clicking a button. These are rather powerful, since a lot of options can be put under one, and it opens up much more possibilities despite the UI options being otherwise limited, like the current lack of text or number input fields.

Getting Started

ModMenuAPI is available on NuGet, and you can add the following package to your csproj file:

[!WARNING]
There are no release builds yet! Consider using this only after a release build exists.

<ItemGroup>
    <PackageReference Include="Hamunii.ModMenuAPI" Version="0.*-*" />
</ItemGroup>

Usage Example

using ModMenuAPI.ModMenuItems;

class CWPatches
{
    internal static void Init()
    {
        // This is the primary way of registering items, through an instance of `ModMenu`.
        // We register an item with instance of a class that inherits MMItemBase.
        new ModMenu("Player")
            .RegisterItem(new InfiniteJumpToggle())
            .RegisterItem(new SomeOtherToggle());

        // Or alternatively, we can use the static method for registering items,
        // which returns an instance of the `menuItem` instead of `ModMenu`
        var buttonInstance = ModMenu.RegisterItem(new SetMoneyAction(), "Stats");
    }
}

// We give the button's name and other optional metadata through the constructor
class InfiniteJumpToggle() : MMButtonToggle("Infinite Jump")
{
    protected override void OnEnable() => IL.PlayerController.TryJump += PlayerController_TryJump;
    protected override void OnDisable() => IL.PlayerController.TryJump -= PlayerController_TryJump;

    private static void PlayerController_TryJump(ILContext il)
    {
        // logic here
    }
}

// This is an example of an action button - it isn't a toggle
class SetMoneyAction() : MMButtonAction("Set Money")
{
    protected override void OnClick()
    {
        // logic here
    }
}

TODO

Priority: First to last.

• Macro/preset system (ability to invoke/toggle buttons on certain events)
• Ability to toggle the UI on/off
• Permission system management (e.g. host-only buttons)
• Thunderstore release (must have permission system)
• More menu item types (e.g. number input)

ModMenuAPI Architecture

ModMenuAPI is designed to be modular and lightweight. This is because the goal of this project is to be a generic mod menu API for any game.