View source for Custom Maid 3D2/Modding/Plugins

{{msgbox
|border=#ddd
|background=#ddd
|textcolor=#000
|message='''''This article is out of date and contains information that might be obsolete. You can find a newer guide for ReiPatcher [http://umaiumeunion.github.io/guides_reipatcher/01_preface.html here] and for UnityInjector [http://umaiumeunion.github.io/guides_unityinjector/01_preface.html here].'''''.
}}

{{Custom Maid 3D 2}}

<includeonly>[[Category:Stubs]]</includeonly>
<noinclude>[[Category:Article_management_templates]]</noinclude>
Since Custom Maid 3D 2 was made using Unity Engine and scripted with .NET, it is possible to manipulate game's behaviour using .NET and some tools to inject code into game's own DLLs. 

In this tutorial we will be using [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703144#post3703144 ReiPatcher], a general-purpose .NET assembly patcher by HongFire user [http://www.hongfire.com/forum/member.php/1283907-usagirei usagirei], and [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703145#post3703145 UnityInjector], a simple plug-in injector, made by the same user, to create simple Unity plug-ins.

To simplify code, this tutorial will also use [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3707606#post3707606 ReiPatcherPlus], an extension library for ReiPatcher to provide a handful of convenient methods. If one prefers to manipulate assemblies oneself, the same results may be achieved with Mono.Cecil, which ReiPathcer and ReiPatcherPlus use as well.

'''Note:''' Please note that owing to ever-so-evolving patching tools some parts of the tutorial may be outdated. The developers of said tools try their best to bring more features while trying to preserve the original programming routines. However, changes happen and the editors of this wiki attempt to update the documentation as fast as possible.

== Overview ==
=== About this tutorial ===
In this tutorial we will use ReiPatcher and UnityInjector to create a simple plug-in called ''HelloWorld'' which will print "Hello, world!" on the screen every time a button is pressed in the game. We will also implement the ability to stop printing the message with a press of a key.

=== How ReiPatcher and UnityInjector work ===
While having some minor differences in purpose, both function as important tools to patch and manipulate CM3D2 (or any other .NET programs or Unity games).
==== ReiPatcher ====
ReiPatcher is an all-purpose tool for injecting CIL (Common Intermediate Language) instructions into existing managed assemblies and programs that were made using .NET. While the tool was initially made at the time of CM3D2, it is capable of patching almost any .NET assembly, as long as it is compiled into managed CIL, like C# and VB.NET do. Notice however, that C++/CLI assemblies might be almost impossible to manipulate, which is due to the code being mostly unmanaged (notice that the managed code is still compiled into CIL, albeit with <code>unsafe</code> tag.).
By using ReiPatcher we can for instance hook methods (make them call other methods from outside their original assemblies) or even redirect them (make them use custom logic instead of game's original code). Furthermore, with the help of Mono.Cecil library, it is possible to add, remove and edit any original methods or assemblies without having to explicitly to decompile and recompile assemblies.

As of this writing, ReiPatcher operates as follows. The programmer creates two DLLs: the one that contains custom hook or redirect methods, and the one that is used by ReiPatcher itself to patch the assemblies to call the custom methods. While the former DLL can have a structure of its own, the latter requires to have patcher classes (classes, that extend ReiPatcher.exe's <code>PatchBase</code> class). Every class that extends <code>PatchBase</code> is considered a patch in itself, which means that the patch DLL can contain as many patches as the programmer wants.

For further information on how to use ReiPatcher to hook or redirect methods, refer to the next sections of this tutorial.

===== ReiPatcherPlus =====
ReiPatcher's purpose is to provide an API for easy code injection. However, while ReiPatcher manages patching, assembly manipulation itself must be implemented by the programmer with the help of Mono.Cecil.
Unfortunately, anything beyond injecting simple function calls increases the complexity of the code to the point where it is almost impossible to maintain it. 

Therefore, an extension for ReiPatcher was created to encapsulate the most common routine methods for patching, injecting and altering assembly members.

ReiPatcherPlus allows to inject two types of functions:
* ''Hooks'': Methods which the injected function will call before continuing with its own routine
* ''Redirects'': Methods which the injected function will call. However, the return value of the redirect function determines whether the injected function will continue or return. That means that the redirect function can "redirect" game logic to programmer's own.

In addition to injection, ReiPatcherPlus allows to easily change visibility of class members to public. Furthermore, it is possible to make methods virtual.

This tutorial uses ReiPatcherPlus to shorten the code. Of course, full source code will be provided, where possible.

'''NOTE:''' Since ReiPatcherPlus 2.0, the library has undergone some major changes in structure. Therefore, note that some of parts of this page concerning ReiPatcherPlus might be outdated.

==== UnityInjector ====
Sometimes one does not need to hook or redirect in-game methods, but instead just needs to manipulate in-game objects, like textures, buttons, models, cameras or input, every tick (game update, usualy called every 1/60th of a second). In that case, patching game's assemblies is not required; instead, UnityInjector can be used.

UnityInjector is a plug-in manager, that hooks into a Unity Engine game and creates a game object of itself that is capable of being updated and accessing other game objects. In other words, UnityInjector uses ReiPatcher to be inserted into the game and allow programmers to create simple plug-ins without the need of patching any assemblies over and over again.
UnityInjector can be used to process user input, create new UI and change properties of objects that are loaded into the game.

== Tools ==
=== Required ===
* Custom Maid 3D 2 (or just the DLLs found in <code>CM3D2(x84/x64)_Data\Managed</code> folder at the very least.
* [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703144#post3703144 ReiPatcher] and [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703145#post3703145 UnityInjector].
* .NET Framework 3.5 or later.
* IDE to program with a .NET-compatible language. Some of the more popular ones are [https://www.visualstudio.com/ Visual Studio] (VS2015 Community is free), [http://www.monodevelop.com/ MonoDevelop] and [http://www.icsharpcode.net/OpenSource/SD/ SharpDevelop]. This tutorial was initially written for Visual Studio.
* [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703144#post3703144 ReiPatcher] and [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703145#post3703145 UnityInjector]. Mono.Cecil is included in ReiPatcher and thus is not required to be downloaded by itself.
* Basic knowledge of at least one programming language that supports .NET Framework. This tutorial is written in C#, but the plug-ins may be written in VB.NET and other .NET-compliant languages alike.

=== Additional ===
* Basic knowledge of CIL (Common Intermediate Language). That is needed when writing own custom patches with Mono.Cecil.
* [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3707606#post3707606 ReiPatcherPlus], which provides methods to hook and redirect methods, load assemblies, etc.
* [https://www.jetbrains.com/resharper/ ReSharper] which is a productivity tool for Visual Studio. The tool provides for a more efficient and faster development.
* .NET decompiler to view game's original code, which will be needed to create own plug-ins. Such tools are, for instance, [http://www.ilspy.com/ ILSpy], [http://code.google.com/p/cecilstudio Cecil Studio], [https://www.jetbrains.com/decompiler/ dotPeek] (included in ReSharper by default, but this is the standalone version) and [http://www.red-gate.com/products/dotnet-development/reflector/ .NET Reflector] (paid, but includes patch testing tools like ILSpy). In this tutorial we will be using ILSpy.

== Inspecting original code with a decompiler ==
Before we can start programming, we need to gather information about how to implement our plug-in. For that, we will use ILSpy (alternatively, you can use any other .NET code viewer) to find the classes and methods to hook.
In the case of CM3D2, most important code is located in <code><Game's Main Directory>\CM3D2(x86/x64)_Data\Managed\Assembly-CSharp.dll</code>. To view the code with ILSpy, do the following:
# Download and fire up ILSpy.
# Click <code>File->Open</code> (or press <code>Ctrl+O</code>) and navigate to <code><Game's Main Directory>\CM3D2(x86/x64)_Data\Managed</code> (choose either x86 or x64 folder).
# Choose <code>Assembly-CSharp.dll</code> and hit "Open". That will add the library to the list of loaded ones.
# Click on the "+" button left to the loaded assembly to expand the view and see namespaces contained in the assembly.

From here it is the programmer's task to find the class and method to hook or redirect. Sometimes it is not even necessary to hook anything at all, for manipulating in-game property with UnityInjector may do the trick. However, for the purpose of this tutorial we shall use ReiPatcher to hook methods nonetheless.

While trying to find the needed classes or methods, one can use the following tools in ILSpy to simplify searching:
* Clicking on the "+" left to any item will expand it to show the sub-items. Namespaces expand into types (classes, structs, etc) and those expand into members (variables, methods, properties). Clicking on the type or its member will show its definition in C#, VB.NET or pure CIL depending on chosen settings.
* Right-clicking any item and choosing "Analyze" will bring up the "Analyzer" window which will contain such information as where the item is used, where it is defined or where it is exposed to other types. That will significantly speed up the process of finding methods to hook, redirect or use.
* Read the names and definitions, for most of the time they reveal the purpose of the type or the method.

For the purpose of this tutorial, we can find that the class <code>UIButton</code> in the general namespace (notated as <code>{}</code> by ILSpy) has a method called <code>OnClick()</code>. After looking at the definition and analysing the method we can be rather certain that this is the method we are looking for.
Therefore, by hooking the method (not redirecting — we'll discuss the difference later!) we can detect whether a button has been pressed. Now that we know what methods to hook, we can proceed to projects for ReiPatcher and UnityInjector.

== Setting up ==
=== Installing the tools ===
Download and install .NET Framework, an IDE of your choice and possibly a decompiler. Follow installation instructions provided with the programs.
Thereafter, download and install ReiPatcher and UnityInjector according to the instructions found on their respective download pages. Verify that the patcher was installed successfully by patching UnityInjector and launching the game. '''Remember to follow all README files provided with the mods.'''

=== Gathering required libraries ===
In addition to DLLs provided with ReiPatcher, we will need some additional assemblies in order to apply own plug-ins.
Below is the list of required DLLs and their locations:
{| class="wikitable" 
|-
! Assembly Name !! Purpose !! Location
|-
| <code>ReiPatcher.exe</code> || Contains main patcher class || ReiPatcher's install directory
|-
| <code>ExIni.dll</code> || Contains classes and methods for manipulating .ini files. || ReiPatcher's install directory
|-
| <code>Mono.Cecil.dll</code> || Contains tools for manipulating CIL assemblies (reading classes, methods, etc) || ReiPatcher's install directory
|-
| <code>Mono.Cecil.*.dll</code> || Miscellaneous classes and tools to extend Mono.Cecil's functionality. || ReiPatcher's install directory
|-
| <code>ReiPatcherPlus.dll</code> (optional) || Extends the functionality of some classes found in <code>ReiPatcher.exe</code> || ReiPatcher's install directory
|-
| <code>Assembly-CSharp.dll</code> || Contains game's logic and scripts || <code><Game's Main Directory>\CM3D2(x86/x64)_Data\Managed</code> (Either x86 or x64 will suffice)
|-
| <code>UnityEngine.dll</code> || Contains Unity Engine's wrapper classes for .NET || <code><nowiki><Game's Main Directory>\CM3D2x86_Data\Managed</nowiki></code>
|-
| <code>UnityInjector.dll</code> || Contains classes for writing and loading plug-ins || <code><nowiki><Game's Main Directory>\CM3D2x86_Data\Managed</nowiki></code>
|-
| Miscellaneous Assemblies || Additional libraries to inject into or to use || Most likely <code><Game's Main Directory>\CM3D2(x86/x64)_Data\Managed</code>
|}

Copy the above-mentioned assemblies into a single folder. It will be used later in the tutorial.</br>
'''Note:''' You can copy <code>Assembly-CSharp.dll</code> as well, but remember that if you intend on using UnityInjector along with ReiPatcher, consider referencing the assembly directly from game directory instead. That way, after ReiPatcher had applied the patches, the IDE will automatically pick up updated method and visibility definitions.

=== Creating the projects ===
Create an empty project in the IDE of your choice. We are going to call it <code>CM3D2.HelloWorld.Hook</code>. When creating the project, we'll set solution name to <code>CM3D2.HelloWorld</code>. Thereafter, we'll create two other empty projects: <code>CM3D2.HelloWorld.Patcher</code> and <code>CM3D2.HelloWorld.Plugin</code>.
Having done that, set solution's active configuration to "Release" and platform to "Any CPU". Finally, set .NET Framework version to 3.5 if you haven't done so when creating the solution. 

If you are unsure of how to perform such a task, refer to the IDE's own help pages. In Visual Studio 2013, the aforementioned can be done as follows:
# Open Visual Studio. Click <code>File->New->Project</code> (or press <code>Ctrl+Shift+N</code>).
# From templates, choose <code>Visual C#->Class Library</code> (or <code>Visual C#->Windows Desktop->Empty Project</code>).
# Above the list of project templates change .NET Framework version to 3.5 if it isn't already.
# Give a name to your project in the <code>Name</code> field. In the case of this tutorial it shall be <code>CM3D2.HelloWorld.Hook</code>.
# Give a name to your solution name in the <code>Solution name</code> field. In our case it is <code>CM3D2.HelloWorld</code>.
# Change location of the solution if needed.
# Make sure <code>Create directory for solution</code> is checked. Click "OK" and wait for solution to load up.
# In Solution Explorer, right click on solution's name and go <code>Properties->Configuration Properties->Configuration->Configuration Manager</code>.
# Change "Active solution configuration" to "Release". Under "Active solution platform", make sure it is "Any CPU" and click "OK". Close Configuration Manager and click OK in solution's configuration.
# Right click on each project and go to <code>Properties</code> and change <code>Output type</code> to "Class Library". Save the project by pressing <code>Ctrl+S</code>. Close the tabs.

When creating other projects, refer to the next subsection about naming and their meaning.

==== DLL types and naming conventions ====
As of this writing, ReiPatcher and UnityInjector require at most three different DLLs to be created in order to apply plug-ins. Those libraries' function can be described as follows:
* ''Hook'' — Used by ReiPatcher. Contains methods (hooks) which will be called by the game before running its own logic. Ready DLLs are placed to <code><Game's Main Directory>\CM3D2(x86/x64)_Data\Managed</code>.
* ''Patcher'' — Used by ReiPatcher. Contains procedures that will add hook methods into game's original methods (also called hooking in programming argot). Ready DLLs are placed to <code><Game's Main Directory>\Patches</code>
* ''Plugin'' — User by UnityInjector. Contains Unity script that is loaded up by UnityInjector. Ready DLLs are placed to <code><Game's Main Directory>\UnityInjector</code>
Note, that if one does not need to alter the execution of any in-game methods, only ''Plugin'' DLL is needed.

Each library needs a project of its own to be created. Unfortunately, as of this moment, no naming conventions exist. Therefore, it is up to the programmer to decide how to name them. Nonetheless, most of the plug-in creators seem to name their DLLs as follows: 
 <code>CM3D2.''PluginName''.''Type''.dll</code>

In this case ''PluginName'' is self-explanatory. ''Type'', on the other hand, refers to one of the three types of DLL.
'''Note:''' Some people seem to prefer to replace the ''Hook'' word with ''Core'', while others leave the type out altogether.

=== Importing the DLLs ===
Remember the DLLs we gathered into a single folder? Move it in the same folder as the solution. After that return to your IDE and add those libraries to projects' references.
In Visual Studio it can be done as follows:
# In Solution Explorer, click on the small arrow left to the project name to expand it.
# Right click on <code>References</code> and click <code>Add Reference...</code>.
# In the newly-opened window go to <code>Browse</code> tab and click <code>Browse...</code> button.
# Choose the assemblies to import (multiple can be chosen at the same time). And click "OK".

Below is the table of basic set of assemblies to reference for each type of DLL:

{| class="wikitable"
|-
! Project type !! Assemblies to reference
|-
| Hook || Assembly-CSharp.dll, UnityEngine.dll
|-
| Patcher || Assembly-CSharp.dll, UnityEngine.dll, Mono.Cecil.dll, ReiPatcher.exe, ReiPatcherPlus.dll (if you want convenience methods)
|-
| Plugin || Assembly-CSharp.dll, UnityEngine.dll, UnityInjector.dll, ExIni.dll, Hook DLL (if using ReiPatcher to hook methods. Can be added by referencing the Hook project)
|}

Of course, if any other assemblies are to be used, they must be referenced as well.

== Writing the hook DLL ==
Firstly, we shall write the hook method. The hook DLL acts more often than not as a bridge between the game's own internal API and our plug-in code.

If there are not any classes (.cs files) in your hook project, create a new source code file. We shall name it <code>HelloWorldHooks</code>.

In it we shall create a basic class which is also named <code>HelloWorldHooks</code>. The structure should be the following:
<code>
 namespace CM3D2.HelloWorld.Hook
 {
     public static class HelloWorldHooks
     {
     }
 }
</code>
Notice how the the class is notated as <code>static</code>. It is not compulsory, but is a good practice, as we do not intend to create an instance of <code>HelloWorldHooks</code>.

Let us define the hook method. As we have seen the definition of <code>UIButton.OnClick()</code>, we know that the button has a property <code>UIButton.isEnabled</code>. We will want to access that property so that we will not print anything when the button is disabled.
To access the property, we will need to have the reference of the pressed button at our disposal. Therefore, we will create a hook method with a single parameter: reference to the <code>UIButton</code> object. The prototype of the method will then look something like this:

<code>
 public static void OnClickHook(UIButton button)
 {
     // Called when the game calls UIButton.OnClick(). 
     // The parameter contains the reference to UIButton in which UIButton.OnClick() was called.
 }
</code>

Next, we shall use .NET event handlers to create a custom event to which we can then add functions to call when <code>OnClickHook()</code> is called.
Contrary to .NET Framework guidelines, we shall do it by declaring a custom delegate (event handler prototype) and an event above of <code>OnClickHook()</code> definition:

<code>
 public delegate void ButtonClickHandler(UIButton button); // Function prototype for event handlers
 public static event ButtonClickHandler ButtonClicked;     // Event itself
 
 public static void OnClickHook(UIButton button)
 {
     // ...
 }
</code>
It must be noted, however, that while this way is shorter, it is against .NET guidelines and is compact only when there are just a few events to handle. Refer to [https://msdn.microsoft.com/en-us/library/aa645739(v=vs.71).aspx MSDN Events tutorial] if you want to do it the .NET way.

Finally, we can call the event handlers in our defined hook. The final structure of <code>HelloWorldHooks.cs</code> will look like this:
<code>
 namespace CM3D2.HelloWorld.Hook
 {
     public static class HelloWorldHooks
     {
         public delegate void ButtonClickHandler(UIButton button); // Function prototype for event handlers
         public static event ButtonClickHandler ButtonClicked;     // Event itself
 
         public static void OnClickHook(UIButton button)
         {
             // Check if there are even handlers. If true, call them.
             if (ButtonClicked != null) ButtonClicked(button);
         }
     }
 }
</code>
This is the only hook method we will need. Save the class and proceed to writing the patcher.

== Writing the patcher DLL ==
As discussed in the previous sections, ReiPatcher uses an API of its own to provide an easy way for patching assemblies. 
The patcher DLL is used by ReiPatcher to allow the plug-in developer to inject custom calls to the hook methods, change member field access and adding own code.

In our patcher project, we shall create a class <code>HelloWorldPatch</code>. To turn the class into a patcher, inherit <code>PatchBase</code> located in <code>ReiPatcher.Patch</code> namespace.
Since the class is abstract, it requires the following members to be extended/defined:
* <code>string Name</code>: A get property that specifies the name of the patch
* <code>string Version</code>: A get property that specifies the version of the patch.
* <code>bool CanPatch(PatcherArguments args)</code>: A method that determines whether the patch can be applied.
* <code>void Patch(PatcherArguments args)</code>: A method in which one performs the patching.

Here is the basic structure of our patch:
<code>
 using System.Reflection;
 using ReiPatcher.Patch;
 using ReiPatcherPlus; // Extends PatchBase to simplify patching. Not required to make ReiPatcher work.
 
 namespace CM3D2.HelloWorld.Patcher
 {
     public class HelloWorldPatch : PatchBase
     {
         public override string Version
         {
             get
             {
                 // A simple way: just gets the version of CM3D2.HelloWorld.Patcher assembly
                 return Assembly.GetExecutingAssembly().GetName().Version.ToString();
             }
         }
         public override string Name
         {
             get { return "Hello, world! Patch for CM3D2"; }
         }
 
         public override bool CanPatch(PatcherArguments args)
         {
             // Checks to determine whether this patch can be applied
             // Return ture if ReiPatch may proceed to patch with this class
         }
 
         public override void Patch(PatcherArguments args)
         {
             // Patches the assemblies using Mono.Cecil
         }
     }
 }
</code>

In addition, we can override two more methods:
* <code>PrePatch()</code>: Called after the patch has been loaded into memory, but before it is applied. Used to request assemblies that we want to patch. Also used to load our hook DLL.
* <code>PostPatch()</code>: Called after the patch has been applied and the patched assembly saved. Can be used to run some clean-up code.

In our case, overriding only <code>PrePatch()</code> will suffice.
=== Pre-patching phase ===
Before patching we need to ask ReiPatcher to load up the assemblies we want to patch. In our case it is <code>Assembly-CSharp.dll</code>. Moreover, we need to load our own assembly that contains the hook method.

Assembly request is done with <code>RPConfig.RequestAssembly(string name)</code>, where <code>name</code> is path to the assembly to patch. If the exact path is not specified, ReiPatcher will attempt to find the assembly from the path specified in AssembliesDir attribute in patcher's INI file.
Every assembly that one wishes to be patched must be requested. Otherwise it might not be included into the patching cycle.

Having requested the assembly, we need to load our hook assembly.

ReiPatcherPlus provides a convenient method <code>LoadAssembly(string name)</code> where <code>name</code> is the path of the assembly. If exact path is not specified, the method will attempt to find the assembly from the path specified in AssembliesDir attribute in patcher's INI file. 
If the method fails to find or load the assembly, it will throw an exception.<br/>
The functionality of <code>LoadAssembly</code> can be mimicked with Mono.Cecil as follows:
<code>
 public static AssemblyDefinition LoadAssembly(string name)
 {
     string path = Path.Combine(patch.AssembliesDir, name);
     if (!File.Exists(path)) throw new FileNotFoundException("Missing DLL: " + path);
     using (Stream s = File.OpenRead(path))
 	     result = AssemblyDefinition.ReadAssembly(s);
     return result;
 }
</code>

In the end, this is how our <code>PrePatch()</code> method should look like:
<code>
 // Below the class definition
 private AssemblyDefinition hookAssembly;    // Our loaded hook assembly
 // ...
 
 // Below Patch(PatcherArguments args)
 public override void PrePatch()
 {
     //Request assemblies from ReiPatcher
     RPConfig.RequestAssembly("Assembly-CSharp.dll");
  
     // Load our own assemblies (like hooks, etc.)
     hookAssembly = this.LoadAssembly("CM3D2.HelloWorld.Hook.dll");
 }
</code>

=== Pre-patching checks ===
The <code>CanPatch(PatcherArguments args)</code> method override is called just about before applying the patch. If we return <code>true</code>, ReiPatcher will call <code>Patch(PatcherArguments args)</code>.
Note that <code>CanPatch</code> can be called multiple times — one time for each assembly that was requested (either by our own patch or some other one). That is why it is crucial to check that we are about to patch the right assembly. That way <code>Patch(PatcherArguments args)</code> method will be called the right number of times and on the right assemblies.

To assist checking, ReiPatcher provides <code>PatcherArguments</code> parameter, that contains the following properties:
{| class="wikitable"
|-
! Property !! Description
|-
| <code>Assembly</code> || Assembly that ReiPatcher is about to patch. Can be used to check whether we actually want to patch it.
|-
| <code>Location</code> || Full path to the assembly
|-
| <code>FromBackup</code> || True, if the assembly was loaded from a back-up
|- 
| <code>WasPatched</code> || True, if that assembly has been patched at least once during this patch cycle
|}

In addition to checking whether the assembly is right, we also need to check if our patch has already been applied to the specified assembly. That way we can avoid injecting the same code twice.<br/>
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>.<br/>
The method loads all attributes from the given assembly and attempts to find a match. If there is an attribute data of which matches <code>attribute</code>, the method returns <code>true</code>.<br/>
The functionality of the method is implemented as follows:
<code>
 public static bool HasAttribute(AssemblyDefinition assembly, string attribute)
 {
     return patch.GetPatchedAttributes(assembly).Any(a => a.Info == attribute);
 }
</code>

We shall define an arbitrary tag, "CM3D2_HELLO_WORLD", that we will add as an attribute to the assembly after our patch has been successfully applied. Next time ReiPatcher is run, we check whether our tag exists in the assembly. If it does, we know that our patch has already been applied.

That way, our definition of <code>CanPatch</code> becomes:
<code>
 // Below the class definition
 private const string TAG = "CM3D2_HELLO_WORLD";
 
 //...
 
 public override bool CanPatch(PatcherArguments args)
 {
     //Check that we are patching the right assembly and it doesn't have our tag
     return args.Assembly.Name.Name == "Assembly-CSharp" && !this.HasAttribute(args.Assembly, TAG);
 }
</code>

=== Patching phase ===
Having done all the checks, it is time to finally patch the assembly, which is done in <code>Patch(PatcherArguments args)</code> method.<br/>
The contents of the method depend on the situation. However, in almost all cases patching requires using various methods provided by Mono.Cecil to alter the contents of classes and methods.<br/>
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps if we are to use pure Cecil and CIL:
# Get assembly's module, which is the property <code>args.Assembly.MainModule</code>, and use its <code>GetType(string fullName)</code> method to acquire the type definition for <code>UIButton</code>.
# Get hook assembly's module, which is the property <code>hookAssembly.MainModule</code>, and acquire the type definition for <code>CM3D2.HelloWorld.Hook.HelloWorldHooks</code> (notice the use of full name containing the namespace(s) and type name).
# Find the <code>MethodDefinition</code> for <code>OnClick()</code> method using <code>UIButton</code>'s type definition.
# Repeat the same process for <code>OnClickHook(UIButton button)</code> method using acquired type definition.
# Using hook assembly's module and method definition, get <code>MethodReference</code> for <code>HelloWorldHooks.OnClickHook()</code>.
# Using <code>UIButton.OnClick()</code>'s method definition, get its method body and from it an instance of <code>ILProcessor</code>.
# Use the IL processor to insert <code>ldarg.0</code> and <code>call [method reference to OnClickHook()]</code> instructions before the method's original first instruction.
# Add our patch tag to the assembly.

The process requires to write about a dozen of lines to complete the injection. However, method search and injecting can be done easier with ReiPatcherPlus.<br/>

Here are the main steps in using ReiPatcherPlus:

'''1. Acquiring the type definitions'''<br/>
This is done simply with Mono.Cecil's <code>ModuleDefinition.GetType(string name)</code>:

<code>
 TypeDefinition uiButton = args.Assembly.MainModule.GetType("UIButton");
 TypeDefinition hooks = hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks");
</code>

'''2. Getting the target method and the appropriate hook'''<br/>
ReiPatcherPlus provides an extension to Mono.Cecil: <code>TypeDefinition.GetMethod(string name)</code> which searches for the first method with the given name.<br/>
Furthermore, to get a suiting hook method, we can use <code>GetHookMethod(MethodDefinition target, TypeDefinition hookType, string hookName, MethodFeatures features)</code> which finds a suitable hook method that matches both the target method and the given criteria.
Since our hook method has only a parameter of the target type, only using the feature <code>MethodFeatures.PassTargetType</code> will suffice:

<code>
 MethodDefinition onClick = uiButton.GetMethod("OnClick");
 MethodHook hookMethod = this.GetHookMethod(onClick, hooks, "OnClickHook", MethodFeatures.PassTargetType);
</code>

For more detailed discussion on method features and <code>GetHookMethod</code>, refer to the later sections.

'''3. Injecting the code'''<br/>
Having created an instance of <code>MethodHook</code>, we can now simply use ReiPatcherPlus's <code>AttachMethod(MethodHook hook, int codeOffset)</code>. Since the hook method was searched with <code>GetHookMethod</code>, one can be sure that the hook method is in fact injectable into the target method.
Note that <code>int codeOffset</code> specifies the index of the IL code to start the injection from. Since we want to add the hook at the beginning of the <code>OnClick()</code>, we simply pass 0:

<code>
 this.AttachMethod(hookMethod, 0);
</code>

Putting it all together we get a fancy patch method:
<code>
 public override void Patch(PatcherArguments args)
 {
     // Get type definitions for the UIButton and the hook class
     TypeDefinition uiButton = args.Assembly.MainModule.GetType("UIButton");
     TypeDefinition hooks = hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks");
     
     // Get the method definition for OnClick and OnClickHook
     // GetHookMethod assures that the created MethodHook instance contains a valid hook for OnClick
     MethodDefinition onClick = uiButton.GetMethod("OnClick");
     MethodHook hookMethod = this.GetHookMethod(onClick, hooks, "OnClickHook", MethodFeatures.PassTargetType);
     
     // Passing 0 will inject the hook method at the beginning of OnClick method
     this.AttachMethod(hookMethod, 0);
     
     // Add our tag to the assembly attribute to signify that the patch has been applied successfully
     SetPatchedAttribute(args.Assembly, TAG);
 }
</code>

{{Box1 start}}
'''NOTE:''' The alternative below is listed only for legacy reasons. ReiPatcherPlus 2.0+ marks <code>HookMethod</code> and <code>RedirectMethod</code> as obsolete. Consider using the above-mentioned code.
{{Boxes end}}

Alternatively, ReiPatcherPlus provides yet another method: <code>HookMethod(TypeDefinition targetType, string targetMethod, TypeDefinition hookType, string hookMethod)</code>.
This method takes the type definitions created in steps 1. and 2., and automatically hooks the function! This version of the method searches for the first methods that match the given method names and hooks them together.
If one wants better control of which method to hook, refer to the later sections where the capabilities of ReiPatcherPlus are exposed in greater detail.

Everything considered, our <code>Patch(PatcherArguments args)</code> method turns into:
<code>
 public override void Patch(PatcherArguments args)
 {
     // Hook UIButton.OnClick method to call CM3D2.HelloWorld.Hook.HelloWorldHooks.OnClickHook()
     this.HookMethod(args.Assembly.MainModule.GetType("UIButton"),
                     "OnClick", 
                     hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), 
                     "OnClickHook");
 
     // Add our tag to the assembly attribute to signify that the patch has been applied successfully
     SetPatchedAttribute(args.Assembly, TAG);
 }
</code>

=== Summary ===
By combining the code from the subsections above we will get a fully working patcher! Of course, it is a simple (it does not even override <code>PostPatch()</code>!), yet fully working class.
In the next section we shall briefly discuss writing plug-in DLLs for UnityInjector.

The final source of our patcher class:
<code>
 using System.Reflection;
 using Mono.Cecil;
 using ReiPatcher;
 using ReiPatcher.Patch;
 using ReiPatcherPlus;
 
 namespace CM3D2.HelloWorld.Patcher
 {
     public class HelloWorldPatch : PatchBase
     {
         private const string TAG = "CM3D2_HELLO_WORLD";
         private AssemblyDefinition hookAssembly;
 
         public override string Version
         {
             get { return Assembly.GetExecutingAssembly().GetName().Version.ToString();}
         }
 
         public override string Name
         {
             get { return "Hello, world! Patch for CM3D2"; }
         }
 
         public override bool CanPatch(PatcherArguments args)
         {
             return args.Assembly.Name.Name == "Assembly-CSharp" && !this.HasAttribute(args.Assembly, TAG);
         }
 
         public override void Patch(PatcherArguments args)
         {
             TypeDefinition uiButton = args.Assembly.MainModule.GetType("UIButton");
             TypeDefinition hooks = hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks");
             
             MethodDefinition onClick = uiButton.GetMethod("OnClick");
             MethodHook hookMethod = this.GetHookMethod(onClick, hooks, "OnClickHook", MethodFeatures.PassTargetType);
             
             this.AttachMethod(hookMethod, 0);
             
             SetPatchedAttribute(args.Assembly, TAG);
         }
 
         public override void PrePatch()
         {
             RPConfig.RequestAssembly("Assembly-CSharp.dll");
             hookAssembly = this.LoadAssembly("CM3D2.HelloWorld.Hook");
         }
     }
 }
</code>

== Writing the plug-in DLL (using UnityInjector) ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API.<br/>
It is important to notice that although UnityInjector relies on ReiPatcher to be installed, both are completely standalone tools in plug-in development.
It is possible to create plug-ins that are only installed by ReiPatcher, plug-ins that act as Unity's game objects loaded on-the-fly with UnityInjector, or plug-ins that take advantage of both tools to create versatile and diverse additions into Unity Engine games.

As mentioned, UnityInjector plug-ins are not patched into the game. Instead, they are loaded dynamically and added to the game as custom <code>MonoBehaviour</code>s.
In other words, UnityInjector allows to insert custom scripts into the game.

Writing plug-ins is simple: create a custom class that extends <code>PluginBase</code>. That is it.
Alternatively, one can add one or many of the following attributes to the class:
{| class="wikitable"
|-
! Attribute example !! Description
|- 
| <code>[PluginFilter("<executable>")]</code> || The plug-in will be loaded only when the name of the game executable is the same as <executable>. If not specified, UnityInjector will always load the plug-in.
|-
| <code>[PluginName("<name>")]</code> || Specifies the name of the plug-in. Useful for debugging. If not specified, the name will be that of the plug-in class.
On UnityInjector 1.0.1.0 and newer, will now fallback to the Assembly Name if not specified.
|-
| <code>[PluginVersion("<version>")]</code> || Specifies the version of the plug-in. Useful for debugging. If not specified, the version will be set to "1.0".
On UnityInjector 1.0.1.0 and newer, will now fallback to the Assembly Version if not specified.
|}

Therefore, in our case the class will look like this:
<code>
 using System;
 using UnityInjector;
 using UnityInjector.Attributes;
 // If you use ReiPatcher to make custom hooks, remember to reference your hook assembly
 using CM3D2.HelloWorld.Hook;
 using ExIni;
 
 namespace CM3D2.HelloWorld.Plugin
 {
     [PluginName("Hello, world! Unity Plug-In"), PluginVersion("0.0.0.1")]
     public class HelloWorldPlugin : PluginBase
     {
     }
 }
</code>

=== About scripting ===
Unlike ReiPatcher, or any other tool discussed so far, Unity does not use C# in a conventional manner. Instead of providing method overrides, the engine simply calls the methods with certain names when an event occurs. These methods are referred to as "messages" in Unity.

There is a foison of different messages one can use to script the behaviour of the plug-in. All of them are well documented on [http://docs.unity3d.com/ScriptReference/MonoBehaviour.html Unity's own documentation website].
Furthermore, UnityInjector contains <code>Message</code> enumeration with all the scriptable message names which can be used as a quick reference while creating own plug-ins.

All in all, it is highly advised to read [http://docs.unity3d.com/Manual/ScriptingSection.html Unity's tutorial on scripting] to fully take advantage of engine's capabilities.

=== Manipulating INI files ===
ReiPatcher comes bundled with ExIni, a simple library that provides the ability to work with INI configuration files.

In our case, we want to give the user the ability to redefine the key which toggles "Hello, world!" messages on and off.

Fortunately, ExIni and UnityInjector will create missing configuration files and properties if they do not exist. That significantly simplifies scripting.
Let us simply create a method <code>LoadConfig()</code> that will load the key configuration or create it if there isn't one:
<code>
 // In the beginning of the class
 private const KeyCode TOGGLE_KEY_INITIAL = KeyCode.K;
 private KeyCode toggleKey = TOGGLE_KEY_INITIAL;
 private bool displayText = true; // We will alter the value of this variable with the key
 //...
 
 private void LoadConfig()
 {
     // Preferences is an instance of ExIni.IniFile that is defined in PluginBase.
     // If no INI file is found, UnityInjector will create one automatically.
     // That is why we don't need to perform any checks.
     // This command will attempt to find a key "ToggleKey" in section "Key_Mappings".
     // If such section/key does not exist, it will be created on-the-fly.
     IniKey key = Preferences["Key_Mappings"]["ToggleKey"];
 
     // If no key existed or it was left empty, the value will be null
     if (key.Value == null)
     {
         key.Value = Enum.GetName(typeof(KeyCode), toggleKey);
         // Note that ExIni nor UnityInjector save the configuration. Remember to do it yourself!
         SaveConfig();
     }
     else
     {
         try
         {
             // If the key is found, we attempt to parse it into UnityEngine's KeyCode enum
             toggleKey = (KeyCode)Enum.Parse(typeof(KeyCode), key.Value, true);
         }
         catch (Exception)
         {
             // If we fail, set reset it to the initial value and save our work
             toggleKey = TOGGLE_KEY_INITIAL;
             key.Value = Enum.GetName(typeof(KeyCode), toggleKey);
             SaveConfig();
         }
     }
 }
</code>

Note, that the name of plug-in's INI configuration file will be the same as plug-in class name. In our case, calling <code>SaveConfig()</code> will create a configuration file named <code>HelloWorldPlugin.ini</code> which will be saved to <code><Game's main directory>\UnityInjector\Config</code>.

=== Adding the event handler ===
If you used ReiPatcher to create a custom hook, it is high time we added an event handler for it. In that case, remember to reference the hook assembly in the plug-in project to access the hooked event.
In the case of this tutorial, we shall reference "CM3D2.HelloWorld.Hook" and use the namespace.<br/>
After that, we create an event handler called <code>OnButtonClick(UIButton button)</code> in our plug-in. In it, we simply check that the button is enabled (that is, clickable) and we can display the text. If all lights are green, we print our message.

Having written our event handler, it is only left to be added to the event itself. That is done in <code>Awake()</code> method, that in Unity acts as a constructor. In fact, there are not a lot of differences between the two, one of them being that <code>Awake()</code> guarantees that all game objects have been initialised and are accessible from this method.<br/>
In the <code>Awake()</code> method we firstly call <code>LoadConfig()</code> to load the configuration file; only thereafter we add the event handler to the event.

In the end we have ended up with two new methods in our <code>HelloWorldPlugin</code>:
<code>
 // Used instead of constructor
 public void Awake()
 {
     LoadConfig(); // Load the configuration
     HelloWorldHooks.ButtonClicked += OnButtonClick; // Add our own event handler to ButtonClicked event
 }
 
 // This is our event handler. It will be called every time HelloWorldHooks.OnClickHook() will be called.
 private void OnButtonClick(UIButton button)
 {
     // Check that button is enabled and text displaying is not disabled
     if (button.isEnabled && displayText)
         Console.WriteLine("Beep! Hello, world!");
 }
</code>

=== Final steps: getting input ===
To finish our patch, we shall implement simple input processing. Since input is updated every tick, it makes sense to put our input checking into <code>Update()</code> message.

The code below speaks for itself:
<code>
 // On top of the class
 private bool isKeyPressed = false; // Helper boolean to prevent multiple toggles
 
 //...
 
 public void Update()
 {
     if (!isKeyPressed && Input.GetKeyDown(toggleKey))
     {
         // We can still use in-game classes without hooking them.
         // For instance, in CM3D2 we can emit button click sounds with the command below
         GameMain.Instance.SoundMgr.PlaySystem(displayText ? "SE001.ogg" : "SE002.ogg");
 
         displayText = !displayText;
         isKeyPressed = true;
     }
     else if (isKeyPressed && Input.GetKeyUp(toggleKey))
         isKeyPressed = false;
 }
</code>

=== Summary ===
In this section we discussed how to create plug-ins for UnityInjector. As we have witnessed, the process is rather simple and just requires some knowledge of Unity scripting API.

Here is the source code for our plug-in class:
<code>
 using System;
 using CM3D2.HelloWorld.Hook;
 using ExIni;
 using UnityEngine;
 using UnityInjector;
 using UnityInjector.Attributes;
 
 namespace CM3D2.HelloWorld.Plugin
 {
     [PluginName("Hello, world! Unity Plug-In"), PluginVersion("0.0.0.1")]
     public class HelloWorldPlugin : PluginBase
     {
         private const KeyCode TOGGLE_KEY_INITIAL = KeyCode.K;
 
         private KeyCode toggleKey = TOGGLE_KEY_INITIAL;
         private bool displayText = true;
         private bool isKeyPressed;
 
         public void Awake()
         {
             LoadConfig();
             HelloWorldHooks.ButtonClicked += OnButtonClick;
         }
 
         public void Update()
         {
             if (!isKeyPressed && Input.GetKeyDown(toggleKey))
             {
                 GameMain.Instance.SoundMgr.PlaySystem(displayText ? "SE001.ogg" : "SE002.ogg");
                 displayText = !displayText;
                 isKeyPressed = true;
             }
             else if (isKeyPressed && Input.GetKeyUp(toggleKey))
                 isKeyPressed = false;
         }
 
         private void LoadConfig()
         {
             IniKey key = Preferences["Key_Mappings"]["ToggleKey"];
             if (key.Value == null)
             {
                 key.Value = Enum.GetName(typeof (KeyCode), toggleKey);
                 SaveConfig();
             }
             else
             {
                 try
                 {
                     toggleKey = (KeyCode) Enum.Parse(typeof (KeyCode), key.Value, true);
                 }
                 catch (Exception)
                 {
                     toggleKey = TOGGLE_KEY_INITIAL;
                     key.Value = Enum.GetName(typeof (KeyCode), toggleKey);
                     SaveConfig();
                 }
             }
         }
 
         private void OnButtonClick(UIButton button)
         {
             if (button.isEnabled && displayText)
                 Console.WriteLine("Beep! Hello, world!");
         }
     }
 }
</code>

== Source code and example projects ==
Below is a list of different projects written for ReiPatcher and UnityInjector. The projects can be used as templates for own projects.
* [https://github.com/usagirei/CM3D2_CameraControlEx Extended Camera Control] by [http://www.hongfire.com/forum/member.php/1283907-usagirei usagirei]

== ReiPatcherPlus: methods overview ==
The previous sections have covered all of the ReiPatcher and UnityInjector API, while ReiPatcherPlus and ExIni have been covered only briefly.
In the following two sections ('''Note:''' ExIni will come later) we will discuss the possibilities that ReiPatcherPlus and ExIni provide.

This section is dedicated to ReiPatcherPlus: a ReiPatcher extension that condenses complicated Mono.Cecil code into simple-to-use methods.

ReiPatcherPlus is used alongside ReiPatcher to add additional functionality to programmer's patcher class that inherits ReiPatcher's <code>PatchBase</code>.
As of this writing, such functionality includes method hooking, redirecting, modifying accessibility of class members, assembly loading and attribute checking.

Note that accessing ReiPatcherPlus's methods requires one to use <code>this.</code>, or the extension method's won't be seen.

In the examples we shall use the following class that contains potential methods to hook:
<code>
 namespace Game
 {
     public class Swallow
     {
         protected enum SwallowType
         {
             European,
             African
         }
         
         private float airSpeedVelocity = 11.2F;
         
         public float GetNeededSwallows(int coconuts);
         public float GetNeededSwallows(float distance);
         public bool IsSwallowEuropean(bool isNotAfrican);
         public static T FirstSwallow<T>(List<T> swallows);
         public static T FirstSwallow<T>(List<T> swallows, T addition);
         private void MakeFly(bool isUnladen, float distance);
     }
 }
</code>

=== Getting methods and fields ===
ReiPatcherPlus adds two new extension methods to Mono.Cecil that allow to locate method definitions in their respected types.
Those methods are added as extensions to <code>Mono.Cecil.TypeDefinition</code> type.<br/>
Those two methods are:
<code>
 MethodDefinition GetMethod(string methodName);
 MethodDefinition GetMethod(string methodName, params TypeReference[] paramTypes);
</code>
where the arguments are:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>methodName</code> || Name of the method to search for.
|-
| <code>paramTypes</code> || <code>TypeReference</code> representation of method parameters. Used to search for the exact overload of a method.
|}

Furthermore, one can easily acquire member fields (delegates, variables) of the type. That is done with the method:
<code>
 FieldDefinition GetField(string memberName);
</code>
where <code>memberName</code> is name of the member to search for.

In both cases, the methods will return <code>null</code>, if the fitting method/field has not been found. Therefore, it is up to the developer to make sure the provided parameters point to a valid method or field. 
In some cases, the programmer may need to perform null checking.

==== Examples ====
<code>
 TypeDefinition swallowType = MyModule.GetType("Game.Swallow");
 
 // Will return GetNeededSwallows(int)
 MethodDefinition m1 = swallowType.GetMethod("GetNeededSwallows");
 
 // Will return GetNeededSwallows(float)
 MethodDefinition m2 = swallowType.GetMethod("GetNeededSwallows", Parameter.FromType<float>());
 
 FieldDefinition f1 = swallowType.GetField("airSpeedVelocity");
</code>

=== Handling parameters ===
To make turning <code>System.Type</code> and normal type declarations into dummy <code>TypeReference</code>s to use with ReiPatcherPlus, <code>Parameter</code> class was created.
The class houses a panoply of useful methods to create "dummy type references" (they are not actual references to the real types -- instead, they are containers for type information used method search methods).<br/>
Such methods are:
<code>
 TypeReference FromType(Type type, params string[] genericTypeNames);
 TypeReference FromType<T>();
 TypeReference FromTypeRef(Type type, params string[] genericTypeNames);
 
 TypeReference CreateGeneric(string name);
</code>

For the first four methods, the parameter descriptions are as follows:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>type</code> || <code>System.Type</code> representation of the given type. Can be acquired with <code>typeof(TypeName)</code>.
|-
| <code>genericTypeNames</code> || Names of the generic types. Used only, if the provided <code>type</code> has undefined generic parameters.
|-
| <code><T></code> || Type name of the type to be converted. Calling <code>FromType<T>()</code> has the same effect as <code>FromType(typeof(T))</code>.
|}

As for <code>CreateGeneric</code>:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>name</code> || Name of the generic type to create.
|}

Note that in order for <code>GetMethod</code> to succeed with generic types, the names of those must stay the same. If the original method had a generic type <code>T</code>, one must make the type with <code>Parameter.MakeGeneric("T")</code> in order for the method to be found.
The same principle must hold when matching target method parameters with the hook method parameters.

==== Examples ====
<code>
 // t1 and t2 are technically the same 
 TypeReference t1 = Parameter.FromType(typeof(int));
 TypeReference t2 = Parameter.FromType<int>();
 
 // Creates a type of List<T>
 TypeReference t3 = Parameter.FromType(typeof(List<>), "T");
 
 // Creates a reference type System.Boolean&
 TypeReference t4 = Parameter.FromTypeRef(typeof(bool));
 
 TypeDefinition swallowType = MyModule.GetType("Game.Swallow");
 
 MethodDefinition m3 = swallowType.GetMethod("MakeFly", Parameter.FromType<bool>(), Parameter.FromType<float>());
 MethodDefinition m4 = swallowType.GetMethod("FirstSwallow", Parameter.FromType(typeof(List<>), "T"), Parameter.CreateGeneric("T"));
 
 // WILL NOT WORK: The provided generic types differ from the original definition
 MethodDefinition m5 = swallowType.GetMethod("FirstSwallow", Parameter.FromType(typeof(List<>),"A"), Parameter.CreateGeneric("G"));
</code>

=== The MethodHook type and getting hooks ===
To provide an easy patching experience, ReiPatcherPlus includes <code>MethodHook</code> container that exposes the following get-only properties:
{| class="wikitable"
|-
! Property !! Description
|-
| <code>Hook</code> || Method definition of the hook method. Will be hooked to the target.
|-
| <code>Features</code> || Additional criteria by which the hook method was chosen. Refer to the next subsection for more information.
|-
| <code>Target</code> || Method definition of the method to hook (target method).
|}

The creation of the <code>MethodHook</code> instance is controlled internally from ReiPatcherPlus. That way the library guarantees that the specified hook-target pair is valid and injectable.

Currently there are two ways of getting the instance: by using <code>PatchBase</code> extension <code>GetHookMethod</code> or by calling <code>MethodHook.FromMethodDefinition</code>.

The exact definitions are:
<code>
 MethodHook GetHookMethod(MethodDefinition target, 
                          TypeDefinition hookType, 
                          string hookName, 
                          MethodFeatures features, 
                          params FieldDefinition[] memberReferences);
 
 MethodHook MethodHook.FromMethodDefinition(MethodDefinition target, 
                                            MethodDefinition hook, 
                                            MethodFeatures features, 
                                            params FieldDefinition[] memberReferences);
</code>

The parameter description is the following:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>target</code> || The method definition of the method which is to be hooked.
|-
| <code>hookType</code> || The type (class/struct) that possesses the hook method.
|-
| <code>features</code> || The criteria by which the hook method should be chosen. Defines the structure of the hook method. Refer to the next subsection for more information.
|-
| <code>memberReferences</code> || If one of the criteria is <code>MethodFeatures.PassMemberReferences</code>, specifies the fields that are to be passed to the method.
|- 
| <code>hook</code> || Method definition of the hook method.
|}

While using the methods, note the following:
* When using <code>GetHookMethod</code>, the final <code>features</code> might be different from the ones specified. That is simply because the method adapts to its passed parameters to find the best hook method.
However, the method attempts to find the best hook without throwing any exceptions (for the exception of <code>ArgumentException</code> if the provided member fields do not belong to the target type).
* <code>MethodHook.FromMethodDefinition</code> strictly checks whether the provided target and hook are injectable. If a discrepancy is found, the method will throw an exception containing the reason the method failed.
* Prefer using <code>GetHookMethod</code>, as it mostly exception-free and will return either a working instance of <code>MethodHook</code> or <code>null</code>.

==== Method Features ====
To allow the developer to freely choose which kind of hook to use, what parameters to pass and what to return, ReiPatcherPlus allows to specify certain criteria that define the layot of the hook method.
Albeit allowing different set of parameters to be passed, the hook method must have its parameters in a certain order for ReiPatcherPlus to work with them.

Below is the hook method template with numbered positions and a table of what types are allowed in place of those positions and which <code>MethodFeatures</code> fields to use to enable those positions:
<code>
 public static <2.1> MyHookMethod(<1>, <2.2>, <3>, <4>);
</code>
{| class="wikitable"
|-
! <code>MethodFeatures</code> field !! Position value replacement, if feature specified (only types and prefixes specified) !! Description
|-
| <code>MethodFeatures.None</code> || <1>, <2.2>, <3>, <4> = Empty<br/><2.1> = <code>void</code> || The method may not have any of the features.
|-
| <code>MethodFeatures.PassTargetType</code> || <1> = Target type || The method may be passed a reference to the target type that initially called the hooked method.
|-
| <code>MethodFeatures.PassReturn</code> || <2.1> = <code>bool</code><br/>If target has a return type:<br/><2.2> = <code>out <return type></code><br/>Otherwise:<br/><2.2> = Empty || The hook method is a redirect and thus may be passed a reference to the return value (if there is such). If the the target method has a return value of type <code><return type></code>, a parameter of the same type is passed as a reference to the hook method.<br/>'''Note:''' If the feature is not specified, <2.1> must be <code>void</code>.
|-
| <code>MethodFeatures.PassMemberReferences</code> || <3> = <code>ref <type1>, ref <type2>, ...</code> || The method may pass references to the target type's member fields (assuming target method is not static) specified by the <code>MethodHook</code> creation method.
|-
| <code>MethodFeatures.PassMethodParametersByValue</code> || <4> = <code><type1>, <type2>, ...</code> || The method may pass its own parameters to the hook. Since they are passed by value, they cannot be altered.
|-
| <code>MethodFeatures.PassMethodParametersByReference</code> || <4> = <code>ref <type1>, ref <type2>, ...</code> || The method may pass its own parameters to the hook. Since they are passed by reference, they can be altered.
|}

Some important things to point out:
* The hook method '''must''' be public and static! Otherwise it is impossible to hook it anywhere.
* Some of the above-mentioned features can be left out. However the order of the parameters must be always preserved!
* If <code>MethodFeatures.PassReturn</code> is set, the hook method must return a <code>bool</code>. If the hook method returns <code>true</code>, the execution of the original target method's instructions is interrupted; the target method simply returns the result value it got from the hook method (if any). In the contrary, if the hook method return <code>false</code>, the original target method will continue its execution after the hook method has completed executing its instructions.
* Legacy notice: <code>MethodFeatures.PassReturn</code> makes ReiPatcherPlus search for a redirect method. However, since both hooking and redirecting have been combined into one single method, there is no point in differentiating between them anymore.

The features may be combined with a logical OR operator (<code>|</code>). In addition to the features above, the <code>MethodFeatures</code> enumeration has the following feature combinations:
{| class="wikitable"
|-
! Feature !! Combination equivalent
|-
| <code>MethodFeatures.All_ByValue</code> || <code><nowiki>MethodFeatures.PassTargetType | MethodFeatures.PassReturn | MethodFeatures.PassMemberReferences | MethodFeatures.PassMethodParametersByValue</nowiki></code>
|-
| <code>MethodFeatures.All_ByReference</code> || <code><nowiki>MethodFeatures.PassTargetType | MethodFeatures.PassReturn | MethodFeatures.PassMemberReferences | MethodFeatures.PassMethodParametersByReference</nowiki></code>
|}

==== Examples ====
<code>
 TypeDefinition swallowType = MyModule.GetType("Game.Swallow");
 // Getting type definition for the class that contains all the hook methods
 TypeDefinition hookType = HookModule.GetType("MyHookNamespace.Hook");
 
 MethodDefinition m1 = swallowType.GetMethod("GetNeededSwallows");
 MethodDefinition m2 = swallowType.GetMethod("MakeFly");
  
 // Valid hook method prototype: public static void GetNeededSwallowsHook1()
 MethodHook hookM1 = this.GetHookMethod(m1, 
                                        hookType, 
                                        "GetNeededSwallowsHook1",
                                        MethodFeatures.None);
 
 // Valid hook method: public static bool GetNeededSwallowsHook2(Swallow self, out float result, int coconuts)
 MethodHook hookM2 = this.GetHookMethod(m1,
                                        hookType,
                                        "GetNeededSwallowsHook2",
                                        MethodFeatures.PassTargetType
                                        | MethodFeatures.PassReturn
                                        | MethodFeatures.PassMethodParametersByValue);
 
 // Valid hook method: public static bool GetNeededSwallowsHook3(Swallow self, out float result, ref int coconuts)									
 MethodHook hookM3 = this.GetHookMethod(m1,
                                        hookType,
                                        "GetNeededSwallowsHook3",
                                        MethodFeatures.PassTargetType
                                        | MethodFeatures.PassReturn
                                        | MethodFeatures.PassMethodParametersByReference);
 
 // Valid hook method: public static bool MakeFlyHook(Swallow self, out float result, ref float airSpeedVelocity, int coconuts)									
 MethodHook hookM4 = this.GetHookMethod(m2,
                                        hookType,
                                        "MakeFlyHook",
                                        MethodFeatures.PassTargetType
                                        | MethodFeatures.PassReturn
                                        | MethodFeatures.PassMemberReferences
                                        | MethodFeatures.PassMethodParametersByValue,
                                        swallowType.GetField("airSpeedVelocity"));
 
 MethodDefinition hookMethod = hookType.GetMethod("MakeFlyHook2");
 
 // Valid hook method: public static bool MakeFlyHook(Swallow self, out float result, ref float airSpeedVelocity, ref int coconuts)									
 MethodHook hookM5 = MethodHook.FromMethodDefinition(m2,
                                                     hookMethod,
                                                     MethodFeatures.All_ByReference,
                                                     swallowType.GetField("airSpeedVelocity"))
</code>

=== Injecting the methods ===
Finally, ReiPatcherPlus provides a functionality to patch methods. That can be done with <code>AttachMethod</code> method.

The exact definitions and parameter descriptions are below:
<code>
 void AttachMethod(MethodHook hook, int codeOffset);
 void AttachMethod(MethodDefinition target, 
                   MethodDefinition hook, 
                   int codeOffset, 
                   MethodFeatures features,
                   params FieldDefinition[] memberReferences);
</code>
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>target</code> || The method definition of the method which is to be hooked.
|-
| <code>MethodDefinition hook</code> || Method definition of the hook method.
|-
| <code>features</code> || The criteria by which the hook method should be chosen. Defines the structure of the hook method. '''Default: ''' <code>MethodFeatures.None</code>
|-
| <code>memberReferences</code> || If one of the criteria is <code>MethodFeatures.PassMemberReferences</code>, specifies the fields that are to be passed to the method.
|- 
| <code>MethodHook hook</code> || An instance of <code>MethodHook</code> that contains all the appropriate information.
|-
| <code>codeOffset</code> || An index value of an IL instruction in the target method from which to begin injection. If set to negative, will begin counting from the last instruction of the target method, where -1 is being the last instruction.
|}

Elementary, these two methods will automatically inject the needed CIL instructions depending on the chosen hook/target method.<br/>
The latter method will verify the compatibility between the target and the hook before applying the patch. That method is equivalent to calling <code>MethodHook.FromMethodDefinition</code> and then <code>AttachMethod</code>.

Most of the time setting code offset to 0 will be sufficient for plug-ins. However, if one wants to place the hook at a certain place, refer to the previous sections on how to decompile the .NET code. Most of the decompilers come with IL decompilers bundled (like ILSpy), which allows to inspect pure IL instructions to find the perfect attachment point.

Note as well that <code>AttachMethod</code> will always add its own CIL instructions '''before''' the specified code offset! That is done to prevent the developers from inserting method hooks after the <code>ret</code> instruction that is always present as a last IL instruction in every method. Any code insterted after the said instruction is simply neglected by the machine.

==== Examples ====
<code>
 TypeDefinition swallowType = MyModule.GetType("Game.Swallow");
 TypeDefinition hookType = HookModule.GetType("MyHookNamespace.Hook");
 
 MethodDefinition m1 = swallowType.GetMethod("GetNeededSwallows");
 
 // Valid hook method prototype: public static void GetNeededSwallowsHook1()
 MethodHook hookM1 = this.GetHookMethod(m1, 
                                        hookType, 
                                        "GetNeededSwallowsHook1",
                                        MethodFeatures.None);
 
 this.AttachMethod(hookM1, 0);
</code>

=== Changing accessibility ===
When searching through assemblies you might encounter a member or a method that is set to be private, even though you would want to access outside the class.

ReiPatcherPlus provides a simple method to make such private types accessible:
<code>
 void ChangeAccess(TypeDefinition type, string member, bool makePublic = true, bool makeVirtual = true);
</code>

The method has the following arguments:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>type</code> || Type (class/struct) that contains the member to manipulate. Can be gained from an assembly with the <code>AssemblyDefinition.MainModule.GetType(string typeName)</code> method.
|-
| <code>member</code> || Name of the member to manipulate.
|-
| <code>makePublic</code> || If <code>true</code>, will make the member public. '''Default:''' true.
|-
| <code>makeVirtual</code> || If <code>true</code> and <code>member</code> is a method, will make it virtual. '''Default:''' true.
|}

=== Debugging functions ===
ReiPatcherPlus provides simple methods for patcher message logging. All of the logging methods are located in <code>RPPLogger</code> class.

However, to enable logging, one must use the DEV version of the ReiPatcherPlus (slightly larger file size than normal ReiPatcherPlus).
After that, one can set <code>RPPLogger.VERBOSE_LEVEL</code> variable to enable logging of certain methods.

Possible variable values are:
{| class="wikitable"
|-
! Flag !! Description
|-
| <code>RPPLogger.VerboseLevel.None</code> || Don't output any messages
|- 
| <code>RPPLogger.VerboseLevel.Patcher</code> || Output patcher-related messages (getting hook methods, attaching methods, etc.).
|-
| <code>RPPLogger.VerboseLevel.Cecil</code> || Output Mono.Cecil-related extension method messages. Includes parameter equality checking and method searching.
|}

The flags can be combined with a logical OR (<code>|</code>) operator.

If one whishes to output own logging messages, it is possible through the following methods located in <code>RPPLogger>/code>:
<code>
 void Log(string message, VerboseLevel level, bool addPrefix);
 void LogLine(string message, VerboseLevel level, bool addPrefix);
</code>

And the parameters:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>message</code> || Message to output.
|-
| <code>level</code> || The level to output the message to. Used to filter the output based on selected levels.
|-
| <code>addPrefix</code> || If <code>true</code>, will append a prefix specified on <code>RPPLogger.PREFIX</code> before the specified <code>message</code>.
|}

The difference between the methods is that the latter will add a line break to the message, while the former one will not.

==== Examples ====
<code>
 // Set verbose level to patcher only
 RPPLogger.VERBOSE_LEVEL = RPPLogger.VerboseLevel.Patcher;
 
 // Will be shown in ReiPatcher console
 RPPLogger.LogLine("Hello, log!", RPPLogger.VerboseLevel.Patcher);
 
 // Won't be seen in ReiPatcher
 RPPLogger.LogLine("I am hidden!", RPPLogger.VerboseLevel.Cecil);
</code>
 
=== Miscellaneous methods ===
Here are some other small methods that simplify the workflow:
{| class="wikitable"
|-
! Method !! Description
|-
| <code>bool HasAttribute(AssemblyDefinition assembly, string attribute)</code> || Checks whether the assembly has a string attribute set. Can be used in <code>CanPatch(PatcherArguments args)</code> to determine if the patch has already been applied.
|-
| <code>AssemblyDefinition LoadAssembly(string name)</code> || Loads a custom assembly from the <code>AssembliesDir</code> path set by ReiPatcher. Can be used in <code>PrePatch()</code> to load hook assemblies.
|}

=== Legacy and other obsolete methods ===
These methods are marked as obsolete and must not be used. Instead, use the newer functionality of ReiPatcherPlus.

==== Method hooking ====
ReiPatcherPlus has two overrides of this method:
<code>
 void HookMethod(TypeDefinition targetType, string targetMethod, 
            TypeDefinition hookType, string hookMethod, bool passSelf = true);
 
 void HookMethod(TypeDefinition targetType, string targetMethod, 
            Type[] targetParams, TypeDefinition hookType, string hookMethod, 
            bool passSelf = true);
</code>

Where the arguments are:
{| class="wikitable"
|-
! Argument !! Description
|-
| <code>targetType</code> || Type (class/struct) which contains the method to be hooked. Can be gained from an assembly with the <code>AssemblyDefinition.MainModule.GetType(string typeName)</code> method.
|-
| <code>targetMethod</code> || Name of the method to hook.
|- 
| <code>targetParams</code> || An array containing the <code>Type</code> of each target method's arguments in the order they are defined in the method. Used to find the exact method to hook.
|-
| <code>hookType</code> || Type (class/struct) which contains the hook method.
|-
| <code>hookMethod</code> || Name of the hook method.
|-
| <code>passSelf</code> || If true, the hooked method will pass an instance of an object in which the method was called to the hook. '''Default:''' true.
|}

In order for <code>HookMethod</code> to succeed in hooking the method, the hook must be defined with the right arguments.
The type and the number of arguments needed depends on the choice of the override:
* If the former override is chosen, the hook must contain only one argument: object of the type that contains the hooked method. However, if <code>passSelf</code> is set to <code>false</code>, the hook must have no arguments at all.
* If the latter override is chosen, the hook must contain one more argument than the method it hooks: the first is the object of the type that contains the hooked method, and the rest are the same arguments as those of the method that is to be hooked. However, if <code>passSelf</code> is set to <code>false</code>, the hook must have exactly the same arguments as the method that is hooked.
* If the former override is chosen and the hooked method contains some arguments, they will not be passed to the hook. For that, use the latter override.

In all cases, the hook must be a method without any return values (<code>void</code>, that is).

==== Method redirecting ====
The overrides are akin to <code>HookMethod</code> and the arguments are too:
<code>
 void RedirectMethod(TypeDefinition targetType, string targetMethod, 
            TypeDefinition redirectType, string redirectMethod, bool passSelf = true);
 
 void RedirectMethod(TypeDefinition targetType, string targetMethod, 
            Type[] targetParams, TypeDefinition redirectType, string redirectMethod, 
            bool passSelf = true);
</code>

The biggest difference is in how the redirect method <code>MyMethod</code> should be defined:
* The return type must be <code>bool</code>. If the redirect returns <code>true</code>, the redirected method will return immediately without continuing the execution. If <code>false</code> is returned, the redirected method will proceed to its own instructions (just like in <code>HookMethod</code>).
* <code>passSelf</code> acts the same as in <code>HookMethod</code> and therefore requires an object of the type with the redirected method (if <code>passSelf=true</code>).
* If the redirected method has a return value (not <code>void</code>, that is), the redirect method must have an additional argument after the object type (if <code>passSelf=true</code>): reference type of the redirected method's return value (that is an argument that has <code>out</code> word before the type name). The value of this argument can be set by the redirect method. If redirect method returns <code>true</code>, the redirected method will use that value as its own return value.