Mache

Mache is a modding framework designed for Sons of the Forest. As a utility it provides support for modders, allowing simple creation of new game content and functions to tweak existing elements of the game. Mache provides access to a unified set of tools, menus, and actions that make the process of creating and implementing mods easier and more streamlined.

Usage

Press F1 to open the Mache mod menu

Modding API

Mod Menu

Easily register your own menu with Mache

Integrated Menu

You can implement interactable UI elements directly into the Mache menu for your mod! When registering your mod, Mache provides an OnFinishedCreating event that is executed when your mod's panel is fully initialized and ready to accept additional elements. Using the GameObject passed to this callback as the parent for your own UI elements will incorporate them into the existing scroll view of your mod's panel in the Mache menu. For example:

Mache.RegisterMod(() => new ModDetails
{
    Name = "Example Mod",
    Id = "your.unique.mod.id",
    Version = "1.0.0",
    Description = "Lorem ipsum dolor sit amet...",
    OnFinishedCreating = (parent) =>
    {
        MenuPanel.Builder()
            .AddComponent(new LabelComponent
            {
                Text = "Hello World!",
                FontSize = 24
            })
            .AddComponent(new ButtonComponent
            {
                Text = "Press Me",
                OnClick = (self) => MachePlugin.Instance.Log.LogMessage("Down the rabbit hole...")
            })
            .BuildToTarget(parent);
    }
});

Custom/Standalone Menu

If you provide a value for OnMenuShow when registering your mod Mache will only display the given name, version, and description in its own window. Instead of placing options there it will create an "Open Settings" button that, when clicked, will execute your OnMenuShow callback. This is intended for use when you want to have a totally independent and fully self-managed menu. It is up to you how your mod responds when the user clicks this button.

Mache.RegisterMod(() => new ModDetails
{
	Name = "Example Mod",
	Id = "your.unique.mod.id",
	Version = "1.0.0",
	Description = "Lorem ipsum dolor sit amet...",
	OnMenuShow = () => Log("Player clicked the 'Open Settings' button for your mod")
});

Expanded Item Database

Easily access the IDs and data of all in-game items

ItemData meatData = GameItem.Meat.GetData();
int meatId = GameItem.Meat.GetId();

Network Event Creation

NOTE: All network events must use unique identifiers, and the identifier for a given event must be the same across all clients!

There are two methods for creating and registering a custom network event:

1. Auto serialize/deserialize
2. With custom serialization/deserialization

Auto (De)Serialization

For auto serialization create a class that extends SimpleEvent<T>, for example:

public class ExampleEvent : SimpleEvent<ExampleEvent>
{
    public string Message { get; set; }
    public int MessageCount { get; set; }

    // called when an event of this type has been receieved
    public override void OnReceived()
    {
        for (int i = 0; i < MessageCount; i++)
        {
            MachePlugin.Instance.Log.LogMessage(Message);
        }
    }
}

Then register it with Mache:

EventDispatcher.RegisterEvent<ExampleEvent>();

Pros:

• Much easier
• Less boilerplate

Cons:

• Your event class must only implement fields that can be automatically serialized to JSON (generally value types and collections of value types)
• Only applies to classes that extend SimpleEvent<T>

Custom (De)Serialization

For more complex scenarios it may be necessary to implement custom serialization and deserialization methods for your class, or if you want to create a network event for types you do not control you can define your own method of serializing/deserializng them. In these cases you must define your own serialize, deserialize, and event recieved callback methods, for example:

EventDispatcher.RegisterEvent("Some.Unique.Event.Id", SomeEvent.Serialize, SomeEvent.Deserialize, SomeEventHandler.OnReceived);

Pros:

• Maximum flexibility
• Can register events that serialize any type

Cons:

• This method is much more involved
• Significantly more boilerplate

Raising Network Events

Events can be raised anywhere and sent to all clients. Using the ExampleEvent from above:

EventDispatcher.RaiseEvent(new ExampleEvent
{
    Message = "Hello World!",
    MessageCount = 10
});

v0.2.0

• Updated with forked version of UniverseLib to fix issues coming from UniverseLib.Input.CursorUnlocker

v0.1.4

• Network events raised outside of a multiplayer game will now work as long as they target the sender

v0.1.3

• Simplified the registration/raising of SimpleEvents further

v0.1.2

• The following Mache overlay properties are now saved and restored on restart:
  • Overlay panel position
  • Overlay panel size
  • Last mod menu displayed

v0.1.1

• esc key now closes Mache menu
• Fixed issue with UniverseLib config preventing use of chat in multiplayer
• Added methods for enabling/disabling the Mache menu and switching to specific mod details

v0.1.0

• Improved dropdown component with configurable height
• Bumped to minor version 1 so patch numbers will be more significant

v0.0.7

• Added config option for changing the Mache Mod Menu toggle keybind

v0.0.6

• Added functionality for mods to put UI elements directly into their Mache mod screen
• Added helpful extensions for saving Vector2, Vector3, Vector4, and Rect values to BepInEx config
• Added the MenuPanel::Builder to facilitate easier creation of simple UniverseLib based UI

v0.0.5

• Added utilities for registering/raising custom networked events
• Opening the Mache menu in-game will now also open the pause menu

v0.0.1

• Initial release