Multitool

Multitool

Swiss army knife of APIs for Atlyss mod development.

This is an utility library / plugin that can be used by mods for common tasks and patterns encountered in mods, such as custom save data.

This library comes with an XML plugin documenting the public API surface. You can use this together with your IDE to explore its functionality.

Keep in mind that if you're a regular user, there is no reason to install this plugin by itself. It needs to be installed alongside the mods that use it.

Table of contents

• SaveUtils
• HierarchyTraverse

SaveUtils

At the moment, this module allows you to save and load custom data as part of character profile saves.

All of the related functionality can be accessed using the Marioalexsan.Multitool.SaveUtils.SaveUtilsAPI class, and other objects found in the Marioalexsan.Multitool.SaveUtils namespace.

Custom Profile Data

To enable saving modded profile data, you must first register your custom data using an unique identifier. Usually, you can use your mod's GUID for this. For example:

SaveUtilsAPI.RegisterProfileData(ModInfo.GUID, SaveProfileData, LoadProfileData, DeleteProfileData);

Once you've setup custom data, you must keep the same GUID at all times, since it is used for loading and deserializing mod data from disk.

The registration requires you to supply five parameters, as follows:

• The type of the custom data to be serialized and deserialized, as the generic type of the method, T
• The GUID to use for this custom data
• A callback for saving profile data, with the signature void SaveProfileData(CharacterFile file, int slotIndex, out T? data)
• A callback for loading profile data, with the signature void LoadProfileData(CharacterFile file, int slotIndex, T? data)
• A callback for deleting profile data, with the signature void DeleteProfileData(CharacterFile file, int slotIndex)

Custom data

The custom data to be serialized and deserialized is provided as a generic parameter for SaveUtilsAPI.RegisterProfileData.

You can customize serialization using Newtonsoft.Json attributes, such as JsonProperty.

GUID

The GUID you specify for your custom data should be unique from any other custom mod data's GUID.

Usually, you can use your BepInEx plugin's GUID for this field.

Once you start using a GUID, you need to keep it unchanged between mod updates, since this is used by Multitool to identify and load your custom data.

Save profile callback

The save callback, void SaveProfileData(CharacterFile file, int slotIndex, out T? data), is called whenever the game is currently saving a character profile.

To save your custom data, set the T? data parameter to the custom data that you want to be serialized and saved on disk for the given save slot.

You can specify null as the data to be serialized, which will erase the saved custom data from the disk.

Keep in mind that this callback will be called both for existing characters, and whenever a new character is created. This means that you need to handle the case where you might not have any existing data available for that character yet.

Sample API usage:

Dictionary CustomSaveData =;

void SaveProfileData(CharacterFile file, int index, out MyModData? saveData)

{

if (!CustomSaveData.TryGetValue(index, out saveData))

{

saveData = new()

{

RichTextName = file._nickName

};

}

}

Load profile callback

The load callback, void LoadProfileData(CharacterFile file, int slotIndex, T? data), is called whenever the game is currently loading a character profile.

If there is custom data available for this profile, T? data will contain a deserialized object with that data. Otherwise, it will be null.

The data can be null whenever a vanilla character is loaded, or the Multitool save file didn't contain any existing data for your mod. This means that you need to handle the case where you might not have any existing data available for that character yet.

Keep in mind that Atlyss has some quirks when it comes to loading profile saves. Your