Edit Infobox Wii Homebrews: Wiinject

Free text:

Wiinject is a tool that allows you to inject ASM hacks into Wii games using [[Riivolution Wii|Riivolution]] memory patches. It takes a folder containing PowerPC assembly files (.s) and C files (.c) as input, along with injection sites, and outputs a memory file and a series of Riivolution XML memory patches. It is cross-platform. Wiinject relies on the [https://www.keystone-engine.org/ Keystone Engine] to assemble code and [https://devkitpro.org/ devkitPro] to compile C code. == User guide == ===Prerequisites=== * The [https://dotnet.microsoft.com/en-us/download/dotnet/6.0 .NET 6.0 runtime]. * [https://devkitpro.org/wiki/Getting_Started devkitPro] if compiling C code. ===CLI Options=== * <code>-f|--folder</code> – The folder where your source files live * <code>-m|--dolphin-map|--map|--symbols</code> – A Dolphin symbols map for any built-in functions you want to reference by name * <code>-i|--injection-addresses</code> – The addresses to inject function code at, comma delimited. The code at these addresses should be safe to overwrite. * <code>-e|--injection-ends</code> – The addresses at which the above injection sites end (are no longer safe to overwrite), comma delimited. If the code is unable to fit in any of these injection sites, an error will be thrown. * <code>-o|--output-folder</code> – The folder to output the Riivolution patch.xml &amp; assembled ASM bin file to. * <code>-n|--patch-name</code> – The name of the patch to output. The patch will be output to <code>{output_folder}/Riivolution/{patch_name}.xml</code> and the ASM bin will be output to <code>{output_folder}/{patch_name}/patch.bin</code>. * <code>-p|--input-patch</code> – The base Riivolution patch that will be modified by Wiinject to contain the memory patches. A blank base template will be created if this is not provided. * <code>d|devkitpro-path=</code> ‐ The path to a devkitPro installation containing devkitPPC (e.g. <code>C:\devkitPro</code> or <code>/opt/devkitpro</code>) * <code>--console-output</code> – Rather than producing an ASM patch, simply output the XML to the console. This will still save the ASM bin, however. * <code>--emit-c</code> – Emits assembled C functions to the console so you can modify your assembly calls to those functions to work with the registries used by the compiler. ==== Structuring Your Source Code and Preparing Your Initial Patch ==== Wiinject expects the <code>folder</code> where your source lives to have one subdirectory for each patch element you wish to generate. For example, if you'd like your final Riivolution patch to contain one optional patch for translating the game and another for reducing monster spawns, name one subdirectory something like <code>Translation</code> and the other <code>ReduceMonsterSpawns</code>. Then, place your source files relevant to those patches in those directories. When preparing your input patch, make sure you set up the options yourself and ensure that the patch names in the options match the names of the subdirectories in your source <code>folder</code>. Finally, add any patch elements that have non-memory patches. Wiinject will automatically create patch elements that don't exist and append to ones that do. If you've followed along, your input patch should look something like this: <pre>&lt;wiidisc version=&quot;1&quot;&gt; &lt;id game=&quot;R42069&quot; /&gt; &lt;options&gt; &lt;section name=&quot;Translation&quot;&gt; &lt;option name=&quot;Translation&quot;&gt; &lt;choice name=&quot;Enabled&quot;&gt; &lt;patch id=&quot;Translation&quot; /&gt; &lt;/choice&gt; &lt;/option&gt; &lt;/section&gt; &lt;section name=&quot;Quality of Life&quot;&gt; &lt;option name=&quot;Reduce Monster Spawns&quot;&gt; &lt;choice name=&quot;Enabled&quot;&gt; &lt;patch id=&quot;ReduceMonsterSpawns&quot; /&gt; &lt;/choice&gt; &lt;/option&gt; &lt;/section&gt; &lt;/options&gt; &lt;patch id=&quot;Translation&quot;&gt; &lt;folder external=&quot;/Game/files&quot; recursive=&quot;true&quot; disc=&quot;/&quot; /&gt; &lt;folder external=&quot;/Game/files&quot; /&gt; &lt;/patch&gt; &lt;/wiidisc&gt;</pre> === Writing ASM === Wiinject uses the Keystone Engine to assemble standard PowerPC assembly. To write an assembly file that Wiinject can parse, however, you need to use special function names. Here is a sample Wiinject-compatible assembly file: <pre>hook_80017250: start: add 5,5,0 mr 26,3 cmpwi 5,3 beq end li 5,2 end: blr hook_80017254: mr 3,26 blr repl_80017260: mr 5,25 li 6,7 ref_801BBB38: li 6,7 blr</pre> The <code>hook</code>s indicate which instructions to replace with a branch instruction to the function provided. The <code>repl</code> indicates a location to start overwriting instructions directly with the instructions provided. The <code>ref</code> indicates a location to write a reference to the function provided (useful for hooking into functions that use <code>bctrl</code>, etc.). === Using Variables in ASM === Wiinject allows for a special notation to store and interact with variables. Variables can be defined anywhere in an ASM file with <code>$variable:</code>, e.g. <code>$array: .skip 16</code>. You can then load that variable into memory with the <code>lv</code> command. <code>lv</code> is resolved to an <code>lis</code> followed by an <code>addi</code> in the assembling process. Example: <pre>$variable: .int 0 $array: .skip 16 hook_80017250: lv 2,$variable lv 3,$array blr</pre> === Writing C === For each ASM file, you may also provide a companion C file to compile and inject methods which may then be called from the ASM. In order to use this functionality, you must install [https://devkitpro.org/wiki/Getting_Started devkitPro] and provide Wiinject with the path to the devkitPro installation (e.g. <code>C:\devkitPro</code> or <code>/opt/devkitpro</code>). Injected C methods are called from the ASM via <code>bl =method_name</code>. The assembly function caller will need to handle stack manipulation and inputs itself. You can expect a compiled C method to accept inputs sequentially starting with <code>r3</code> and to place its return value in <code>r3</code>. However, in order to verify this, you can use the <code>--emit-c</code> flag while calling Wiinject to view the compiled C code's assembly so you can adjust your assembly caller appropriately. Here is a sample Wiinject-compatible C file named ''font_hack.c'': <pre>int font_offset(char character) { switch (character) { case 'A': return 0x180; case 'I': case 'i': case 'l': case '!': return 0x48; default: return 0x90; } }</pre> And here is its companion ASM file named ''font_hack.s'': <pre>hook_8001726C: stwu 1,-24(1) mflr 0 stw 0,20(1) stw 31,16(1) mr 31,1 stw 9,12(1) stw 3,8(1) mr 3,26 cmpwi 3,75 bl =font_offset lwz 0,20(1) mtlr 0 mr 0,3 lwz 9,12(1) lwz 3,8(1) addi 11,31,24 lwz 31,-4(11) mr 1,11 blr</pre> === Using Symbols === You can provide Wiinject with a Dolphin symbols map and use that to reference functions existing in the ASM in the same way you would reference C functions. Map file: <div class="snippet-clipboard-content notranslate position-relative overflow-auto"> <pre class="notranslate">.text section layout 80004000 00000050 80004000 0 memcpy</pre> Assembly: <pre>hook_8001726C: stwu 1,-24(1) mflr 0 stw 0,20(1) bl =memcpy lwz 0,20(1) mtlr 0 addi 1,24 blr</pre> === Limitations === * Wiinject only supports the <code>bl</code> command for C functions or functions defined in your Dolphin symbols map; functions defined in assembly cannot currently be branched to. * The [https://wiibrew.org/wiki/Paired_single paired single operators] are not available. ==Changelog== '''v1.2.1''' Fixes: *Complex switch statements written in C compile to jump tables which were not supported by Wiinject. This adds support for jump tables and thus makes these switch statements work as intended. *Wiinject errors were sometimes hard to debug due to vague error messages. This adds more detailed error messages for certain cases that should make things easier to debug. '''v1.2.0''' *Upgraded to .NET 6.0. *Variables in assembly implemented. *Added support for referencing built-in functions using a Dolphin symbols map. *Added ref and hex assembly tags which allow for specifying that the address should be written rather than a bl instruction and specifying raw hex to be written, respectively. *Refactored the CLI so Wiinject can be packaged as a NuGet package. *Add support for multiple patch elements. Not in this release but just noticed: *We actually do support multi-file C lmao. '''v1.1.0''' *Wiinject is now self-documenting (not providing arguments will print the options list). *Added repl assembly tag in addition to hook. repl allows for directly replacing assembly at the target address rather than inserting a branch instruction. *Added support for multiple injection sites so you can split your code among multiple safe-to-overwrite locations on the ROM. *Added support for compiling and injecting C code. Compilation is done using devkitPro and functions can be referenced from ASM via bl=c_function_here Fixes: *Customized Keystone's C# binding so it actually works cross-plat. *Keystone now throws errors when encountering assembly it can't assemble. '''v1.0.0''' *Initial release of Wiinject. ==External links== * GitHub - https://github.com/jonko0493/Wiinject * Romhacking.net - https://www.romhacking.net/utilities/1660/