Hamunii.ModMenuAPI 0.3.0-dev

This is a prerelease version of Hamunii.ModMenuAPI.
dotnet add package Hamunii.ModMenuAPI --version 0.3.0-dev                
NuGet\Install-Package Hamunii.ModMenuAPI -Version 0.3.0-dev                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Hamunii.ModMenuAPI" Version="0.3.0-dev" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Hamunii.ModMenuAPI --version 0.3.0-dev                
#r "nuget: Hamunii.ModMenuAPI, 0.3.0-dev"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Hamunii.ModMenuAPI as a Cake Addin
#addin nuget:?package=Hamunii.ModMenuAPI&version=0.3.0-dev&prerelease

// Install Hamunii.ModMenuAPI as a Cake Tool
#tool nuget:?package=Hamunii.ModMenuAPI&version=0.3.0-dev&prerelease                

ModMenuAPI

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

GitHub Build Status Thunderstore Version NuGet Version

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.

Engine Supported?
Unity Mono
Unity IL2CPP
Other
Modloader Supported?
BepInEx 5
Other
Mods using this API

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

Game Mod Readme
Lethal Company ModMenuAPI.Plugin.LC link
Content Warning ModMenuAPI.Plugin.CW link

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.

Namespace Purpose
ModMenuAPI The entry point of the software; handles loading and unloading itself so it plays well with hot loading. This is the only modloader-specific part, and adding support for another modloader should be incredibly easy.
ModMenuAPI.ModMenuItems & ModMenuAPI.ModMenuItems.BaseItems Contains the mod menu button components that are used, including the API methods used for registering buttons on the menu.
ModMenuAPI.MenuGUI Contains the graphical menu implementation, which currently is Unity's OnGUI. A new implementation should be easy, as the most significant thing this does (other than the graphics) is invoke button presses using MMItemBase's CommonInvoke().
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.1

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.3.0-dev 56 5/31/2024
0.2.0-dev 54 5/16/2024
0.1.2-dev 56 5/15/2024
0.1.1-dev 46 5/14/2024