Hgames Wiki - User contributions [en]

User:Denikson

2017-11-01T15:25:37Z

Denikson:

= About denikson =

Mainly developer for CM3D2 plug-ins. Some of my creations:

* [https://github.com/denikson/CM3D2.MaidFiddler Maid Fiddler] (CM3D2 in-game editor)
* [https://github.com/denikson/CM3D2.YATranslator YATranslator] (a translation loader for CM3D2)
* Tutorials for ReiPatcher and UnityInjector

== Contact ==

[https://github.com/denikson denikson@GitHub] (my projects) 
[http://www.hongfire.com/forum/member/1347954-denikson denikson@HongFire] 
ghorsington#0834 on Discord

User:Denikson

2017-11-01T15:24:04Z

Denikson:

Custom Maid 3D2/Technical Help

2017-11-01T15:23:12Z

Denikson: Corrected some notes about YATranslator

{{Custom Maid 3D 2}}
=FAQ=
==Running the game==
*'''Q1: I keep getting an "(0) Yotogi.Category enum parse error (character not japanese)" error when I run the game and I have tried both AppLocale and NTLEA?'''
: A: You can't use AppLocale to run the x64 version because AppLocale don't support x64 version. but you can use AppLocale to run the x86 version on Windows 7,8 by step below
# Copy files and folders CM3D2x86_Data and CM3D2x86.exe from '''installation folder''' into your game folder. (example: C:\KISS\CM3D2\)
# Right click CM3D2x86.exe and select Run with Japanese locale. (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options.) '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
: A: The best way for solve this problem is set '''window system locate to japanese''' but if you still want to run the x64 version or window 10 without set window system, you can using [https://ntlea.codeplex.com NTLEA x64] by setting [https://puu.sh/y0gTm/9619f6c611.png here] and press the arrow on the bottom right. This makes that you can right click CM3D2x64 to run with NTLEA x64.
: A: Set '''window system locate to japanese''' to do the following:
: Control Panel > Region > Administrative Tab > Language for non-Unicode programs choose <code>Japanese(Japan)</code> and restart your computer.

*'''Q2: My game crashes doing in maid creation or doing change skin color and my graphic card is AMD. How to fix this problem?''' 
: A: Maybe this guide is helpful for you [http://www.hongfire.com/forum/showthread.php/445139-AMD-CRASH-FIX-FOR-Radeon-HD-Series AMD CRASH FIX FOR Radeon HD Series] or you can access [http://pastebin.com/t3m1Lg3h this] in case the website blocked.

*'''Q3: How do I install the translations?''' 
: A: See [[Custom_Maid_3D_2/Technical_Help#Translate_Plus_Plugin|Translate Plus]] or [[Custom_Maid_3D_2/Technical_Help#YATranslator_Plugin|YATranslator]].

*'''Q4: I get this error when running the HF Patch: "... The game is an unsupported version. This patch requires version 1.03...", what can I do?''' 
: A: Install the official v1.03 patch and then run the HF Patch again.

*'''Q5: I get a "Daily panel" error during gameplay.''' 
: A: Make sure that you have the official 1.03 patch installed (and it is correct version x86 or x64) and then run the HF Patch again.

*'''Q6: When installing patch keeps telling me "Game main executable couldn't be found, patch may be invalid" that after I try to install the patch. 
: A: Make sure your game is installed correctly. If not installed correctly, patch cannot be detected CM3D2 in the window. If you make sure you have done this correctly, try reloading the patch again.

*'''Q7: Incorrect Position UI, Transparent UI, White UI, Black screen stuck on Day 1, Night service skill name overlapping after update patch.''' 
: A: Delete Folder "Assets" and "Texture" in <code>Sybaris\UnityInjector\Config</code> and replace them with files download from [https://mega.nz/#!soIGDAAb!OPEppFIJNIJ-iG1m6yDr1HI9wCn9OhzCMuQhbQZNRV4 v1.49 UI translation]. This solve whatever problem you encouter (v1.49 UI translation for ver1.52, older version you can find them in HF).
: '''''Note: this trouble often found after KISS update the game, be careful this solution in this specific to your game version.'''''

*'''Q8: After installed Karaoke Pack VR, I can't found the karaoke button on the menu and I have used translate plugin? 
: A: Update patch v1.53 and replace a file in translate UI assets folder with file from [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/414082/page9#post5825775 here].

==Gameplay==
*'''Q1: I got this option for my maid to choose between Free and something. What does this mean? ''' 
: A: You are choosing between making your [[Custom_Maid_3D_2/Gameplay/The_Maid_Profile#Maid_Type|Maid Type]]. There are two types of maid is personal (only has sex with you) and free (has sex with the customers). The first earns you less money than the second.

*'''Q2: How can I replay VIP scenes?''' 
: A: <del>If you want to play them again, you must keep a save file before play the VIP. (After 100 days in game, VIP events that have been played over the first 99 days in game are again avalable to be played with forever but the same requirements are still applied as per the VIP event.)</del> 
: A: After v1.21 and Plus Pack, you can replay unlocked VIP events in [[Custom_Maid_3D_2/Gameplay#Free_Mode|Free Mode]].

*'''Q3: What are red options during sex?''' 
: A: These are '''one-time''' options for the skill. You can use them again next time if you use this skill again.

*'''Q4: How do I get more maids? I only have 1-2.''' 
: A: You need to get your club '''out of debt''' first. Also, there is no upper limit on maids, but there is an upper limit on six working maids.

*'''Q5: How do I unlock new rooms? ''' 
: A: Increase your [[Custom_Maid_3D_2/Gameplay#Club_Grade|Club Grade]] from cleaning, decorating and eval and other [[Custom_Maid_3D_2/Gameplay#Rooms|Rooms]] require expansion installation. This is possible while still in debt.

*'''Q6: After having sex with my maid, I got a notification. Something to do with being close? What does this mean? ''' 
: A: It means you've advanced your [[Custom_Maid_3D_2/Gameplay/The_Maid_Profile#Status|Relationship]] with your maid.

*'''Q7: How do I earn CR for pay off the 10m Debt?''' 
: A: You can earn a small amount 50k~100k CR of money by "Dispatch" maids during the daytime, but the most amount of money comes from "Entertain" on nighttime. Entertain can earn 200k~1m CR per night per maid depending on club grade. Both Free Maids and Personal Maids are able to entertain.

*'''Q8: It is said that I got "Ring" from the Lovers Trophy but I can't seem to find it... where can I find it?''' 
: A: It's only unlocked by the time you got the "Lovers" Trophy. You still need to buy it from the shop for 10.000.000CR to equip the ring in the arms category.

*'''Q9: All of sudden, There is no "Talk to her" option... What am I doing wrong? ''' 
: A: You didn't put either top or bottom clothes for her, which makes her feels too embarrassed to talk to you. Try to put some clothes instead you ecchi-goshujinsama.

*'''Q10: I can't seem to make the rental maid to do her VIP event? ''' 
: A: You need to supervise her daily activities to earn her trust until you trigger all the 3 specific events which occurs per-day, the last one will pop-up a dialogue that tells you the VIP event is unlocked. The VIP event only occurs once and is not replayable since she's a rental maid. Explained in [[Custom_Maid_3D_2/Gameplay/VIP_Events#NPC_Maid|NPC Maid VIP]]

*'''Q11: My game system don't have free mode, marriage, honeymoon, maid battle, empire league, vacation and karaoke, how can I unlock there systems? ''' 
: A: You can unlock there game systems from installing append pack below.
#[http://kisskiss.tv/cm3d2/plus Plus Pack] will unlock '''free mode''' and '''maid battle''' system.
#[http://kisskiss.tv/cm3d2/plus2 Plus Pack ACT.2] will unlock '''marriage''' and '''empire league''' system.
#[http://kisskiss.tv/cm3d2/plus3 Plus Pack ACT.3] will unlock '''honeymoon''' system.
#[http://kisskiss.tv/cm3d2/vpvr Vacation Pack VR] will unlock '''vacation''' system.
#[http://kisskiss.tv/cm3d2/kpvr Karaoke Pack VR] will unlock '''karaoke''' system.

==Text Hooking - Visual Novel Reader==
*'''Q1: Why can't I get VNR to work with the game?''' 
: A: VNR doesn't work with the x64 version of the game, use the x86 version instead.

*'''Q2: I managed to sync VNR to CM3D2 but I can't make it translate. The TL box won't come out. What's wrong?''' 
: A: Either enable the VNR built in hooker or rollback; overwrite your current VNR folder.

=Installed Guide=
More information can be found in [http://www.hongfire.com/forum/forum/hentai-lair/hentai-game-discussion/418479 CM3D2 Hongfire] or [https://www.reddit.com/r/cm3d2/comments/6faqro/support_megathread CM3D2 Reddit].
==Installing the Game==
[[File:CM3D2_Installer.png|thumb|Click the highlighted button to install]]
[[File:CM3D2_Insert_disk2.png|thumb|Insert disk 2]]
#Set the '''window system locate to japanese''' or '''[https://ntlea.codeplex.com NTLEA x64]''' '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
#Extract <code>cm3d2_1.iso</code> and <code>cm3d2_2.iso</code> '''(DO NOT extract the .mds files).'''
#Mount <code>cm3d2_1.iso</code> with [http://www.disk-tools.com/download/daemon Daemontools Lite] (If you have trouble using other mounting software, Daemontools Lite has been confirmed to work).
#'''DO NOT autorun''', but open the mounted dvd in explorer and click <code>Installer.exe</code> if your computer locale already in japanese, otherwise, right-click <code>Installer.exe</code> and select Run with Japanese locale as an administrator (you need '''NTLEA x64''' for the right-click options).
#Optional: Change the install folder (default is C:\KISS).
#Click the button <code>インストール</code> to start the CM3D2 setup.
#Confirm that you want to install to that location and wait while the setup until setup asks for disk 2.
#Mount <code>cm3d2_2.iso</code> and click Retry.
#Wait for the setup to finish and close the installer.
 
 
 
 
==Updating Patch==
[[File:Kissupdatepage.JPG|thumb|right|KISS official update webpage]]
[[File:Kissupdate folder.JPG|thumb|right|Extracted .zip files]]
#Set the '''window system locate to japanese''' or '''[https://ntlea.codeplex.com NTLEA x64]''' '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
#Download the latest full update that is meant for the version you run (either x86 or x64). For lastes version update: http://kisskiss.tv/cm3d2/update.php Or visit forum for mirrors: [http://www.hongfire.com/forum/forum/hentai-lair/hentai-game-discussion/418479 CM3D2 discussion]
#Download the updater ver.1.00～1.12 (cm3d2_up_for_1_00-1_12).
#Extract the .zip file and execute the <code>update.exe</code> located inside the extracted folder. (It will auto-detect your installation directory) you can simply execute the <code>update.exe</code> if your computer locale already in japanese, otherwise, right-click <code>update.exe</code> and select ''Run with Japanese locale as an administrator'' (you need '''NTLEA x64''' for the right-click options).
#Choose <code>適用</code> -> <code>開始</code>, and wait for the patch to be extracted and installed.
#Download the latest updater (example: cm3d2_up153_x86_sub or cm3d2_up153_x64_sub) and repeat ''step 4 and 5'' after downloading the latest updater.
#After update complete, next time you can update the latest patch into your game without update ver.1.00～1.12 again.
Additional screenshots for '''Step 5''' as below:
{| class="wikitable"
|-
| [[File:Kissupdate patch1.JPG|300px|center]] || [[File:Kissupdate patch2.JPG|300px|center]]
|}

'''''1st Note:''' If the patch didn't detect your installation directory and/or somehow the update.exe bugged, you can overwrite the ''GameData'' folder, and you will also need to update the ''update.lst'' file, which is advanced for veteran users.'' 
'''''2nd Note:''' The '''update.exe''' will not install an already installed patches/DLCs as seen in additional screenshots for Step 5 where the START option is '''''greyed out''''', it follows the ''update.lst'' file, in case you are wondering it is located on your CM3D2 Root directory. (example: ''C:\KISS\CM3D2\'')'' 
'''''3rd Note:''' For the old version update can be found [http://kisskiss.tv/cm3d2/oldupdate.php here]''

==Installing Sybaris==
===Sybaris FAQ===
*'''Q1: What is Sybaris? 
: A: Sybaris is loader that runs plugins other than the official plugins have been installed in the base game.

*'''Q2: What is the difference between Sybaris and Reipatcher? 
: A: Both loader have no difference in usability. The only difference is the methods of operation.

*'''Q3: Why use Sybaris? 
: A: Sybaris have the advantage better than Reipatcher is: 
# Does not affect the base game, you can go back to vanilla anytime. 
# Updating the game causes less problems.

*'''Q4: Sybaris have a disadvantage? 
: A: Sybaris has the following disadvantages: 
# Many plugins for Sybaris are only available in japanese language. 
# Some Reipatcher plugins are incompatible with Sybaris, such as Unified Translation Loader.

*'''Q5: Sybaris need to install Reipatcher? 
: A: No

*'''Q6: How many sybaris plugins are supported?
: A: You can check [https://pastebin.com/va3qWhaQ here] or [http://motimoti3d.jp/blog-entry-37.html motimoti3d]

----
===Sybaris===
For an easy installation you can download: [https://mega.nz/#!XFJUQAjL!G2GMTKUt2XGCo94Q3SII5Ki02u1LtMEECyCa9QrEr-g Sybaris Starter Pack 1.52] or [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5816208-sybaris-aio-ultimate-english-expansion-1-53-1-beta-suggestions-are-welcome Sybaris AIO Ultimate English Expansion - 1.53.1 Beta] 
This Package contains:
* Sybaris support v1.52+
* Plugins
* Translator
* Uncensor

1. Download [https://ux.getuploader.com/cm3d2_e/download/317/cm3d2_e_317.zip Sybaris] or Sybaris Starter Pack or Sybaris AIO 
2. Copy '''opengl32.dll''' and '''Sybaris''' folder and place into the game folder. example: <code>C:\KISS\CM3D2</code> 
Please use opengl32.dll according to version game you play. 
# <code>cm3d2_e_317\opengl32.dll</code> for the 64bit version (x64).
# <code>cm3d2_e_317\x86\opengl32.dll</code> for the 32bit version (x86).
<code>SybarisArcEditor</code> is optional if you need to install, copy and then put in game folder. This program will allow you to view and edit .arc files.

----

===Basic Plugin===
1. Download [https://ux.getuploader.com/cm3d2_h/download/58/cm3d2_h_58.zip Basic Plugin] or Sybaris Starter Pack or Sybaris AIO 
This Package contains:
* MaidVoicePitch Plugin
* ExternalSaveData Plugin
* FastFade Plugin
* AddModsSlider Plugin
* ExternalPreset Plugin
* ConsistentWindowPosition Plugin '''(Optional)'''
* EditSceneUndo Plugin '''(Optional)'''
* LogWindow Plugin '''(Optional)'''
* PersonalizedEditSceneSettings Plugin '''(Optional)'''
* SkillCommandShortCut Plugin '''(Optional)'''
* VoiceNormalizer Plugin '''(Optional)'''
2. Copy .dll files in folder <code>Loader</code> and <code>UnityInjector</code> from basic plugin to sybaris in game folder.
# <code>cm3d2_h_58\ReiPatcherレス化プラグイン一式170606\Sybaris\Loader</code> ➡ <code>CM3D2\Sybaris\Loader</code>
# <code>cm3d2_h_58\ReiPatcherレス化プラグイン一式170606\Sybaris\Plugins\Unityinjector</code> ➡ <code>CM3D2\Sybaris\Plugins\UnityInjector</code>
3. Copy files in folder <code>Config</code> to <code>CM3D2\Sybaris\Plugins\UnityInjector\Config</code> in game folder. 
4. For '''optional''' plugins, you can install them by copy .dll files in <code>Sybaris\Loader\オプション</code> and <code>Sybaris\Plugins\UnityInjector\オプション</code> from basic plugin into Sybaris in game folder. 

'''''1st Note:''' '''FastFade Plugin''' will change the display of the game. If you don't need to use the plugin, then shouldn't be installed.'' 
'''''2nd Note:''' Other plugins mostly there is step to installation same as basic plugin. However, for correct let check the readme before installation.''

----

===TranslatePlus Plugin===
'''*TranslationPlus is known to have compatibility issues with v1.49 or newer with translate textures and skill icons. Consider using [[Custom_Maid_3D_2/Technical_Help#YATranslator_Plugin|YATranslator]] or proceed at your own risk. '''
1. Download [https://github.com/zklm/CM3D2.TranslationPlus/releases Translate Plus Plugin] or Sybaris Starter Pack 
2. Copy files below in the translateplus folder to these folders.
# CM3D2.TranslationPlus.Sybaris.Patcher.dll ➡ <code>CM3D2\Sybaris\Loader</code>
# CM3D2.TranslationPlus.Hook ➡ <code>CM3D2\Sybaris\Plugins\Managed</code>
# CM3D2.TranslationPlus.Plugin ➡ <code>CM3D2\Sybaris\Plugins\UnityInjector</code>
3. TranslatePlus Plugin is require a translate data to run with the plugin. you can find translate data in '''Sybaris Starter''' or '''Sybaris AIO''', then put a translate data into <code>Sybaris\Plugins\UnityInjector\Config</code>
# Place translate data from "Assets" folder in <code>Sybaris\Plugins\UnityInjector\Config\Assets</code>.
# Place translate data from "String" folder in <code>Sybaris\Plugins\UnityInjector\Config\Strings</code>.
# Place translate data from "Texture" folder in <code>Sybaris\Plugins\UnityInjector\Config\Texture</code>.

===YATranslator Plugin===
YATranslator is a translation loader. It supports CM3D2 v1.49 and newer, works with ReiPatcher and Sybaris, and replaces TranslationPlus or Unified Translation Loader. The plug-in also fixes many loading errors present in other translation loaders. 
1. Download [https://github.com/denikson/CM3D2.YATranslator/releases YATranslator Plugin] or [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5816208-sybaris-aio-ultimate-english-expansion-1-53-1-beta-suggestions-are-welcome Sybaris AIO] 
2. '''Remove TranslationPlus or Unified Translation Loader''' 
3. Follow the installation guides [https://github.com/denikson/CM3D2.YATranslator/wiki/Installation here] or in the READMEs 
4. YATranslator Plugin is require a translate data to run with the plugin. you can find translate data in '''Sybaris Starter''' or '''Sybaris AIO''', then put a translate data into <code>Sybaris\Plugins\UnityInjector\Config</code>
# Place translate data from "Assets" folder in <code>Sybaris\Plugins\UnityInjector\Config\Assets</code>.
# Place translate data from "String" folder in <code>Sybaris\Plugins\UnityInjector\Config\Strings</code>.
# Place translate data from "Texture" folder in <code>Sybaris\Plugins\UnityInjector\Config\Texture</code>.

'''''1st Note:''' If you have any trouble with incorrect UI, transparent UI, white UI, black screen stuck on Day 1 or night service skill name overlapping, '''remove all previous translations loaders!''' The issues have been fixed in YATranslator, but having older translations loaders (TranslationPlus, UTL) conflict with the new plug-in. '' 
'''''2nd Note:''' It is recommended to get the '''AutoTranslate Plugin''' to enable automatic Google translations. You can find the plug-in on [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5756478-plugin-automatic-google-translate-v1-3-2-2017-10-26 HongFire] and [https://github.com/texel-sensei/CM3D2.AutoTranslate/releases GitHub]''

----

===YASDPlus Plugin===
'''First Step: Prepare File''' 
1. Download [https://mega.nz/#!G8Y3gIwL!6U5x1xWj-QzmP8CULD6OoaxuvbWJhR1SUlcKpx_aMtI Soft-Demosaic Plugin] (Password: byreisen) 
Copy file '''CM3D2.NoMosaic.Plugin.dll''' from the CM3D2.NoMosaic folder to <code>CM3D2\Sybaris\Plugins\UnityInjector</code> 
2. Next Step (If you have Sybaris Starter Pack or Sybaris AIO, skip to step 2.3) 
Download [https://mega.nz/#!Y5hCXThS!jgbR9IFpBgFlT9V1-YEh9FpJK4ajoVweN9GOyTL5wrE Female Uncensor-Menelol(R4)] (Password: 4HF) 
Download [http://ux.getuploader.com/cm3d2_d/download/84/cm3d2_d_84.zip 適当ツールまとめ] 
# Go to folder <code>Girl Uncensor\UnityInjector\config</code> of Female Uncensor-Menelol, find all .png file inside the folder. 
# Import .png files in Female Uncensor-Menelol folder to program '''[CM3D2]tex←→png変換.exe''' in <code>cm3d2_d_84\[CM3D2]適当ツールまとめ</code> then convert .png to .tex, doing all the files until complete. 
# Go to folder <code>CM3D2\Sybaris\GameData</code>, create a new folder "FemaleUncensor" then pull all .tex uncensor files from converts into this folder. 
You can skip this step, If you don't need to male uncensor. but If you need to do the following: 
3. Download [http://ux.getuploader.com/cm3d2_d/download/24/cm3d2_d_24.zip ManTNP] or Sybaris Starter Pack or Sybaris AIO 
Then put male uncensor into <code>CM3D2\Sybaris\GameData</code>

'''Second Step: Installation''' 
1. Download [http://pastebin.com/pTKGk0Ef YASDPlus Plugin] or Sybaris Starter Pack or Sybaris AIO 
2. Copy file '''cm3d2.yasdplus.plugin.cs''' into folder <code>Sybaris\Plugins\UnityInjector\AutoCompile</code>. when opening the game, the game will generate this files below
# cm3d2.yasdplus.plugin.dll in <code>Sybaris\Plugins\UnityInjector</code>
# yasd.ini in <code>Sybaris\Plugins\UnityInjector\Config</code>
When you get the above files, YASDPlus Plugin installation have been completed. 
''Note: You can setting uncensor in the game by opening '''yasd.ini''' file in Notepad. See the setting from [http://motimoti3d.jp/blog-entry-53.html here].'' 
''Note: If male character has cylinder penis, because '''you do not put the male uncensor''' into sybaris. Please see third step in the first step: prepare file.''

==Installing Mod==
[[File:Cm3d2installmod01.jpg|thumb|right|Example installing mods within folder]]
Installation the mod, you can follow the steps below. 
'''For Vanilla''' 
1. Go to game folder create a new folder "Mod" (example: C:\KISS\CM3D2\Mod) 
2. Put the mod files into <code>CM3D2\Mod</code> folder. 

'''For Sybaris''' 
1. Go to <code>CM3D2\Sybaris\GameData</code> in sybaris folder. 
2. Put the mod files into <code>CM3D2\Sybaris\GameData</code> folder. 

''Note: Some mod must be placed in sybaris folder, please check the readme before installing.'' 
''Note: For .mod file should be placed without the folder.''

User:Denikson

2017-11-01T15:16:16Z

Denikson: Created page with "= About denikson = Mainly developer for CM3D2 plug-ins. Some of my creations: * [https://github.com/denikson/CM3D2.MaidFiddler Maid Fiddler] (CM3D2 in-game editor) * [https:..."

= About denikson =

Mainly developer for CM3D2 plug-ins. Some of my creations:

* [https://github.com/denikson/CM3D2.MaidFiddler Maid Fiddler] (CM3D2 in-game editor)
* [https://github.com/denikson/CM3D2.YATranslator YATranslator] (a translation loader for CM3D2)
* Tutorials for ReiPatcher and UnityInjector

== Contact ==

[https://github.com/denikson denikson@GitHub] (my projects)
[http://www.hongfire.com/forum/member/1347954-denikson denikson@HongFire]

Custom Maid 3D2/Technical Help

2017-09-11T20:18:52Z

Denikson:

{{Custom Maid 3D 2}}
=FAQ=
==Running the game==
*'''Q: I keep getting an "(0) Yotogi.Category enum parse error (character not japanese)" error when I run the game and I have tried both AppLocale and NTLEA?'''
: A: You can't use AppLocale to run the x64 version because AppLocale don't support x64 version. but you can use AppLocale to run the x86 version on Windows 7,8 by step below
# Copy files and folders CM3D2x86_Data and CM3D2x86.exe from installation folder into your game folder. (example: C:\KISS\CM3D2\)
# Right-click CM3D2x86.exe and select Run with Japanese locale. (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options.) '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
: A: The best way for solve this problem is set '''window system locate to japanese''' but if you still want to run the x64 version or window 10 without set window system, you can try this [http://www.hongfire.com/forum/showthread.php/444096-KISS-Custom-Maid-3D-2-%28%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%A1%E3%82%A4%E3%83%893D2%29-Discussion-FAQ?p=3706481#post3706481 solution], which is using NTLEA x64.

*'''Q: My game crashes doing in maid creation or doing change skin color and my graphic card is AMD. How to fix this problem?''' 
: A: Maybe this guide is helpful for you [http://www.hongfire.com/forum/showthread.php/445139-AMD-CRASH-FIX-FOR-Radeon-HD-Series AMD CRASH FIX FOR Radeon HD Series] or you can access [http://pastebin.com/t3m1Lg3h this] in case the website blocked.

*'''Q: How do I install the translations?''' 
: A: See [[Custom_Maid_3D_2/Technical_Help#Translate_Plus_Plugin|Translate Plus]] or [[Custom_Maid_3D_2/Technical_Help#YATranslator_Plugin|YATranslator]].

*'''Q: I get this error when running the HF Patch: "... The game is an unsupported version. This patch requires version 1.03...", what can I do?''' 
: A: Install the official 1.03 patch and then run the [[#The HF Patch|Custom Maid 3D 2 HF Patch]] again. There are mirrors to the official patch in the [http://www.hongfire.com/forum/showthread.php/444096 CM3D2 discussion].

*'''Q: I get a "Daily panel" error during gameplay.''' 
: A: Make sure that you have the official 1.03 patch installed (and it is correct version - x86 or x64) and then run the [[#The HF Patch|Custom Maid 3D 2 HF Patch]] again. There are mirrors to the official patch in the [http://www.hongfire.com/forum/showthread.php/444096 CM3D2 discussion].

*'''Q: It keeps telling me that the "game main executable couldn't be found, path maybe invalid and it says that after I try to install the patch. 
: A:

*'''Q: Incorrect Position UI, Transparent UI, White UI, Black screen stuck on Day 1, Night service skill name overlapping after update patch.''' 
: A: Delete Folder "Assets" and "Texture" in <code>Sybaris\UnityInjector\Config</code> and replace them with files download from [http://goo.gl/6CsKNi v1.49 UI translation]. This solve whatever problem you encouter (v1.49 UI translation for v1.52, older version you can find them in HF).
: '''''Note: this trouble often found after KISS update the game, be careful this solution in this specific to your game version.'''''

==Gameplay==
*'''Q: I got this option for my maid to choose between Free and something. What does this mean? ''' 
: A: You are choosing between making your [[Custom_Maid_3D_2/Gameplay/The_Maid_Profile#Maid_Type|Maid Type]]. There are two types of maid is personal (only has sex with you) and free (has sex with the customers). The first earns you less money than the second.

*'''Q: How can I replay VIP scenes?''' 
: A: <del>If you want to play them again, you must keep a save file before play the VIP. (After 100 days in game, VIP events that have been played over the first 99 days in game are again avalable to be played with forever but the same requirements are still applied as per the VIP event.)</del> 
: A: After v1.21 and Plus Pack, you can replay unlocked VIP events in [[Custom_Maid_3D_2/Gameplay#Free_Mode|Free Mode]].

*'''Q: What are red options during sex?''' 
: A: These are '''one-time''' options for the skill. You can use them again next time if you use this skill again.

*'''Q: How do I get more maids? I only have 1-2.''' 
: A: You need to get your club '''out of debt''' first. Also, there is no upper limit on maids, but there is an upper limit on six working maids.

*'''Q: How do I unlock new rooms? ''' 
: A: Increase your [[Custom_Maid_3D_2/Gameplay#Club_Grade|Club Grade]] from cleaning, decorating and eval and other [[Custom_Maid_3D_2/Gameplay#Rooms|Rooms]] require expansion installation. This is possible while still in debt.

*'''Q: After having sex with my maid, I got a notification. Something to do with being close? What does this mean? ''' 
: A: It means you've advanced your [[Custom_Maid_3D_2/Gameplay/The_Maid_Profile#Status|Relationship]] with your maid.

*'''Q: How do I earn CR for pay off the 10m Debt?''' 
: A: You can earn a small amount 50k~100k CR of money by "Dispatch" maids during the daytime, but the most amount of money comes from "Entertain" on nighttime. Entertain can earn 200k~1m CR per night per maid depending on club grade. Both Free Maids and Personal Maids are able to entertain.

*'''Q: It is said that I got "Ring" from the Lovers Trophy but I can't seem to find it... where can I find it?''' 
: A: It's only unlocked by the time you got the "Lovers" Trophy. You still need to buy it from the shop for 10.000.000CR to equip the ring in the arms category.

*'''Q: All of sudden, There is no "Talk to her" option... What am I doing wrong? ''' 
: A: You didn't put either top or bottom clothes for her, which makes her feels too embarrassed to talk to you. Try to put some clothes instead you ecchi-goshujinsama.

*'''Q: I can't seem to make the rental maid to do her VIP event? ''' 
: A: You need to supervise her daily activities to earn her trust until you trigger all the 3 specific events which occurs per-day, the last one will pop-up a dialogue that tells you the VIP event is unlocked. The VIP event only occurs once and is not replayable since she's a rental maid. Explained in [[Custom_Maid_3D_2/Gameplay/VIP_Events#NPC_Maid|NPC Maid VIP]]

==Text Hooking - Visual Novel Reader==
*'''Q: Why can't I get VNR to work with the game?''' 
: A: VNR doesn't work with the x64 version of the game, use the x86 version instead.

*'''Q: I managed to sync VNR to CM3D2 v1.03 but I can't make it translate. The TL box won't come out. What's wrong?''' 
: A: Either enable the VNR built in hooker or rollback; overwrite your current VNR folder.

=Installed Guide=
More information can be found in [http://www.hongfire.com/forum/forum/hentai-lair/hentai-game-discussion/418479 CM3D2 Hongfire] or [https://www.reddit.com/r/cm3d2/comments/6faqro/support_megathread CM3D2 Reddit].
==Installing the Game==
[[File:CM3D2_Installer.png|thumb|Click the highlighted button to install]]
[[File:CM3D2_Insert_disk2.png|thumb|Insert disk 2]]
#Set the '''window system locate to japanese''' or download [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
#Extract <code>cm3d2_1.iso</code> and <code>cm3d2_2.iso</code> '''(DO NOT extract the .mds files)'''
#Mount <code>cm3d2_1.iso</code> with [http://www.disk-tools.com/download/daemon Daemontools Lite] (If you have trouble using other mounting software, Daemontools Lite has been confirmed to work)
#'''DO NOT autorun''', but open the mounted dvd in explorer and click <code>Installer.exe</code> if your computer locale already in japanese, otherwise, right-click <code>Installer.exe</code> and select Run with Japanese locale as an administrator (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options)
#Optional: Change the install folder (default is C:\KISS).
#Click the button <code>インストール</code> to start the CM3D2 setup.
#Confirm that you want to install to that location and wait while the setup until setup asks for disk 2.
#Mount <code>cm3d2_2.iso</code> and click Retry.
#Wait for the setup to finish and close the installer.
 
 
 
 
==Updating Patch==
[[File:Kissupdatepage.JPG|thumb|right|KISS official update webpage]]
[[File:Kissupdate folder.JPG|thumb|right|Extracted .zip files]]
#Set the '''window system locate to japanese''' or download [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
#Download the latest full update that is meant for the version you run (either x86 or x64). For lastes update patch: http://kisskiss.tv/cm3d2/update.php For old update patch: http://kisskiss.tv/cm3d2/oldupdate.php Or visit forum for mirrors update patch: [http://www.hongfire.com/forum/forum/hentai-lair/hentai-game-discussion/418479 CM3D2 discussion].
#Download the updater ver.1.00～1.12 (cm3d2_up_for_1_00-1_12)
#Extract the .zip file and execute the <code>update.exe</code> located inside the extracted folder. (It will auto-detect your installation directory) you can simply execute the <code>update.exe</code> if your computer locale already in japanese, otherwise, right-click <code>update.exe</code> and select ''Run with Japanese locale as an administrator'' (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options).
#Choose <code>適用</code> -> <code>開始</code>, and wait for the patch to be extracted and installed.
#Download the latest updater (example: cm3d2_up148_x86_sub or cm3d2_up148_x64_sub) and repeat ''step 4 and 5'' after downloading the latest updater.
#After update complete, next time you can update the latest patch into your game without update ver.1.00～1.12 again.
Additional screenshots for '''Step 5''' as below:
{| class="wikitable"
|-
| [[File:Kissupdate patch1.JPG|300px|center]] || [[File:Kissupdate patch2.JPG|300px|center]]
|}

'''''1st Note:''' If the patch didn't detect your installation directory and/or somehow the update.exe bugged, you can overwrite the ''GameData'' folder, and you will also need to update the ''update.lst'' file, which is advanced for veteran users.''

'''''2nd Note:''' The '''update.exe''' will not install an already installed patches/DLCs as seen in additional screenshots for Step 5 where the START option is '''''greyed out''''', it follows the ''update.lst'' file, in case you are wondering it is located on your CM3D2 Root directory. (example: ''C:\KISS\CM3D2\'')''

==Installing Sybaris==
===Sybaris FAQ===
*'''Q: What is Sybaris? 
: A: Sybaris is loader that runs plugins other than the official plugins have been installed in the base game.

*'''Q: What is the difference between Sybaris and Reipatcher? 
: A: Both loader have no difference in usability. The only difference is the methods of operation.

*'''Q: Why use Sybaris? 
: A: Sybaris have the advantage better than Reipatcher is: 
# Does not affect the base game, you can go back to vanilla anytime. 
# Updating the game causes less problems.

*'''Q: Sybaris have a disadvantage? 
: A: Sybaris has the following disadvantages: 
# Many plugins for Sybaris are only available in japanese language. 
# Some Reipatcher plugins are incompatible with Sybaris, such as Unified Translation Loader.

*'''Q: Sybaris need to install Reipatcher? 
: A: No

----
===Sybaris===
For an easy installation you can download: [https://mega.nz/#!XFJUQAjL!G2GMTKUt2XGCo94Q3SII5Ki02u1LtMEECyCa9QrEr-g Sybaris Starter Pack 1.52] or [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5816208-sybaris-aio-ultimate-english-expansion-1-52-2-1-beta-suggestions-are-welcome Sybaris AIO Ultimate English Expansion 1.52.2.4 Beta] 
This Package contains:
* Sybaris support v1.52+
* Plugins
* Translator
* Uncensor

1. Download [https://ux.getuploader.com/cm3d2_e/download/317/cm3d2_e_317.zip Sybaris] or Sybaris Starter Pack 
2. Copy '''opengl32.dll''' and '''Sybaris''' folder into the game folder. example: <code>C:\KISS\CM3D2</code> 
Please use opengl32.dll according to version game you play. 
# <code>cm3d2_e_317\opengl32.dll</code> for the 64bit version (x64).
# <code>cm3d2_e_317\x86\opengl32.dll</code> for the 32bit version (x86).
<code>SybarisArcEditor</code> is optional. This program will allow you to view and edit .arc files.

----

===Basic Plugin===
1. Download [https://ux.getuploader.com/cm3d2_h/download/58/cm3d2_h_58.zip Basic Plugin] or Sybaris Starter Pack 
This Package contains:
* MaidVoicePitch Plugin
* ExternalSaveData Plugin
* FastFade Plugin
* AddModsSlider Plugin
* ExternalPreset Plugin
* ConsistentWindowPosition Plugin '''(Optional)'''
* EditSceneUndo Plugin '''(Optional)'''
* LogWindow Plugin '''(Optional)'''
* PersonalizedEditSceneSettings Plugin '''(Optional)'''
* SkillCommandShortCut Plugin '''(Optional)'''
* VoiceNormalizer Plugin '''(Optional)'''
2. Copy .dll files in folder <code>Loader</code> and <code>Plugins\UnityInjector</code> from basic plugin to sybaris in game folder.
# <code>cm3d2_h_58\ReiPatcherレス化プラグイン一式170606\Sybaris\Loader</code> ➡ <code>CM3D2\Sybaris\Loader</code>
# <code>cm3d2_h_58\ReiPatcherレス化プラグイン一式170606\Sybaris\Plugins\Unityinjector</code> ➡ <code>CM3D2\Sybaris\Plugins\UnityInjector</code>
3. Copy files in folder <code>Plugins\UnityInjector\Config</code> to <code>CM3D2\Sybaris\Plugins\UnityInjector\Config</code> in game folder. 
4. For '''optional''' plugins, you can install them by copy .dll files in <code>Sybaris\Loader\オプション</code> and <code>Sybaris\Plugins\UnityInjector\オプション</code> from basic plugin into Sybaris in game folder. 

''Note: '''FastFade Plugin''' will change the display of the game. If you don't need to use the plugin, then shouldn't be installed.''

----

===Translate Plus Plugin===
{{msgbox
|border=#ddd
|background=#ddd
|textcolor=#000
|message='''NOTE:''' TranslationPlus is known to have compatibility issues with CM3D2 1.49 or newer with some translation files (especially textures and skill icons). Consider using [[Custom_Maid_3D_2/Technical_Help#YATranslator_Plugin|YATranslator]] or proceed at your own risk.
}}

1. Download [https://github.com/zklm/CM3D2.TranslationPlus/releases Translate Plus Plugin] or Sybaris Starter Pack 
2. Copy files below in the translate plus folder to these folders.
# CM3D2.TranslationPlus.Sybaris.Patcher.dll ➡ <code>CM3D2\Sybaris\Loader</code>
# CM3D2.TranslationPlus.Hook ➡ <code>CM3D2\Sybaris\Plugins\Managed</code>
# CM3D2.TranslationPlus.Plugin ➡ <code>CM3D2\Sybaris\Plugins\UnityInjector</code>
3. Translate Plus Plugin is require a translate data to run with the plugin. you can find translate data in [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5678372-cm3d2-system-text-translation HF] or [https://mega.nz/#!XFJUQAjL!G2GMTKUt2XGCo94Q3SII5Ki02u1LtMEECyCa9QrEr-g Sybaris Starter Pack], then put a translate file into <code>Sybaris\Plugins\UnityInjector\Config</code> (for system text translate, go to step 2)
# Create a new folder "Assets" and put translate files into <code>Sybaris\Plugins\UnityInjector\Config\Assets</code>.
# Create a new folder "String" and put translate files into <code>Sybaris\Plugins\UnityInjector\Config\Strings</code>.
# Create a new folder "Texture" and put translate files into <code>Sybaris\Plugins\UnityInjector\Config\Texture</code>.

----

===YATranslator Plugin===
YATranslator is a translation loader. It supports CM3D2 1.49 and newer, works with ReiPatcher and Sybaris, and replaces TranslationPlus and the Unified Translation Plugin.

1. Download [https://github.com/denikson/CM3D2.YATranslator/releases YATranslator Plugin] or [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5816208-sybaris-aio-ultimate-english-expansion-1-52-2-1-beta-suggestions-are-welcome Sybaris AIO Ultimate English Expansion 1.52.2.4 Beta] 
2. '''Remove TranslationPlus or the Unified Translation Loader''' 
3. Follow the installation guides included in the READMEs 

====AutoTranslate====
Currently YATranslator a custom-fixed AutoTranslate Plugin to enable automatic Google translations.
You can find the latest version on [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5813782-plugin-yat-yet-another-translator-1-3-0-0-vpvr-subtitles-autotranslate?p=5814818#post5814818 HongFire].
----

===YASDPlus Plugin===
'''First Step: Prepare File''' 
1. Download [https://mega.nz/#!G8Y3gIwL!6U5x1xWj-QzmP8CULD6OoaxuvbWJhR1SUlcKpx_aMtI Soft-Demosaic Plugin] (Password: byreisen) 
Copy file '''CM3D2.NoMosaic.Plugin.dll''' from the CM3D2.NoMosaic folder to <code>CM3D2\Sybaris\Plugins\UnityInjector</code> 
2. Next Step (If you have Sybaris Starter Pack, skip to step 2.3) 
Download [https://mega.nz/#!Y5hCXThS!jgbR9IFpBgFlT9V1-YEh9FpJK4ajoVweN9GOyTL5wrE Female Uncensor-Menelol(R4)] (Password: 4HF) 
Download [http://ux.getuploader.com/cm3d2_d/download/84/cm3d2_d_84.zip 適当ツールまとめ] 
# Go to folder <code>Girl Uncensor\UnityInjector\config</code> of Female Uncensor-Menelol, find all .png file inside the folder. 
# Import .png files in Female Uncensor-Menelol folder to program '''[CM3D2]tex←→png変換.exe''' in <code>cm3d2_d_84\[CM3D2]適当ツールまとめ</code> then convert .png to .tex, doing all the files until complete. 
# Go to folder <code>CM3D2\Sybaris\GameData</code>, create a new folder "FemaleUncensor" then pull all .tex uncensor files from converts into this folder. 
You can skip this step, If you don't need to male uncensor. but If you need to do the following: 
3. Download [http://ux.getuploader.com/cm3d2_d/download/24/cm3d2_d_24.zip ManTNP] or Sybaris Starter Pack 
Then put male uncensor into <code>CM3D2\Sybaris\GameData</code>

'''Second Step: Installation''' 
1. Download [http://pastebin.com/pTKGk0Ef YASDPlus Plugin] or Sybaris Starter Pack 
2. Copy file '''cm3d2.yasdplus.plugin.cs''' into folder <code>Sybaris\Plugins\UnityInjector\AutoCompile</code>. when opening the game, the game will generate this files below
# cm3d2.yasdplus.plugin.dll in <code>Sybaris\Plugins\UnityInjector</code>
# yasd.ini in <code>Sybaris\Plugins\UnityInjector\Config</code>
When you get the above files, YASDPlus Plugin installation have been completed. 
''Note: You can setting uncensor in the game by opening '''yasd.ini''' file in Notepad. See the setting from [http://motimoti3d.jp/blog-entry-53.html here].''

Custom Maid 3D2/Technical Help

2017-09-11T20:08:21Z

Denikson: More info about YATranslator

{{Custom Maid 3D 2}}
=FAQ=
==Running the game==
*'''Q: I keep getting an "(0) Yotogi.Category enum parse error (character not japanese)" error when I run the game and I have tried both AppLocale and NTLEA?'''
: A: You can't use AppLocale to run the x64 version because AppLocale don't support x64 version. but you can use AppLocale to run the x86 version on Windows 7,8 by step below
# Copy files and folders CM3D2x86_Data and CM3D2x86.exe from installation folder into your game folder. (example: C:\KISS\CM3D2\)
# Right-click CM3D2x86.exe and select Run with Japanese locale. (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options.) '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
: A: The best way for solve this problem is set '''window system locate to japanese''' but if you still want to run the x64 version or window 10 without set window system, you can try this [http://www.hongfire.com/forum/showthread.php/444096-KISS-Custom-Maid-3D-2-%28%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%A1%E3%82%A4%E3%83%893D2%29-Discussion-FAQ?p=3706481#post3706481 solution], which is using NTLEA x64.

*'''Q: My game crashes doing in maid creation or doing change skin color and my graphic card is AMD. How to fix this problem?''' 
: A: Maybe this guide is helpful for you [http://www.hongfire.com/forum/showthread.php/445139-AMD-CRASH-FIX-FOR-Radeon-HD-Series AMD CRASH FIX FOR Radeon HD Series] or you can access [http://pastebin.com/t3m1Lg3h this] in case the website blocked.

*'''Q: How do I install the translations?''' 
: A: See [[Custom_Maid_3D_2/Technical_Help#Translate_Plus_Plugin|Translate Plus]] or [[Custom_Maid_3D_2/Technical_Help#YATranslator_Plugin|YATranslator]].

*'''Q: I get this error when running the HF Patch: "... The game is an unsupported version. This patch requires version 1.03...", what can I do?''' 
: A: Install the official 1.03 patch and then run the [[#The HF Patch|Custom Maid 3D 2 HF Patch]] again. There are mirrors to the official patch in the [http://www.hongfire.com/forum/showthread.php/444096 CM3D2 discussion].

*'''Q: I get a "Daily panel" error during gameplay.''' 
: A: Make sure that you have the official 1.03 patch installed (and it is correct version - x86 or x64) and then run the [[#The HF Patch|Custom Maid 3D 2 HF Patch]] again. There are mirrors to the official patch in the [http://www.hongfire.com/forum/showthread.php/444096 CM3D2 discussion].

*'''Q: It keeps telling me that the "game main executable couldn't be found, path maybe invalid and it says that after I try to install the patch. 
: A:

*'''Q: Incorrect Position UI, Transparent UI, White UI, Black screen stuck on Day 1, Night service skill name overlapping after update patch.''' 
: A: Delete Folder "Assets" and "Texture" in <code>Sybaris\UnityInjector\Config</code> and replace them with files download from [http://goo.gl/6CsKNi v1.49 UI translation]. This solve whatever problem you encouter (v1.49 UI translation for v1.52, older version you can find them in HF).
: '''''Note: this trouble often found after KISS update the game, be careful this solution in this specific to your game version.'''''

==Gameplay==
*'''Q: I got this option for my maid to choose between Free and something. What does this mean? ''' 
: A: You are choosing between making your [[Custom_Maid_3D_2/Gameplay/The_Maid_Profile#Maid_Type|Maid Type]]. There are two types of maid is personal (only has sex with you) and free (has sex with the customers). The first earns you less money than the second.

*'''Q: How can I replay VIP scenes?''' 
: A: <del>If you want to play them again, you must keep a save file before play the VIP. (After 100 days in game, VIP events that have been played over the first 99 days in game are again avalable to be played with forever but the same requirements are still applied as per the VIP event.)</del> 
: A: After v1.21 and Plus Pack, you can replay unlocked VIP events in [[Custom_Maid_3D_2/Gameplay#Free_Mode|Free Mode]].

*'''Q: What are red options during sex?''' 
: A: These are '''one-time''' options for the skill. You can use them again next time if you use this skill again.

*'''Q: How do I get more maids? I only have 1-2.''' 
: A: You need to get your club '''out of debt''' first. Also, there is no upper limit on maids, but there is an upper limit on six working maids.

*'''Q: How do I unlock new rooms? ''' 
: A: Increase your [[Custom_Maid_3D_2/Gameplay#Club_Grade|Club Grade]] from cleaning, decorating and eval and other [[Custom_Maid_3D_2/Gameplay#Rooms|Rooms]] require expansion installation. This is possible while still in debt.

*'''Q: After having sex with my maid, I got a notification. Something to do with being close? What does this mean? ''' 
: A: It means you've advanced your [[Custom_Maid_3D_2/Gameplay/The_Maid_Profile#Status|Relationship]] with your maid.

*'''Q: How do I earn CR for pay off the 10m Debt?''' 
: A: You can earn a small amount 50k~100k CR of money by "Dispatch" maids during the daytime, but the most amount of money comes from "Entertain" on nighttime. Entertain can earn 200k~1m CR per night per maid depending on club grade. Both Free Maids and Personal Maids are able to entertain.

*'''Q: It is said that I got "Ring" from the Lovers Trophy but I can't seem to find it... where can I find it?''' 
: A: It's only unlocked by the time you got the "Lovers" Trophy. You still need to buy it from the shop for 10.000.000CR to equip the ring in the arms category.

*'''Q: All of sudden, There is no "Talk to her" option... What am I doing wrong? ''' 
: A: You didn't put either top or bottom clothes for her, which makes her feels too embarrassed to talk to you. Try to put some clothes instead you ecchi-goshujinsama.

*'''Q: I can't seem to make the rental maid to do her VIP event? ''' 
: A: You need to supervise her daily activities to earn her trust until you trigger all the 3 specific events which occurs per-day, the last one will pop-up a dialogue that tells you the VIP event is unlocked. The VIP event only occurs once and is not replayable since she's a rental maid. Explained in [[Custom_Maid_3D_2/Gameplay/VIP_Events#NPC_Maid|NPC Maid VIP]]

==Text Hooking - Visual Novel Reader==
*'''Q: Why can't I get VNR to work with the game?''' 
: A: VNR doesn't work with the x64 version of the game, use the x86 version instead.

*'''Q: I managed to sync VNR to CM3D2 v1.03 but I can't make it translate. The TL box won't come out. What's wrong?''' 
: A: Either enable the VNR built in hooker or rollback; overwrite your current VNR folder.

=Installed Guide=
More information can be found in [http://www.hongfire.com/forum/forum/hentai-lair/hentai-game-discussion/418479 CM3D2 Hongfire] or [https://www.reddit.com/r/cm3d2/comments/6faqro/support_megathread CM3D2 Reddit].
==Installing the Game==
[[File:CM3D2_Installer.png|thumb|Click the highlighted button to install]]
[[File:CM3D2_Insert_disk2.png|thumb|Insert disk 2]]
#Set the '''window system locate to japanese''' or download [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
#Extract <code>cm3d2_1.iso</code> and <code>cm3d2_2.iso</code> '''(DO NOT extract the .mds files)'''
#Mount <code>cm3d2_1.iso</code> with [http://www.disk-tools.com/download/daemon Daemontools Lite] (If you have trouble using other mounting software, Daemontools Lite has been confirmed to work)
#'''DO NOT autorun''', but open the mounted dvd in explorer and click <code>Installer.exe</code> if your computer locale already in japanese, otherwise, right-click <code>Installer.exe</code> and select Run with Japanese locale as an administrator (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options)
#Optional: Change the install folder (default is C:\KISS).
#Click the button <code>インストール</code> to start the CM3D2 setup.
#Confirm that you want to install to that location and wait while the setup until setup asks for disk 2.
#Mount <code>cm3d2_2.iso</code> and click Retry.
#Wait for the setup to finish and close the installer.
 
 
 
 
==Updating Patch==
[[File:Kissupdatepage.JPG|thumb|right|KISS official update webpage]]
[[File:Kissupdate folder.JPG|thumb|right|Extracted .zip files]]
#Set the '''window system locate to japanese''' or download [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] '''''Note: HF pAppLoc doesn't work with Windows 10 or x64 version.'''''
#Download the latest full update that is meant for the version you run (either x86 or x64). For lastes update patch: http://kisskiss.tv/cm3d2/update.php For old update patch: http://kisskiss.tv/cm3d2/oldupdate.php Or visit forum for mirrors update patch: [http://www.hongfire.com/forum/forum/hentai-lair/hentai-game-discussion/418479 CM3D2 discussion].
#Download the updater ver.1.00～1.12 (cm3d2_up_for_1_00-1_12)
#Extract the .zip file and execute the <code>update.exe</code> located inside the extracted folder. (It will auto-detect your installation directory) you can simply execute the <code>update.exe</code> if your computer locale already in japanese, otherwise, right-click <code>update.exe</code> and select ''Run with Japanese locale as an administrator'' (you need [http://www.hongfire.com/forum/showthread.php/328830 HF pApploc] for the right-click options).
#Choose <code>適用</code> -> <code>開始</code>, and wait for the patch to be extracted and installed.
#Download the latest updater (example: cm3d2_up148_x86_sub or cm3d2_up148_x64_sub) and repeat ''step 4 and 5'' after downloading the latest updater.
#After update complete, next time you can update the latest patch into your game without update ver.1.00～1.12 again.
Additional screenshots for '''Step 5''' as below:
{| class="wikitable"
|-
| [[File:Kissupdate patch1.JPG|300px|center]] || [[File:Kissupdate patch2.JPG|300px|center]]
|}

'''''1st Note:''' If the patch didn't detect your installation directory and/or somehow the update.exe bugged, you can overwrite the ''GameData'' folder, and you will also need to update the ''update.lst'' file, which is advanced for veteran users.''

'''''2nd Note:''' The '''update.exe''' will not install an already installed patches/DLCs as seen in additional screenshots for Step 5 where the START option is '''''greyed out''''', it follows the ''update.lst'' file, in case you are wondering it is located on your CM3D2 Root directory. (example: ''C:\KISS\CM3D2\'')''

==Installing Sybaris==
===Sybaris FAQ===
*'''Q: What is Sybaris? 
: A: Sybaris is loader that runs plugins other than the official plugins have been installed in the base game.

*'''Q: What is the difference between Sybaris and Reipatcher? 
: A: Both loader have no difference in usability. The only difference is the methods of operation.

*'''Q: Why use Sybaris? 
: A: Sybaris have the advantage better than Reipatcher is: 
# Does not affect the base game, you can go back to vanilla anytime. 
# Updating the game causes less problems.

*'''Q: Sybaris have a disadvantage? 
: A: Sybaris has the following disadvantages: 
# Many plugins for Sybaris are only available in japanese language. 
# Some Reipatcher plugins are incompatible with Sybaris, such as Unified Translation Loader.

*'''Q: Sybaris need to install Reipatcher? 
: A: No

----
===Sybaris===
For an easy installation you can download: [https://mega.nz/#!XFJUQAjL!G2GMTKUt2XGCo94Q3SII5Ki02u1LtMEECyCa9QrEr-g Sybaris Starter Pack 1.52] or [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5816208-sybaris-aio-ultimate-english-expansion-1-52-2-1-beta-suggestions-are-welcome Sybaris AIO Ultimate English Expansion 1.52.2.4 Beta] 
This Package contains:
* Sybaris support v1.52+
* Plugins
* Translator
* Uncensor

1. Download [https://ux.getuploader.com/cm3d2_e/download/317/cm3d2_e_317.zip Sybaris] or Sybaris Starter Pack 
2. Copy '''opengl32.dll''' and '''Sybaris''' folder into the game folder. example: <code>C:\KISS\CM3D2</code> 
Please use opengl32.dll according to version game you play. 
# <code>cm3d2_e_317\opengl32.dll</code> for the 64bit version (x64).
# <code>cm3d2_e_317\x86\opengl32.dll</code> for the 32bit version (x86).
<code>SybarisArcEditor</code> is optional. This program will allow you to view and edit .arc files.

----

===Basic Plugin===
1. Download [https://ux.getuploader.com/cm3d2_h/download/58/cm3d2_h_58.zip Basic Plugin] or Sybaris Starter Pack 
This Package contains:
* MaidVoicePitch Plugin
* ExternalSaveData Plugin
* FastFade Plugin
* AddModsSlider Plugin
* ExternalPreset Plugin
* ConsistentWindowPosition Plugin '''(Optional)'''
* EditSceneUndo Plugin '''(Optional)'''
* LogWindow Plugin '''(Optional)'''
* PersonalizedEditSceneSettings Plugin '''(Optional)'''
* SkillCommandShortCut Plugin '''(Optional)'''
* VoiceNormalizer Plugin '''(Optional)'''
2. Copy .dll files in folder <code>Loader</code> and <code>Plugins\UnityInjector</code> from basic plugin to sybaris in game folder.
# <code>cm3d2_h_58\ReiPatcherレス化プラグイン一式170606\Sybaris\Loader</code> ➡ <code>CM3D2\Sybaris\Loader</code>
# <code>cm3d2_h_58\ReiPatcherレス化プラグイン一式170606\Sybaris\Plugins\Unityinjector</code> ➡ <code>CM3D2\Sybaris\Plugins\UnityInjector</code>
3. Copy files in folder <code>Plugins\UnityInjector\Config</code> to <code>CM3D2\Sybaris\Plugins\UnityInjector\Config</code> in game folder. 
4. For '''optional''' plugins, you can install them by copy .dll files in <code>Sybaris\Loader\オプション</code> and <code>Sybaris\Plugins\UnityInjector\オプション</code> from basic plugin into Sybaris in game folder. 

''Note: '''FastFade Plugin''' will change the display of the game. If you don't need to use the plugin, then shouldn't be installed.''

----

===Translate Plus Plugin===
{{msgbox
|border=#ddd
|background=#ddd
|textcolor=#000
|message='''NOTE:''' TranslationPlus is known not to be directly compatible with CM3D2 1.49 or newer without editing the translation files. Consider using [[Custom_Maid_3D_2/Technical_Help#YATranslator_Plugin|YATranslator]] or proceed at your own risk.
}}

1. Download [https://github.com/zklm/CM3D2.TranslationPlus/releases Translate Plus Plugin] or Sybaris Starter Pack 
2. Copy files below in the translate plus folder to these folders.
# CM3D2.TranslationPlus.Sybaris.Patcher.dll ➡ <code>CM3D2\Sybaris\Loader</code>
# CM3D2.TranslationPlus.Hook ➡ <code>CM3D2\Sybaris\Plugins\Managed</code>
# CM3D2.TranslationPlus.Plugin ➡ <code>CM3D2\Sybaris\Plugins\UnityInjector</code>
3. Translate Plus Plugin is require a translate data to run with the plugin. you can find translate data in [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5678372-cm3d2-system-text-translation HF] or [https://mega.nz/#!XFJUQAjL!G2GMTKUt2XGCo94Q3SII5Ki02u1LtMEECyCa9QrEr-g Sybaris Starter Pack], then put a translate file into <code>Sybaris\Plugins\UnityInjector\Config</code> (for system text translate, go to step 2)
# Create a new folder "Assets" and put translate files into <code>Sybaris\Plugins\UnityInjector\Config\Assets</code>.
# Create a new folder "String" and put translate files into <code>Sybaris\Plugins\UnityInjector\Config\Strings</code>.
# Create a new folder "Texture" and put translate files into <code>Sybaris\Plugins\UnityInjector\Config\Texture</code>.

----

===YATranslator Plugin===
YATranslator is a translation loader. It supports CM3D2 1.49 and newer, works with ReiPatcher and Sybaris, and replaces TranslationPlus and the Unified Translation Plugin.

1. Download [https://github.com/denikson/CM3D2.YATranslator/releases YATranslator Plugin] or [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5816208-sybaris-aio-ultimate-english-expansion-1-52-2-1-beta-suggestions-are-welcome Sybaris AIO Ultimate English Expansion 1.52.2.4 Beta] 
2. '''Remove TranslationPlus or the Unified Translation Loader''' 
3. Follow the installation guides included in the READMEs 

====AutoTranslate====
Currently YATranslator a custom-fixed AutoTranslate Plugin to enable automatic Google translations.
You can find the latest version on [http://www.hongfire.com/forum/forum/hentai-lair/hf-modding-translation/custom-maid-3d-2-mods/5813782-plugin-yat-yet-another-translator-1-3-0-0-vpvr-subtitles-autotranslate?p=5814818#post5814818 HongFire].
----

===YASDPlus Plugin===
'''First Step: Prepare File''' 
1. Download [https://mega.nz/#!G8Y3gIwL!6U5x1xWj-QzmP8CULD6OoaxuvbWJhR1SUlcKpx_aMtI Soft-Demosaic Plugin] (Password: byreisen) 
Copy file '''CM3D2.NoMosaic.Plugin.dll''' from the CM3D2.NoMosaic folder to <code>CM3D2\Sybaris\Plugins\UnityInjector</code> 
2. Next Step (If you have Sybaris Starter Pack, skip to step 2.3) 
Download [https://mega.nz/#!Y5hCXThS!jgbR9IFpBgFlT9V1-YEh9FpJK4ajoVweN9GOyTL5wrE Female Uncensor-Menelol(R4)] (Password: 4HF) 
Download [http://ux.getuploader.com/cm3d2_d/download/84/cm3d2_d_84.zip 適当ツールまとめ] 
# Go to folder <code>Girl Uncensor\UnityInjector\config</code> of Female Uncensor-Menelol, find all .png file inside the folder. 
# Import .png files in Female Uncensor-Menelol folder to program '''[CM3D2]tex←→png変換.exe''' in <code>cm3d2_d_84\[CM3D2]適当ツールまとめ</code> then convert .png to .tex, doing all the files until complete. 
# Go to folder <code>CM3D2\Sybaris\GameData</code>, create a new folder "FemaleUncensor" then pull all .tex uncensor files from converts into this folder. 
You can skip this step, If you don't need to male uncensor. but If you need to do the following: 
3. Download [http://ux.getuploader.com/cm3d2_d/download/24/cm3d2_d_24.zip ManTNP] or Sybaris Starter Pack 
Then put male uncensor into <code>CM3D2\Sybaris\GameData</code>

'''Second Step: Installation''' 
1. Download [http://pastebin.com/pTKGk0Ef YASDPlus Plugin] or Sybaris Starter Pack 
2. Copy file '''cm3d2.yasdplus.plugin.cs''' into folder <code>Sybaris\Plugins\UnityInjector\AutoCompile</code>. when opening the game, the game will generate this files below
# cm3d2.yasdplus.plugin.dll in <code>Sybaris\Plugins\UnityInjector</code>
# yasd.ini in <code>Sybaris\Plugins\UnityInjector\Config</code>
When you get the above files, YASDPlus Plugin installation have been completed. 
''Note: You can setting uncensor in the game by opening '''yasd.ini''' file in Notepad. See the setting from [http://motimoti3d.jp/blog-entry-53.html here].''

Custom Maid 3D2/Modding/ReiPatcher

2016-01-03T11:06:02Z

Denikson: Added links to an up-to-date guide

Custom Maid 3D2/Modding/Plugins

2016-01-03T11:05:03Z

Denikson: Added links to an up-to-date guide

{{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.
'''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. 
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. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
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. 
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. 

Here are the main steps in using ReiPatcherPlus:

'''1. Acquiring the type definitions''' 
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''' 
ReiPatcherPlus provides an extension to Mono.Cecil: <code>TypeDefinition.GetMethod(string name)</code> which searches for the first method with the given name. 
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''' 
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. 
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. 
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. 
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. 
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). 
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 <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> If target has a return type: <2.2> = <code>out <return type></code> Otherwise: <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. '''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. 
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.

Template:Nav/Custom Maid 3D2

2015-09-27T00:00:54Z

Denikson: Added a link to ReiPatch guide

* '''[[Custom Maid 3D 2/Technical Help|FAQ & Technical Help]]'''

* '''[[Custom Maid 3D 2/Gameplay|Gameplay]]'''
** [[Custom Maid 3D 2/Gameplay/The Maid Profile|The Maid Profile]]
** [[Custom Maid 3D 2/Gameplay/Schedule|Schedule]]
** [[Custom Maid 3D 2/Gameplay/Maid_Classes|Maid Classes]]
** [[Custom Maid 3D 2/Gameplay/H_Guide|H Guide]]
** [[Custom Maid 3D 2/Gameplay/Skills|Skills]]
** [[Custom Maid 3D 2/Gameplay/VIP_Events|VIP Events]]
** [[Custom Maid 3D 2/Gameplay/Trophy|Trophy]]

* '''[[Custom Maid 3D 2/Modding|Modding]]'''
** [[Custom Maid 3D 2/Modding/ReiPatcher|Patching 101: How to ReiPatch for dummies]]
** [[Custom Maid 3D 2/Modding/Plugins|Writing plug-ins with ReiPatcher and UnityInjector]]

* '''[[Custom Maid 3D 2/Version History|Version History]]'''

Custom Maid 3D2/Modding/ReiPatcher

2015-09-27T00:00:23Z

Denikson: Added new page: how to use ReiPatcher

{{Custom Maid 3D 2}}

[http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703144#post3703144 ReiPatcher] is an awesome tool made by Hongfire user [http://www.hongfire.com/forum/member.php/1283907-usagirei usagirei]. ReiPatcher allows you to apply all kinds of modifications to a game that is made with Unity: you can change how game behaves; you can translate the game into another language; you can edit sounds, textures, models and other in-game assets while the game is running. All in all, the possibilities are limitless!

If somebody linked you to this page, it means you're one of hundreds of people who cannot really understand how to use this neat tool. On the other hand, if you stumbled upon the page yourself, you most likely are seeking for an easy-to-understand tutorial on how to set up and use ReiPatcher. Whichever it might be, '''you came to the right place'''. By reading this small tutorial you will become a professional ReiPatcher'er(er?) in no time!

What are we waiting for? Let the patching begin!

== Grabbing the tools and getting it organized ==
Before we can start patching, we need ReiPatcher downloaded!

Head to [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703144#post3703144 ReiPatcher] and grab the tool! Of course, remember to thank Rei-sama for his hard work by giving him some reputation '''[http://www.hongfire.com/forum/reputation.php?do=addreputation&p=3703144 here]''' (which is one of the many reasons you should join the greate Hongfire community!).

After you have the archive downloaded, extract it to some folder. If you are asked to enter a password, it is most likely <code>byreisen</code> (if it's not, check the maid thread).

After you have extracted everything, you'll find '''at least''' the following files:
{| class="wikitable"
|-
! Filename !! Purpose and some other information
|-
| ExIni.dll || Used by ReiPatcher and the majority of user-created plug-ins. Responsible for creating, editing and saving configuration files.
|-
| ExIni.pdb and ExIni.xml || Mainly used by developers to debug and have a documentation of the ExIni library. If you are not a developer, you don't really need these.
|-
| Mono.Cecil.dll and other DLLs starting with Mono.Cecil || The most important tool of ReiPatcher that is responsible for patching the game.
|-
| ReiPatcher.exe || The executable you are going to run every time you want (or need) to patch a game.
|-
| ReiPatcher.pdb and ReiPatcher.xml || Just as for ExIni.pdb and .xml, they are mainly intended for the developers. You don't really need them unless you are a developer. It is, however, advised that you to keep ReiPatcher.pdb, as it will make it easier to read possible errors.
|}

Now move these files to some directory of your preference. The main point is that all the files stay together. The best place is perhaps the same directory where your games are located. Simply create a folder called ReiPatcher there and put the extracted files in it.

There you go! Now let us test whether ReiPatcher works! Simply hold <code>Shift</code> and rihgt-click on the empty space in ReiPatcher folder. From the context menu that has just appeared select <code>Open command window here</code>. A command prompt should now open. The cursor (_) should be next to the ReiPatcher's directory. Write <code>ReiPatcher.exe</code> and hit <code>Enter</code>. If you copied (or moved) everything correctly, you'll get (almost similar) prompt:
<code>
ReiPatcher 0.9.0.8
.NET Assembly Patcher - Powered by Mono.Cecil
Copyright © Usagirei 2015
GIT master [aac43ce754149cbde635f4ef6d5b164aa796fba1]
==============================================================
Switch Usage:
-fc <Config> Force creation of new configuration file
-c <Config> Use or create of configuration file
-w Waits for user input after patching
-r Reloads latest Assembly backup

Exit Codes:
0 Success
1 NoPatchesApplied
-3 InternalException
-2 FileNotFound
-1 DirectoryNotFound
</code>

You are all set! Now onto creating a game configuration!

== Creating game configuration ==
Before patches can be applied, we need to create a configuration file that tells ReiPatcher where the game files are and where to find the patches to apply.

If the game is officially supported by Hongfire community, you'll most likely find ready game configurations online. Most likely they are available on [http://www.hongfire.com/forum/showthread.php/444101-%28KISS%29-Custom-Maid-3D-2?p=3703144#post3703144 ReiPatcher's original thread].

If, however you are in need to create a new configuration from scratch, simply open the console window in ReiPatcher's directory (by holding <code>Shift</code>, right-clicking on the empty space in the folder and selecting <code>Open command window here</code>) and type the following in the opened console window:

<code>
ReiPatcher.exe -fc <NAME>
</code>
where <NAME> is the name of the configuration (you're pretty much free to choose what it shall be).

Whichever way you choose to obtain the configuration file, it should be put in the same folder as ReiPatcher.exe. That is not necessary, of course, but it will be A LOT easier to reference the files when patching through the command window.

Now that you have the configuration file, let us examine it. Grab your favourite text editor of your choice (which should obviously be Notepad++, right? RIGHT?!) and open the configuration file you downloaded or created. Within you should see a bunch of (probably weird) syntax. Here's a quick agenda for you to remind/teach how to read .INI files:
* Lines starting with <code>;</code> are called comments. They are ignored by ExIni (for the exception the ones starting with <code>@</code>. They are called environment variables and mostly used to load and store path information (which may change depending on the computer and game).
* Lines of the form <code>Variable=Value</code> are variables that are used by ReiPatcher or other patchers. In ReiPatcher they are primarily used to store paths to different folders.
* Lines of the form <code>[Name]</code> are called groups. They -- obviously -- group multiple variables together. All variables between two group names (or between a group name and the end of the file) belong to one group. The name of the grouped variables is defined in the upper group name declaration.

After this crash-course into ExIni, here are some of the most important variables used by ReiPatcher. You'll most likely want to edit those to your liking:
{| class="wikitable"
|-
! Variable name !! Description
|-
| <code>PatchesDir</code> || Path to the patcher DLLs for this game configuration. Can be either absolute (ie. starting with drive letter) or relative (only folder name(s)). Depending on the game you'll want this to be <code><GAME NAME>_Patches</code>. Therefore you'll need to put plug-ins' patch DLLs in the folder called <code><GAME NAME>_Patches</code> that you must create in ReiPatcher folder.
|-
| <code>AssembliesDir</code> || Path to game assemblies that are to be patched. If you downloaded the configuration from the Internet, you'll most likely want to leave this as is. In other cases it is most likely of the form <code><GAME DIRECTORY>\<GAME NAME>_Data\Managed</code> (which, of course, might change depending on the game.
|-
| <code>Executable</code> || Set this to the path to the game executable, if you want ReiPatcher to launch the game after patching is complete. Leave empty if you don't.
|-
| <code>Arguments</code> || Additional arguments to use when launching the game.
|-
| <code>Directory</code> || Root of the game (the one that contains the game's executable).
|}

Any additional values might vary depending on the patches and tools you use, which is why we shall not go deeper into the topic.

After you have added your game configuration (and created the folder for patches as specified in the game configuration file), you can test/run it with ReiPatcher. Simply open the console window in ReiPatcher directory and type:

<code>
ReiPatcher.exe -c <NAME>.ini
</code>
where <NAME> is the name of your configuration file. If everything went well (and your folder containing the patches is empty), you should see the following output:

<code>
ReiPatcher 0.9.0.8
.NET Assembly Patcher - Powered by Mono.Cecil
Copyright © Usagirei 2015
GIT master [aac43ce754149cbde635f4ef6d5b164aa796fba1]
==============================================================================
Loading configuration file: 'CM3D2x64.ini'
============================== Loading Patchers ==============================
Loading Patchers
No Patches Found
================================= Pre-Patch ==================================
============================= Loading Assemblies =============================
================================== Patching ==================================
================================= Post-Patch =================================
================================== Finished ==================================
</code>
Since we had no patches in the folder that we specified in the configuration file, no patches were applied! Let us now proceed to actually downloading installing the patches and actually applying them!

== Installing the patches ==
We're almost there! The only step left is to apply the patches!

Download the plug-ins of your choice and extract the downloaded archives.

Unfortunately, there are no strict rules on how to name either the folders in the archive or how to call the DLLs themselves. Therefore, '''always consult the README included with the plug-ins first!''' That being said, the most common way to divide the DLLs and other files in the plug-in is to divide them into three folders: <code>Manged</code>, <code>ReiPatcher</code> and <code>UnityInjector</code>. If that's the case, all you need to do is:
* Copy the contents of <code>Manged</code> to <code><Game directory>\<GAME>_Data\Managed</code>, where <code><Game directory></code> is the path to the game root (the directory where the game's extecutable is) and <code><GAME></code> is the game code with the possible addition of some other codes, like CPU architecture.
* Copy the contents of <code>ReiPatcher</code> to the patches folder specified in the game's configuration file.
* Copy the contents of <code>UnityInjector</code> to <code><Game directory>\UnityInjector</code> if the folder does not exist yet, create it.

Other times the developer doesn't bother to separate the DLLs into differenet folders. In these cases they most likely specify the purpose of the DLL by their name. Again, there are not strict rules on this either, but it seems that most developers name their plug-ins in the following manner:

<code>
<GAME>.<Plugin name>.<Type>
</code>
In that case <code><GAME></code> is the game code, <code><Plugin name></code> is the name of the plug-in and <code><Type></code> is the type of the DLL. Here are the most common type names and where to place the DLLs with that type:
* <code>Hook</code> (also sometimes blank or <code>Core</code>): put to <code><Game directory>\<GAME>_Data\Managed</code>, where <code><Game directory></code> is the path to the game root (the directory where the game's extecutable is) and <code><GAME></code> is the game code with the possible addition of some other codes, like CPU architecture.
* <code>Patch</code> (or <code>Patcher</code>): Put to the patches folder specified in the game's configuration file.
* <code>Plugin</code>: Put to <code><Game directory>\UnityInjector</code> if the folder does not exist yet, create it.

=== The moment of truth ===

When you have put everything into place, it is time to run ReiPatcher. Open command window in ReiPatcher folder and type:

<code>
ReiPatcher.exe -c <NAME>.ini
</code>
where <NAME> is the name of your configuration file. If everything went well, you'll see the green text that specifies that every patch has been applied successfully. Horaay! Now you can enjoy your game with the new plug-ins!

== Overview ==
We briefly discussed how to install ReiPatcher, how to create own game configurations and how to install and apply patches. Much information has been omitted for the sake of simplicity, but this tutorial serves as a nice crash-course into the world of Unity Engine patching.

I hope that you, dear reader, have grasped the most essential knowledge of being a ReiPatcher'er(er?)(er??). Whenever you have issues with patching the game, always consult this tutorial or the original ReiPatcher thread (unless you will get linked back to this tutorial, that is -- in which case you have missed something very obvious).

Custom Maid 3D2/Modding/Plugins

2015-08-12T18:30:44Z

Denikson: /* Summary */

{{Custom Maid 3D 2}}

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.
'''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. 
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. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
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. 
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. 

Here are the main steps in using ReiPatcherPlus:

'''1. Acquiring the type definitions''' 
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''' 
ReiPatcherPlus provides an extension to Mono.Cecil: <code>TypeDefinition.GetMethod(string name)</code> which searches for the first method with the given name. 
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''' 
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. 
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. 
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. 
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. 
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). 
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 <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> If target has a return type: <2.2> = <code>out <return type></code> Otherwise: <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. '''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. 
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.

Custom Maid 3D2/Modding/Plugins

2015-08-12T16:21:25Z

Denikson: /* Injecting the methods */

{{Custom Maid 3D 2}}

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.
'''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. 
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. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
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. 
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. 

Here are the main steps in using ReiPatcherPlus:

'''1. Acquiring the type definitions''' 
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''' 
ReiPatcherPlus provides an extension to Mono.Cecil: <code>TypeDefinition.GetMethod(string name)</code> which searches for the first method with the given name. 
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''' 
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. 
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. 
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. 
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>

== 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. 
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). 
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 <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> If target has a return type: <2.2> = <code>out <return type></code> Otherwise: <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. '''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. 
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.

Custom Maid 3D2/Modding/Plugins

2015-08-12T16:20:26Z

Denikson:

{{Custom Maid 3D 2}}

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.
'''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. 
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. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
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. 
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. 

Here are the main steps in using ReiPatcherPlus:

'''1. Acquiring the type definitions''' 
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''' 
ReiPatcherPlus provides an extension to Mono.Cecil: <code>TypeDefinition.GetMethod(string name)</code> which searches for the first method with the given name. 
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''' 
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. 
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. 
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. 
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>

== 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. 
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). 
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 <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> If target has a return type: <2.2> = <code>out <return type></code> Otherwise: <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. '''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. 
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 to insert 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.

Custom Maid 3D2/Modding/Plugins

2015-08-12T15:59:40Z

Denikson: Fixed some typos, updated documentation for ReiPatcherPlus

{{Custom Maid 3D 2}}

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.
'''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. 
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. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
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. 
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. 

Here are the main steps in using ReiPatcherPlus:

'''1. Acquiring the type definitions''' 
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''' 
ReiPatcherPlus provides an extension to Mono.Cecil: <code>TypeDefinition.GetMethod(string name)</code> which searches for the first method with the given name. 
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''' 
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. 
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. 
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. 
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>

== 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. 
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). 
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 <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> If target has a return type: <2.2> = <code>out <return type></code> Otherwise: <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. '''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, InjectDirection dir);
void AttachMethod(MethodDefinition target,
MethodDefinition hook,
int codeOffset,
MethodFeatures features,
InjectDirection dir,
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.
|-
| <code>dir</code> || Direction in which to inject the hook method. If <code>InjectDirection.Before</code>, will inject the hook method before the specified instruction. If <code>InjectDirection.After</code>, the injection will commence after the provided instruction. '''Default:''' <code>InjectDirection.Before</code>.
|}

Elementary, these two methods will automatically inject the needed CIL instructions depending on the chosen hook/target method. 
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.

==== 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.

Custom Maid 3D2/Modding/Plugins

2015-08-07T16:01:27Z

Denikson: /* Patching phase */

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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. 
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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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. 
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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T15:57:39Z

Denikson: /* Manipulating INI files */

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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. 
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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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. 
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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T15:52:39Z

Denikson: /* Writing the plug-in DLL */ Altered the name of the section to find it easily

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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. 
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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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. 
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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T15:51:31Z

Denikson: /* Writing the plug-in DLL */ Fixed the name of MonoBehaviour class

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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. 
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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T09:42:00Z

Denikson: /* Pre-patching checks */ Added a minor explanation.

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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. 
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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T09:40:02Z

Denikson: /* Pre-patching phase */ Rephrased a sentence concerning the number of RequestAssembly calls

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T09:30:48Z

Denikson:

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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.
The number of requests is the same as the number of assemblies we want to patch.

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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-07T08:17:44Z

Denikson: Added more decompilers, changed directory info for ReiPatcher

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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 impossible to manipulate, which is due to the code being mostly unmanaged.
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.

==== 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>CM3D2x84_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.

== Designing the plug-in ==
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.

=== 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 ====
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, 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. 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 programming choice, 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.
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.
The number of requests is the same as the number of assemblies we want to patch.

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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-06T23:30:38Z

Denikson: Mentioned the need of using this.

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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 impossible to manipulate, which is due to the code being mostly unmanaged.
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.

==== 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>CM3D2x84_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 ===
* [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] and [http://code.google.com/p/cecilstudio Cecil Studio]. In this tutorial we will be using ILSpy.

== Designing the plug-in ==
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 || Game's main directory
|-
| <code>ExIni.dll</code> || Contains classes and methods for manipulating .ini files. || Game's main directory
|-
| <code>Mono.Cecil.dll</code> || Contains tools for manipulating CIL assemblies (reading classes, methods, etc) || Game's main directory
|-
| <code>Mono.Cecil.*.dll</code> || Miscellaneous classes and tools to extend Mono.Cecil's functionality. || Game's main directory
|-
| <code>ReiPatcherPlus.dll</code> (optional) || Extends the functionality of some classes found in <code>ReiPatcher.exe</code> || Game's main 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.

=== 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 ====
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, 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. 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 programming choice, 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.
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.
The number of requests is the same as the number of assemblies we want to patch.

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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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.
|-
| <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".
|}

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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Template:Nav/Custom Maid 3D2

2015-08-06T23:27:50Z

Denikson: Added link to Modding/Plugins

* '''[[Custom Maid 3D 2/Gameplay|Gameplay]]'''
** [[Custom Maid 3D 2/Gameplay/H_Guide|H Guide]]
** [[Custom Maid 3D 2/Gameplay/Skills|Skills]]
** [[Custom Maid 3D 2/Gameplay/Maid_Classes|Maid Classes]]
** [[Custom Maid 3D 2/Gameplay/Characteristics|Characteristics]]
** [[Custom Maid 3D 2/Gameplay/VIP_Events|VIP Events]]

* '''[[Custom Maid 3D 2/Technical Help|Technical Help]]'''

* '''[[Custom Maid 3D 2/Modding|Modding]]'''
** [[Custom Maid 3D 2/Modding/Plugins|Writing plug-ins with ReiPatcher and UnityInjector]]

* '''[[Custom Maid 3D 2/Version History|Version History]]'''

Custom Maid 3D2/Modding/Plugins

2015-08-06T23:26:23Z

Denikson:

{{Custom Maid 3D 2}}

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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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 impossible to manipulate, which is due to the code being mostly unmanaged.
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.

==== 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>CM3D2x84_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 ===
* [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] and [http://code.google.com/p/cecilstudio Cecil Studio]. In this tutorial we will be using ILSpy.

== Designing the plug-in ==
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 || Game's main directory
|-
| <code>ExIni.dll</code> || Contains classes and methods for manipulating .ini files. || Game's main directory
|-
| <code>Mono.Cecil.dll</code> || Contains tools for manipulating CIL assemblies (reading classes, methods, etc) || Game's main directory
|-
| <code>Mono.Cecil.*.dll</code> || Miscellaneous classes and tools to extend Mono.Cecil's functionality. || Game's main directory
|-
| <code>ReiPatcherPlus.dll</code> (optional) || Extends the functionality of some classes found in <code>ReiPatcher.exe</code> || Game's main 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.

=== 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 ====
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, 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. 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 programming choice, 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.
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.
The number of requests is the same as the number of assemblies we want to patch.

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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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.
|-
| <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".
|}

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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-06T23:02:04Z

Denikson:

{{Custom Maid 3D 2}}

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 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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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 impossible to manipulate, which is due to the code being mostly unmanaged.
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.

==== 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>CM3D2x84_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 ===
* 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] and [http://code.google.com/p/cecilstudio Cecil Studio]. In this tutorial we will be using ILSpy.

== Designing the plug-in ==
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 || Game's main directory
|-
| <code>ExIni.dll</code> || Contains classes and methods for manipulating .ini files. || Game's main directory
|-
| <code>Mono.Cecil.dll</code> || Contains tools for manipulating CIL assemblies (reading classes, methods, etc) || Game's main directory
|-
| <code>Mono.Cecil.*.dll</code> || Miscellaneous classes and tools to extend Mono.Cecil's functionality. || Game's main directory
|-
| <code>ReiPatcherPlus.dll</code> (optional) || Extends the functionality of some classes found in <code>ReiPatcher.exe</code> || Game's main 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.

=== 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 ====
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, 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. 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 programming choice, 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.
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.
The number of requests is the same as the number of assemblies we want to patch.

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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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.
|-
| <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".
|}

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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}

Custom Maid 3D2/Modding/Plugins

2015-08-06T23:01:05Z

Denikson: Created page with "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 o..."

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 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:''' This tutorial was written with ReiPatcher 0.9.0.6 and UnityInjector 1.0.1.1. It is possible that in later versions of those tool there will have been some major changes in their design, which may or may not make this tutorial obsolete.

== 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 impossible to manipulate, which is due to the code being mostly unmanaged.
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.

==== 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>CM3D2x84_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 ===
* 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] and [http://code.google.com/p/cecilstudio Cecil Studio]. In this tutorial we will be using ILSpy.

== Designing the plug-in ==
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 || Game's main directory
|-
| <code>ExIni.dll</code> || Contains classes and methods for manipulating .ini files. || Game's main directory
|-
| <code>Mono.Cecil.dll</code> || Contains tools for manipulating CIL assemblies (reading classes, methods, etc) || Game's main directory
|-
| <code>Mono.Cecil.*.dll</code> || Miscellaneous classes and tools to extend Mono.Cecil's functionality. || Game's main directory
|-
| <code>ReiPatcherPlus.dll</code> (optional) || Extends the functionality of some classes found in <code>ReiPatcher.exe</code> || Game's main 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.

=== 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 ====
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, 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. 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 programming choice, 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.
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.
The number of requests is the same as the number of assemblies we want to patch.

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. 
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.

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 it has already been patched by our patch. 
ReiPatcherPlus contains another convenience method: <code>HasAttribute(AssemblyDefinition assembly, string attribute)</code>. 
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>. 
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. 
All in all, injecting our <code>OnClickHook(UIButton hook)</code> requires the following steps:
# 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, why not do all that with just two lines of code? 
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)
{
this.HookMethod(args.Assembly.MainModule.GetType("UIButton"), "OnClick",
hookAssembly.MainModule.GetType("CM3D2.HelloWorld.Hook.HelloWorldHooks"), "OnClickHook");
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 ==
Finally, by using UnityInjector one can affect game's logic and objects using Unity's own scripting API. 
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>MonoBehavior</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.
|-
| <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".
|}

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 a 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>

=== 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. 
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. 
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 above
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>

== 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.

=== Method hooking ===
Consider the following class that contains the following methods:
<code>
namespace Game
{
public class GameClass
{
public int numberOfCarrots = 42;

public void GameMethod();
public void GameMethod(string s, int i, bool b);
private void GameMethod(byte b);
}
}
</code>

Now imagine we want to do the simplest of tasks: alter <code>GameMethod()</code> so that it calls our own method <code>MyMethod()</code> that is located in our own assembly in namespace <code>MyNamespace.MyClass</code>.

In this case we can use <code>HookMethod</code>, a method that injects (hooks) a call to <code>MyNamespace.MyClass.MyMethod()</code> into <code>GameClass.Game.GameMethod()</code> (hook method) before the method's own instructions. That way, before <code>GameClass.Game.GameMethod()</code> proceeds with own logic, it will call <code>MyNamespace.MyClass.MyMethod()</code>. 
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).

==== Examples ====
Suppose we are patching <code>Game</code> assembly. Assume also that we have <code>AssemblyDefinition</code> of <code>MyNamespace</code> assembly as a variable named <code>hookAssembly</code>.

Therefore, we can patch the methods in patcher class's <code>Patch(PatcherArguments args)</code> method:
<code>
// MyMethod definition: void MyMethod(Game.GameClass thatGame)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod()
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: void MyMethod(Game.GameClass thatGame, string s, int i, bool b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(string), typeof(int), typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: void MyMethod(byte b)
this.HookMethod(args.Assembly.MainModule.GetType("Game.GameClass"), "GameMethod",
new[] { typeof(byte) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</code>

Note that only the ones with <code>Game.GameClass</code> object will be able to access the <code>numberOfCarrots</code> variable.

=== Method redirecting ===
Let us consider the next class:
<code>
namespace Game
{
public class Swallow
{
public float airSpeedVelocity = 11.2F;

public float GetNeededSwallows(int coconuts);
public bool IsSwallowEuropean(bool isNotAfrican);
private void MakeFly(bool isUnladen, float distance);
}
}
</code>

Suppose we want not to just hook a method — we want to replace it with a definition of our own! That can be achieved with ReiPatcherPlus' <code>RedirectMethod</code> methods.
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.

==== Examples ====
With the same rules as before, here is the code that is put into <code>Patch(PatcherArguments args)</code>:
<code>
// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out float result)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);

// MyMethod definition: bool MyMethod(Game.Swallow swallow, bool isUnladen, float distance)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "MakeFly",
new[] { typeof(bool), typeof(float) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out float result, int coconuts)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "GetNeededSwallows",
new[] { typeof(int) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(Game.Swallow swallow, out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod");

// MyMethod definition: bool MyMethod(out bool result, bool isNotAfrican)
this.RedirectMethod(args.Assembly.MainModule.GetType("Game.Swallow"), "IsSwallowEuropean",
new[] { typeof(bool) },
hookAssembly.MainModule.GetType("MyNamespace.MyClass"), "MyMethod", false);
</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.
|}

=== 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.
|}