Harmony

Why Harmony?

Harmony is a popular and tested choice for modding, with features for organizing and ordering patches.

It allows you to quickly compile and reload code in a live ACE server. Instead of making changes to ACE, rebuilding the entire server, restarting, and reconnecting you can build your mod and load it with the mod [f]ind command.

Your code will be kept separate from ACE. This makes it easy to keep up-to-date with the main branch of ACE, share code, and understand exactly what a mod is changing.

Since it compiles patches (into IL) it should be roughly as fast as if code changes had been made in ACE directly.

It's also a handy tool to learn. I use DotNetCorePlugins directly in ACE, but you can use bootstrappers/injectors to load Harmony patches into almost any other C# project.

How Does Harmony Work?

It uses the information you supply to find the method it wants to patch, then replaces that with its own method that:

• Runs the Prefixes
  • Skips the rest of the method if requested
• Runs the original method (including transpiled code)
• Runs Postfixes
• All patch options have the ability to change the inputs and returned value of the patches method.

!

What Does Harmony Struggle With?

• Extending enums. I'm not aware of a good way to do something like add an additional PropertyInt property.
• Large methods. Harmony is best at adding stuff before or after a method. You can replace the functionality of a method and skip it or use a transpiler, but that isn't ideal.
• Generic methods or generic classes are supposed to be tricky.
• Harmony requires a static patch method to target
• You'll need a publicizer (preferred) or reflection (like this) to to get access to private members in ACE.
  • Where possible nameof(Type.Member) is used so you can find where something becomes incompatible with ACE, but inaccessible members are targeted with a string which won't give a compile-time error if ACE changes the names of things.