Mods Communicator
Outward Mods Communicator enables seamless communication between mods through shared events and configuration syncing. It also lets users override any changes made by other mods, giving them full control over their settings.Details
Outward Mods Communicator
Outward Mods Communicator enables seamless communication between mods through shared events and configuration syncing. It also lets users override any changes made by other mods, giving them full control over their settings. You can find library published on NuGet as Outward.ModsCommunicator.
Why should I use this?
Benefits of using this library:
Configuration Syncing
This library allows mod pack creators to synchronize configuration files without directly editing them.
Users don’t need to download configuration files from third-party sources.
Configurations can be edited through XML, and the control flow follows this order: User -> Mod -> Cfg Documents
Changing Configuration As User
This library includesPlayerModsOverrides.example.xml file. You will need
to change it's name to PlayerModsOverrides.xml when you can open it to add
or modify XML values.
Adding Configuration Path To Mod
You can add your configuration XML path inside your plugin’s Awake method like this:OutwardModsCommunicator.OMC.xmlFilePath = "FullPathTo/MyModsOverrides.xml";
Editing XML
This library will contain `PlayerModsOverrides.xml` document as an example. Each override is added inside a ConfigOverrides element:<ConfigOverrides>
<Mod GUID="gymmed.outward_game_settings">
<Section Name="Enchanting Modifications">
<Entry Key="EnchantingSuccessChance" Value="5" />
<Entry Key="RequireRecipeToAllowEnchant" Value="false" />
<Entry Key="UseRecipeOnEnchanting" Value="false" />
</Section>
</Mod>
<Mod GUID="gymmed.outward_mods_communicator">
<Section Name="Event Profiler">
<Entry Key="EnableEventsProfiler" Value="true" />
<Entry Key="InstantLogEventsProfileData" Value="true" />
</Section>
</Mod>
</ConfigOverrides>Possible mod override information can be found in `BepInEx/config` directory inside `.cfg` documents
## Settings file was created by plugin Outward Game Settings v0.0.1
## Plugin GUID: gymmed.outward_game_settings
[Enchanting Modifications]
## Allow enchanting only if enchantment is on character?
# Setting type: Boolean
# Default value: true
RequireRecipeToAllowEnchant = false## Remove recipe after using it on enchanting?
# Setting type: Boolean
# Default value: true
UseRecipeOnEnchanting = false## What is success chance(%) of enchanting?
# Setting type: Int32
# Default value: 50
# Acceptable value range: From 0 to 100
EnchantingSuccessChance = 5
## Play additional audio on enchanting failed/success?
# Setting type: Boolean
# Default value: true
PlayAudioOnEnchantingDone = true
Mods Communication
Communication is handled through an Event Bus — a system that allows mods to fire (publish) and listen (subscribe) to shared events.
How to register event?
using OutwardModsCommunicator.EventBus;
...
void Awake()
{
...
// GUID is your plugin ID provided as a string
// "EnchantmentMenu@TryEnchant" is the event name
// ("menu", typeof(EnchantmentMenu)) defines your variable name and its type
EventBus.RegisterEvent(GUID, "EnchantmentMenu@TryEnchant", ("menu", typeof(EnchantmentMenu)));
// you can add multiple variables and
// add as many as you need like this:
//EventBus.RegisterEvent("MyPluginId", "MyClass@MyMethod", ("name", typeof(string)), ("health", typeof(int)));
...
}How to publish event?
Use this in places where you want to allow other mods to extend your functionality:using OutwardModsCommunicator.EventBus;
...
void YourMethod()
{
...
// Add variable types and names
var payload = new EventPayload
{
["EnchantmentMenu"] = menu,
};
// Send event for subscribers to receive data
EventBus.Publish(OutwardGameSettings.GUID, "EnchantmentMenu@TryEnchant", payload);
}How to subscribe to event?
Use this when you want to listen to an event and execute additional code:using OutwardModsCommunicator.EventBus;
...
void Awake()
{
...
// Provide other mod GUID
// Provide event name
// Provide method you want to execute
EventBus.Subscribe("gymmed.outward_game_settings", "EnchantmentMenu@TryEnchant", OnTryEnchant);
}
private static void OnTryEnchant(EventPayload payload)
{
if (payload == null) return;
// try to retrieve passed event data
EnchantmentMenu menu = payload.Get<EnchantmentMenu>("menu", null);
// if event data is null log and stop execution
if (menu == null)
{
Log.LogMessage("Mod gymmed.outward_game_settings event EnchantmentMenu@TryEnchant returned null for EnchantmentMenu");
return;
}
// Lets log success
Log.LogMessage($"{GUID} successfully communicated with gymmed.outward_game_settings mod and passed menu!");
}How to get all registered events?
Use this when you want to log or inspect all registered events:using OutwardModsCommunicator.EventBus;
...
// We use harmony patch to execute code after each plugin is loaded
// and have already registered their events
[HarmonyPatch(typeof(ResourcesPrefabManager), nameof(ResourcesPrefabManager.Load))]
public class ResourcesPrefabManager_Load
{
static void Postfix(ResourcesPrefabManager __instance)
{
// Log all registered events
EventBusDataPresenter.LogRegisteredEvents();
}
}The project also includes extra tools like EventProfiler and EventBusDataPresenter — feel free to explore them to learn more.
Can I find basic example how to use this?
You can view mod creation template here.
You can view outward game settings mod here.
How to set up
To manually set up, do the following
- Create the directory:
Outward\BepInEx\plugins\OutwardModsCommunicator\. - Extract the archive into any directory(recommend empty).
- Move the contents of the plugins\ directory from the archive into the
BepInEx\plugins\OutwardModsCommunicator\directory you created. - It should look like
Outward\BepInEx\plugins\OutwardModsCommunicator\OutwardModsCommunicator.dllLaunch the game, open inventory and view details of item(Equipment or weapon) it should display all available enchantments.