Harmony Project: Enhancing Flexibility in .NET and Mono
About Harmony
Harmony is a powerful library designed for developers who work with applications built in C#. It provides a sophisticated and high-level mechanism to modify, patch, replace, and decorate methods during runtime in both .NET and Mono environments. Harmony is particularly popular in the gaming world and has been utilized in various acclaimed titles such as:
- Rust
- Rimworld
- 7 Days To Die
- Stardew Valley
- Subnautica
- Oxygen Not Included
- Besiege
- Cities: Skylines
- Kerbal Space Program
- Resonite
- BattleTech
- Slime Rancher
Additionally, it finds applications in technical environments beyond gaming, including use cases within Microsoft and Google for unit testing WPF controls.
How It Works
Harmony stands out by providing developers with the ability to modify application functionalities dynamically. If you've developed a module or plugin in C#, Harmony allows assistance in modifying the functionality of the host application's assemblies while maintaining the integrity of the original methods. It offers the following capabilities:
- Preserve Original Methods: Ensures the original methods remain unchanged.
- Execution Flexibility: Enables execution of custom code before and/or after the original methods.
- Modify with IL Processors: Offers options to change original implementations using intermediate language code processors.
- Non-Conflicting Patches: Allows multiple Harmony patches to coexist without conflicts.
- Runtime Operation: Functions completely during runtime without altering any file content.
Installation
To integrate Harmony into your project, you have a couple of options depending on your needs:
-
Lib.Harmony NuGet Package: This is the preferred method and involves using a single file, dependency-merged assembly. It simplifies setup and minimizes dependency management.
-
Lib.Harmony.Thin NuGet Package: Opt for this if you desire more control by managing dependencies yourself. However, this method requires ensuring all references are available during runtime.
Documentation and Community
Harmony offers a well-documented site, providing detailed guidance to users. Moreover, there's an active community on the official Discord server where users can exchange ideas and seek support.
Contributing to Harmony
The development and support of Harmony represent thousands of hours of dedicated effort. Community involvement is highly encouraged:
- Consider becoming a GitHub sponsor or supporting on Patreon.
- Help spread knowledge by promoting informative discussions in developer forums.
- Utilize community platforms like StackOverflow to facilitate peer help and troubleshooting.
Harmony 1
Note that Harmony 1 is deprecated, with its latest stable version being 1.2.0.1. For environments exclusively using Harmony 1, transitioning to newer versions should be considered with caution, as Harmony 1.x and Harmony 2.x are not compatible and should not be mixed.
Whether enhancing gameplay or testing functional applications, Harmony continues to be an invaluable tool for dynamic code alterations, offering developers flexibility and cohesive integration into existing .NET and Mono projects.