Skip to content

Commit

Permalink
add Code Matcher exemple to the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
warquys committed Oct 16, 2024
1 parent efb41b4 commit 00151fd
Show file tree
Hide file tree
Showing 3 changed files with 190 additions and 0 deletions.
33 changes: 33 additions & 0 deletions Harmony/Documentation/articles/patching-transpiler-matcher.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Patching

## CodeMatcher

One of the most useful tool for transpiler is the [CodeMatcher](../api/HarmonyLib.CodeMatcher.yml).

`CodeMatcher` is like a cursor that can move through the IL code. Using matching methods, you can find specific set of instructions and then insert, remove or replace instructions. To find matching IL you need to use [CodeMatch](../api/HarmonyLib.CodeMatch.yml) and [Code](../api/HarmonyLib.Code.yml)

### Use case

Here is an example of use, we are in the context of an API providing events to mods. In the game, there is a base class `DamageHandler` which manages damage and death animation. A virtual method `DamageHandler.Apply()` provides basic damage handling. This method calls another method `DamageHandler.Kill()` which is called when the character dies. We want to replace the `Kill()` call with an API method which will invoke an `OnDeath` event. It is not possible to directly patch `Kill()` because this method is used in other API methods and we do not want to trigger the event.

In our case, let's find the call to `Kill()` and replace it with our method `MyDeathHandler()`. `CodeMatcher.ThrowIfInvalid()` will throw an exception if the code does not match. There is also `ReportFailure` which returns a boolink. Using these methods can help maintain code between updates. Indicating where and which patches should have revisions.

[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=replacement)]

Using `ThrowIfInvalid` is for an example purposes. There is `ThrowIfNotMatchForward` which summarizes the successive calls of `MatchStartForward` and `ThrowIfInvalid`.

```cs
codeMatcher.ThrowIfNotMatchForward("Could not find call to DamageHandler.Kill",
CodeMatch.Calls(() => default(DamageHandler).Kill(default(Player)))
);
```

Furthermore, in this context, it is very likely that not all patcher methods call `Kill()`. It is possible to check the match validation in the following way. When a Match is a failure, the `CodeMatcher` pointer finds it at the end of the list of instructions. With the `Start()` method this will return the cursor to the start.

[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=check_matcher)]

The `Kill()` method might be called more than once. For this it is possible to use `CodeMatcher.Repeat()`, the method will pass the current matcher code to the action. If no Match is successful, it is possible to define an optional action which takes an error message as a parameter, it is called if no match takes place.

[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=repeat)]

![note] `Repeat` will not use a `CodeMatcher.Search...()`, only `Match...()` methods can be repeated. If you consider using another method `Match...()` in the "matchAction", clone your `CodeMatcher` into the match action via `CodeMatcher.Clone()`. This is to not replace the old match used by `Repeat`.
2 changes: 2 additions & 0 deletions Harmony/Documentation/articles/toc.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@

## [Transpiler - CodeInstruction](patching-transpiler-codes.md)

## [Transpiler - CodeMatcher](patching-transpiler-matcher.md)

## [Finalizer](patching-finalizer.md)

## [Injections](patching-injections.md)
Expand Down
155 changes: 155 additions & 0 deletions Harmony/Documentation/examples/patching-transpiler-codematcher.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
namespace patching_transpiler_codematcher
{
using HarmonyLib;
using System.Collections.Generic;
using System.Reflection;
using System.Reflection.Emit;

public class SimpleMatching
{
// <replacement>
[HarmonyPatch]
public static class DamageHandler_Apply_Patch
{
// See "Auxiliary methods"
static IEnumerable<MethodBase> TargetMethods()
{
var result = new List<MethodBase>();
// ... (targeting all DamageHandler.Apply derived)
return result;
}

static void MyDeathHandler(DamageHandler handler, Player player)
{
// ...
}

static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
{
// Without ILGenerator, the CodeMatcher will not be able to create labels
var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);

codeMatcher.MatchStartForward(
CodeMatch.Calls(() => default(DamageHandler).Kill(default(Player)))
)
.ThrowIfInvalid("Could not find call to DamageHandler.Kill")
.RemoveInstruction()
.InsertAndAdvance(
CodeInstruction.Call(() => MyDeathHandler(default, default))
);

return codeMatcher.Instructions();
}
}
// </replacement>

class Player { }

class DamageHandler
{
public void Apply(Player player) { }

public void Kill(Player player) { }
}

}

public class CheckMatcherMatching
{
// <check_matcher>
public static class DamageHandler_Apply_Patch
{
static IEnumerable<MethodBase> TargetMethods()
{
var result = new List<MethodBase>();
// ... (targeting all DamageHandler.Apply derived)
return result;
}

static void MyDeathHandler(DamageHandler handler, Player player)
{
// ...
}

static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
{
var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);
codeMatcher.MatchStartForward(
CodeMatch.Calls(() => default(DamageHandler).Kill(default))
);

if (codeMatcher.IsValid)
{
codeMatcher.RemoveInstruction()
.InsertAndAdvance(
CodeInstruction.Call(() => MyDeathHandler(default, default))
);
}

codeMatcher.Start();
// Other match...

return codeMatcher.Instructions();
}
}
// </check_matcher>

class Player { }

class DamageHandler
{
public void Apply(Player player) { }

public void Kill(Player player) { }
}

}

public class RepeatMatching
{
// <repeat>
public static class DamageHandler_Apply_Patch
{
static IEnumerable<MethodBase> TargetMethods()
{
var result = new List<MethodBase>();
// ... (targeting all DamageHandler.Apply derived)
return result;
}

static void MyDeathHandler(DamageHandler handler, Player player)
{
// ...
}

static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
{
var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);
codeMatcher.MatchStartForward(
CodeMatch.Calls(() => default(DamageHandler).Kill(default))
)
// Only take the last Matching condition.
.Repeat(matchAction: cm =>
{
cm.RemoveInstruction();
cm.InsertAndAdvance(
CodeInstruction.Call(() => MyDeathHandler(default, default))
);
});

return codeMatcher.Instructions();
}
}
// </repeat>

class Player { }

class DamageHandler
{
public void Apply(Player player) { }

public void Kill(Player player) { }
}

}
}

0 comments on commit 00151fd

Please sign in to comment.