pardeike/Harmony
53.9
Adequate · 12 November 2026
6.4k
lines of production code
JavaScript
with C#, Python
8
measurements over time
What this system is
This system is Harmony, a .NET library designed for runtime method patching and IL transpilation, primarily used for modding games and applications. It enables developers to inject, modify, or replace method logic using annotation-based attributes, dynamic delegates, and a fluent API for matching and rewriting IL instructions. The library provides comprehensive reflection utilities to access private or internal members safely and supports serialization of patch metadata for debugging and persistence.
How it got here
2017 — Harmony 2.4.2 release and test expansion
10 changes.
This period focused on releasing Harmony 2.4.2 with .NET 10 support and a centralized build infrastructure, while significantly expanding the test suite to cover Traverse, Tools, and patching mechanics. New reflection and IL code-matching utilities were introduced to enhance modding capabilities, accompanied by comprehensive unit tests to ensure stability and correctness across the updated framework.
2018–2019 — Harmony v2.0 API and Core Refactoring
6 changes.
This period focused on the major v2.0 release, which restructured the public API with new patching capabilities and refactored the core mechanics to use Mono.Cecil instead of System.Reflection.Emit. The work also involved modularizing the project structure for shared code and expanding test coverage to validate the new internal components and reverse-patching features.
2020–2025 — Harmony 2 documentation and dependency modernization
6 changes.
This period focused on releasing Harmony 2 documentation and modernizing the project's infrastructure through comprehensive automation scripts for releases and testing. Key technical updates included internalizing Mono.Cecil and MonoMod dependencies via type forwarding to simplify consumer usage, and adding JSON serialization support for patch information on .NET 5+ to replace legacy binary serialization. The work also enhanced test reliability with improved isolation contexts and added utilities for verifying patching behavior.
Features
Harmony Tools: New reflection and IL code-matching APIs
The Harmony/Tools area now exposes a comprehensive set of helper classes for runtime reflection and IL transpilation. AccessTools and its Type extension methods (AccessToolsExtensions) provide simplified, safe access to fields, properties, events, and methods across type hierarchies, including robust handling of invalid assemblies via GetTypesFromAssembly. For IL patching, CodeMatch and CodeMatcher offer a fluent, predicate-based API to locate and manipulate CodeInstruction sequences, while the static Code class provides shorthand syntax for common opcodes. These tools enable modders to inspect and rewrite method bodies with greater precision and fewer boilerplate reflection calls.
Harmony/Tools · high confidence
Initial publication of Harmony 2 documentation
The documentation site has been restructured and published at the v2 path, introducing comprehensive guides for Harmony 2 features including annotation-based patching, execution flow, finalizers, and IL transpiling. This update adds new articles covering basics, auxiliary patch methods, edge cases, and injection details, while also documenting environment variables for controlling the FileLog debug output.
Documentation · high confidence
New Harmony Extras utilities for fast reflection and dynamic delegates
Added new helper classes in Harmony/Extras to improve performance and flexibility when using reflection. MethodInvoker provides a FastInvokeHandler for invoking methods via delegates, including a directBoxValueAccess option to control how value types passed by reference are handled. FastAccess offers deprecated but available delegates for fast field/property access and instantiation, with clear guidance to use AccessTools alternatives. DelegateTypeFactory enables dynamic creation of delegate types from MethodInfo. RefResult introduces a delegate type for handling ref return injections.
Harmony/Extras · high confidence
New release, build, and documentation automation scripts
Added a suite of new scripts to streamline the release and documentation process: \release.py\ handles staging, validation, and publishing of NuGet packages (Lib.Harmony, Lib.Harmony.Ref, Lib.Harmony.Thin) with smoke tests and CI gate checks; \generate\_llm\_pack.py\ creates an LLM-readable documentation index from API and article YAML/Markdown files; \build-with-local-monomod.sh\ and \pack.ps1\ provide build and packaging workflows for MonoMod integration and general solution packing; and \test.sh\ offers a quick test runner. These changes introduce new tooling for maintaining release integrity and generating documentation assets.
scripts · high confidence
Architecture
Restructures project into shared code items for modular builds
Harmony now uses a shared project structure (Harmony.projitems and Harmony.shproj) to organize its source code into distinct folders (Extras, ForwardingAttributes, Internal, Public, Serialization, Tools). This change supports the broader solution restructuring into separate packages with shared code, allowing the library to be built and consumed more modularly while maintaining a single root namespace (HarmonyLib).
Harmony · high confidence
Behavioural changes
Adds JSON serialization support for patch info in .NET 5+
Harmony now supports serializing and deserializing patch information using System.Text.Json on .NET 5.0 and later, introducing dedicated JSON converters for Patch and InnerMethod objects. This provides a modern, non-binary serialization path alongside the existing binary formatter, which remains the default for .NET 5-8 unless explicitly disabled, while binary serialization is completely removed for .NET 9.0+ in favor of JSON-only handling.
Harmony/Serialization · high confidence
Enhanced test isolation and assertion handling in HarmonyTests
The test suite now features improved reliability and isolation: TestTools introduces workarounds for NUnit's Assert.Multiple mode to ensure assertion failures are immediately visible and correctly captured, and adds a new RunInIsolationContext method that uses collectible AssemblyLoadContexts on .NET Core to unload test assemblies after each test, preventing resource leaks and state pollution.
HarmonyTests · high confidence
Harmony 2.4.2 release with .NET 10 support and updated build infrastructure
This release updates the library to version 2.4.2 and adds support for .NET 10, extending the target framework list to include net10.0 alongside existing frameworks from .NET 3.5 through .NET 9. The build system has been restructured with new Directory.Build.props and Directory.Build.targets files to centralize configuration, including versioning, package metadata, and conditional compilation for framework-specific files. The MonoMod.Core dependency has been updated to version 1.3.6, and System.Text.Json references have been updated for newer frameworks (e.g., 9.0.19 for .NET 9, 10.0.11 for .NET 10) to address security issues in older versions. The solution now includes separate projects for Lib.Harmony, Lib.Harmony.Thin, and Lib.Harmony.Ref, with a LocalMonoMod submodule pointing to a specific commit of the MonoMod repository. Documentation and CI workflows have been updated, and the README now lists additional supported games including Genshin Impact Miliastra Wonderland.
(repo-wide) · high confidence
Harmony v2.0 public API restructuring and new patching capabilities
The public API has been restructured for Harmony v2.0, introducing new enums like \MethodType\ (supporting \Async\ and \Enumerator\ targets), \ArgumentMode\ for exact argument name binding, and \MethodDispatchType\ for controlling virtual vs. static calls. The \Harmony\ class now supports selective debugging via the \HARMONY\_DEBUG\ environment variable and the \\[HarmonyDebug\]\ attribute. New patching capabilities include \PatchCategory\ and \PatchAllUncategorized\ for organized patch management, \ReversePatch\ support for duplicating foreign methods, and \InnerPrefix\/\InnerPostfix\ for patching methods called within other methods. The \CodeInstruction\ class now includes \CallClosure\ for delegate injection, and \HarmonyException\ provides detailed IL error reporting with instruction offsets.
Harmony/Public · high confidence
Harmony v2.4.1 release
This update introduces Harmony v2.4.1, which includes a comprehensive internal refactoring of the library's core mechanics. The changes replace the previous System.Reflection.Emit (SRE) approach with Mono.Cecil for internal operations, introducing new internal components such as \AccessCache\ for optimized member lookups, \ByteBuffer\ for IL byte parsing, and \MethodCopier\ for method body reading. The update also implements a new \HarmonySharedState\ mechanism using dynamic types to ensure stable shared state across multiple Harmony versions and Unity's Mono runtime, while adding support for inline signatures and fault block rewriting.
Harmony/Internal · high confidence
Internalizes Mono.Cecil and MonoMod dependencies via type forwarding
Harmony now includes a set of new files in the Harmony/ForwardingAttributes directory that use \[assembly: TypeForwardedTo\] attributes to expose types from Mono.Cecil, Mono.Cecil.Cil, Mono.Cecil.Mdb, Mono.Cecil.Pdb, Mono.Cecil.Rocks, Mono.Collections.Generic, Mono.CompilerServices.SymbolWriter, and MonoMod.Utils. This change supports the internalization of these dependencies within merged packages, allowing consumers to reference Harmony without needing to directly manage or resolve these underlying libraries as separate dependencies.
Harmony/ForwardingAttributes · high confidence
Test coverage
Added comprehensive unit tests for Harmony Tools; Added reverse-patching test assets with transpiler and target method support; Added test asset classes for Harmony reflection and patching features; Added test utilities for verifying Harmony patching behavior; Added tests for MethodInvoker, patch serialization, and original method retrieval; Added unit tests for attribute-based reverse patching and reverse transpiling; Comprehensive test suite for patching mechanics; Expanded Traverse test coverage for fields, properties, and methods; Expanded test assets for argument handling, method types, and finalizers; New unit tests for IL instruction handling and dynamic argument patches.
Dependencies
Upgrade test dependencies and enforce Newtonsoft.Json version
The test project (HarmonyTests) has been updated to use NUnit 3.14.0 and version-specific Microsoft.NET.Test.Sdk releases (16.11.0, 17.13.0, and 18.9.0) tailored to different .NET target frameworks. Additionally, Newtonsoft.Json has been explicitly pinned to version 13.0.4 to address a known vulnerability, and the NUnit3TestAdapter has been updated to version 4.3.2 (with a fallback to 4.3.0 for netcoreapp3.0).
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 51 → 54 (+2.9)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.3) — scores are not directly comparable.
Lenses
- Code Health 49 → 49 (-0.6)
- Architecture 92 → 67 (-24.8)
- Maturity 54 → 59 (+5.0)
- Readiness 45 → 51 (+5.7)
- Security 65 → 65 (+0.0)
- Performance 70 → 100 (+30.3)
Resolved (8)
- Coverage not measured — no coverage collector is wired up
- Low XML-doc coverage: Documentation(net35) (Documentation/Documentation.csproj)
- Projects may be oversized for their cohesion
- XML-doc coverage: Lib.Harmony(net35) (Lib.Harmony/Lib.Harmony.csproj)
- XML-doc coverage: Lib.Harmony.Ref (Lib.Harmony.Ref/Lib.Harmony.Ref.csproj)
- XML-doc coverage: Lib.Harmony.Thin(net35) (Lib.Harmony.Thin/Lib.Harmony.Thin.csproj)
- XML-doc coverage: TestLibrary(net35) (TestLibrary/TestLibrary.csproj)
- release.validate_files (cognitive 21) (scripts/release.py)
New (10)
- Documentation: no build, run or usage example (README.md)
- Projects may be oversized for their cohesion (Lib.Harmony.Ref/Lib.Harmony.Ref.csproj)
- Projects may be oversized for their cohesion (Lib.Harmony.Thin/Lib.Harmony.Thin.csproj)
- Projects may be oversized for their cohesion (Lib.Harmony/Lib.Harmony.csproj)
- doc comments repeat the names (Harmony/Extras/DelegateTypeFactory.cs)
- redundant comment (HarmonyTests/Extras/RetrieveOriginalMethod.cs)
- redundant comment (HarmonyTests/Patching/PatchSorting.cs)
- redundant comment (HarmonyTests/TestTools.cs)
- redundant comment (HarmonyTests/TestTools.cs)
- redundant comment (HarmonyTests/Tools/TestFieldRefAccess.cs)
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
pardeike/Harmony was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 12 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit cde43a5673825873523ce6ae62aebc0ac36be3fa — the exact code this score is about.
- Scored under rubric-2026.11.3 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.42+preprod-6bc2a431cb25.