How do I create a basic patch with Harmony for a game mod?

Start by referencing the Lib.Harmony NuGet package, define a patch class with attributes like [HarmonyPatch], and use prefixes or postfixes to inject code; detailed examples are in the official documentation.

What's the difference between Harmony and using Reflection.Emit for runtime code changes?

Harmony provides a higher-level, non-destructive API focused on co-existent patches and IL processing, while Reflection.Emit is lower-level and more manual, requiring developers to manage replacement logic and potential conflicts directly.

Can Harmony patches be applied to private or internal methods?

Yes, Harmony can patch private and internal methods using reflection and IL adjustments, but this may require careful handling of access modifiers and could be less stable in updated assemblies.

How do I debug a Harmony patch that isn't working as expected?

Use logging within patch methods, check for exceptions in the host application, and consult the Harmony documentation or Discord community for troubleshooting common issues like method signature mismatches.

Is Harmony suitable for use in production outside of game modding?

While proven in modding and unit testing (e.g., at Microsoft), production use requires caution due to runtime overhead and potential compatibility issues with framework updates or security tools.

What are best practices for managing multiple patches in a large project?

Organize patches into separate classes or assemblies, use Harmony's co-existent patch system to avoid conflicts, and leverage dependency injection or configuration files for modular control.

Open-Awesome

Lib.Harmony

MITC#v2.4.2.0

A library for patching, replacing, and decorating .NET and Mono methods during runtime, enabling non-destructive code modifications.

Visit Website GitHub

6.5k stars566 forks0 contributors

What is Lib.Harmony?

Harmony is a .NET library that enables runtime patching, replacement, and decoration of methods in C# applications. It allows developers to modify the behavior of existing code without altering the original source, making it particularly useful for game modding, plugin development, and unit testing scenarios where direct code changes are impractical.

Target Audience

C# developers creating mods or plugins for games, extending third-party applications, or needing runtime code modifications for testing and debugging purposes.

Value Proposition

Developers choose Harmony for its non-destructive patching approach, support for multiple coexisting patches, and seamless runtime operation without file modifications, offering a robust alternative to traditional method replacement techniques.

Overview

A library for patching, replacing and decorating .NET and Mono methods during runtime

Use Cases

Best For

Creating mods for popular games like RimWorld, Stardew Valley, or Subnautica
Developing plugins that extend functionality in closed-source .NET applications
Unit testing WPF controls or other UI components at Microsoft or Google
Implementing runtime code instrumentation for debugging or profiling
Adding features to Mono-based applications without recompilation
Building non-invasive patches for legacy or third-party .NET assemblies

Not Ideal For

Projects with full source code access where direct compile-time modifications are feasible and preferred
Real-time applications where runtime patching overhead could negatively impact performance
Environments with strict code integrity checks or anti-tampering mechanisms that may block dynamic modifications

Pros & Cons

Pros

Non-Destructive Patching

Keeps original methods intact while allowing custom code to run before, after, or around them, enabling safe modifications without altering source files as described in the philosophy.

Runtime Flexibility

Operates entirely at runtime without file changes or recompilation, making it ideal for plugins and mods in live applications, highlighted in the installation and how-it-works sections.

Co-Existent Patch Support

Allows multiple patches to be applied simultaneously without conflicts, ensuring stability in mod-heavy environments like the listed games.

Broad .NET Compatibility

Supports .NET and Mono environments, including popular game engines and applications such as RimWorld and Stardew Valley, as evidenced in the README's usage examples.

Cons

Version Incompatibility

Harmony 1 and 2 are not compatible, forcing migrations with potential breaking changes, as noted in the documentation about deprecated versions.

Complex Dependency Management

The thin package requires manual handling of dependencies, adding setup complexity compared to the merged assembly, as mentioned in the installation instructions.

Steep IL Code Learning Curve

Low-level modifications via IL code processors demand deep understanding of .NET internals, which can be a barrier for developers unfamiliar with assembly-level tweaks.

Frequently Asked Questions

Related Projects

Roslyn

The Roslyn .NET compiler provides C# and Visual Basic languages with rich code analysis APIs.

Stars20,466

Forks4,267

Last commit2 days ago

The P programming language.

Stars3,623

Forks219

Last commit4 days ago

Fable

F# to JavaScript, TypeScript, Python, Rust, Erlang and Dart Compiler

Implementation of Python 3.x for .NET Framework that is built on top of the Dynamic Language Runtime.

Stars2,748

Forks311