Plugin Tutorial: First Console UI

Now that we've set up the basic structure, let's create a plugin that interacts with Melon in a meaningful way. We'll make our plugin add an option to Melon's main menu.

Step-by-Step Guide

1. Add a Menu Option to Melon's UI

We'll use Host.DisplayManager.MenuOptions to add a new option.

a. Update the LoadUI Method

    public int LoadUI()
    {
        // Add a new menu option
        Host.DisplayManager.MenuOptions.Add("My Plugin Option", MyPluginMenu);
        return 0;
    }
        

b. Implement the Menu Method

    private void MyPluginMenu()
    {
        Console.WriteLine("Welcome to My First Plugin!");
        Console.WriteLine("Press any key to return to the main menu...");
        Console.ReadKey();
    }
        

c. Understanding the Code

• Host.DisplayManager.MenuOptions:
  • This is an ordered dictionary representing Melon's main menu options.
  • By adding a key-value pair, we're adding a new option and specifying the method to call when selected.
• "My Plugin Option":
  • The text that will appear in Melon's main menu.
• MyPluginMenu:
  • The method that gets called when the user selects "My Plugin Option".

2. Rebuild and Test

a. Rebuild Your Plugin

• Build the solution to compile the updated DLL.

b. Update the DLL in Melon

• Copy the new MyFirstMelonPlugin.dll into Melon's Plugins directory, replacing the old one.

c. Restart Melon

• Close and reopen Melon to load the updated plugin.

d. Verify the Menu Option

• Navigate through Melon's UI.
• You should see "My Plugin Option" in the main menu.
• Selecting it should display "Welcome to My First Plugin!" and wait for a key press.

3. Enhance the Menu Interaction

Let's make our plugin's menu more interactive.

a. Update the MyPluginMenu Method

    private void MyPluginMenu()
    {
        while (true)
        {
            Host.MelonUI.BreadCrumbBar(new List<string> { "Melon", "My First Plugin" });
            var choice = Host.MelonUI.OptionPicker(new List<string>
            {
                "Back",
                "Greet",
                "Show Date",
                "Perform Calculation"
            });
    
            switch (choice)
            {
                case "Back":
                    return;
                case "Greet":
                    Console.WriteLine("Hello from My First Plugin!");
                    break;
                case "Show Date":
                    Console.WriteLine($"Today's date is {DateTime.Now.ToShortDateString()}");
                    break;
                case "Perform Calculation":
                    PerformCalculation();
                    break;
            }
    
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }
    }
        

b. Add a Method for Calculation

    private void PerformCalculation()
    {
        Console.Write("Enter a number: ");
        if (double.TryParse(Console.ReadLine(), out double number))
        {
            double result = Math.Pow(number, 2);
            Console.WriteLine($"The square of {number} is {result}");
        }
        else
        {
            Console.WriteLine("Invalid number entered.");
        }
    }
        

c. Understanding the Code

• Host.MelonUI.BreadCrumbBar:
  • Displays the current navigation path in the UI.
• Host.MelonUI.OptionPicker:
  • Presents a list of options for the user to select from.
• Switch Statement:
  • Handles the user's selection.
• PerformCalculation Method:
  • Asks the user for a number and calculates its square.

4. Add Help Options

You can add options to the help menu that shows when calling MelonWebApi.exe(dll) --help.

    public Dictionary<string, string> GetHelpOptions()
    {
        return new Dictionary<string, string>()
        {
            { "--disableDemoMenu", "Tells the plugin not to set it's main menu option." }
        };
    }
        

Then make sure to listen for that Launch Arg like this

    public int LoadUI()
    {
        // Add a new menu option
        if (!Host.StateManager.LaunchArgs.ContainsKey("disableDemoMenu"))
        {
            Host.DisplayManager.MenuOptions.Add("My Plugin Option", MyPluginMenu);
            return 0;
        }
    }
        

5. Rebuild and Test Again

• Rebuild your plugin.
• Copy the DLL into Melon's Plugins directory.
• Restart Melon.
• Navigate to "My Plugin Option" and test the new features.

6. Extra Considerations

• Melon uses Pastel to color it's console text, and has settings for the user to customize these colors. They are stored in the settings, and you can use them in your UI like so:

    Console.WriteLine("This is some text.".Pastel(Host.StateManager.MelonSettings.Text));
    Console.WriteLine("Oh no! Something has gone wrong.".Pastel(Host.StateManager.MelonSettings.Error));
        

• You should not write to the console any time outside of being called as a menu option, either on the main menu or settings. This is because Melon's UI will break if written out of order.
• Host.MelonUI.BreadCrumbBar(new List<string>() { "Melon", "Settings" }); clears the screen and sets the top breadcrumb bar. This should always stay accurate to where you are in the menu chain.
• You shouldn't run any background focused functions or WebApi focused functions in the LoadUI function, only in Execute

7. MelonUI Special Functions

Displaying Progress Bars

You might want to show progress during long operations.

    private void LongRunningOperation()
    {
        for (int i = 0; i <= 100; i++)
        {
            Host.MelonUI.DisplayProgressBar(i, 100, '=', '-');
            Thread.Sleep(50); // Simulate work
        }
        Console.WriteLine("\nOperation completed.");
    }
        

Color Picker

Allow users to pick colors.

    private void ColorSelection()
    {
        var currentColor = Color.White;
        var selectedColor = Host.MelonUI.ColorPicker(currentColor);
        Console.WriteLine($"You selected color: {selectedColor}");
    }
        

Hidden Input

Useful for password fields.

    private void SecureInput()
    {
        Console.Write("Enter your password: ");
        var password = Host.MelonUI.HiddenInput();
        Console.WriteLine("\nPassword entered.");
    }
        

Clear Console

Provides a fully working cross platform way to clear the screen

Host.MelonUI.ClearConsole();

Last Tutorial: Getting Started <--- ---> Next Tutorial: Managing Settings