Modding:Harmony

This article is a stub. You can help Caves of Qud Wiki by expanding it.

This article is a stub. You can help Caves of Qud Wiki by expanding it.

For best results, it's recommended to have read the following topics before this one:

• Modding:C Sharp Scripting

Harmony is a library for dynamically patching C# code. In the context of Caves of Qud modding, it's useful for changing the behavior of things that are not explicitly exposed through the game's modding interface. Harmony is included in the base game, and as such doesn't require any external mods to use.

For a primer on using Harmony to patch game methods, see this article.

While Harmony Patches are powerful and are often the easiest and most direct way to modify behaviour, they are more prone to incompatibility with other mods and future updates, and they can be more difficult to debug or troubleshoot if something goes wrong. A Harmony patch should be considered a last resort only if the desired functionality cannot otherwise be achieved by using the existing part and event infrastructure available in the game, or another similar solution.

That said, there do remain some situations in which Harmony patches are required in order to affect certain functionality. In these cases, Postfix patches tend to be the most compatibility friendly, followed by non-blocking Prefix patches. Prefix patches that prevent the main function from running or Transpiler Patches that modify the IL Code of a function are often more likely to conflict with other mods and should be avoided unless they are the only option.

In general, the Caves of Qud development team prefers data driven behavior, and would be likely to entertain adding a better hook for your mod to use than a Harmony patch. Specifically, reach out to @gnarf37 or @armithaig in #modding on the Official Discord Server.

Example: Chaotic-Colored Message Text

Chaotic-colored message text created by the example harmony patch.

Create somefile.cs in your .../Mods/ModName/ directory, with the following code:

using HarmonyLib;

namespace YourMod.HarmonyPatches
{
    [HarmonyPatch(typeof(XRL.Messages.MessageQueue))]
    class YourPatch1
    {
        [HarmonyPrefix]
        [HarmonyPatch("Add")]
        static void Prefix(ref string Message)
        {
            Message = "{{chaotic|" + Message + "}}";
        }
    }
}