| At line 1 changed one line |
| !!!Prerequisites |
| !!Prerequisites |
| At line 23 added 32 lines |
|
| !!Runtime Code Modules |
| Runtime Code Modules were created to minimize the amount of memory being used by code patches at any given point. The way that it works is that a file called {{code.rcm}} is placed in the root of a scene archive, and when that scene is loaded, the patches from the file are processed. This allows for code that only needs to be in effect during one particular scene to remain in memory only temporarily. Because the address that an RCM file will be loaded at can't be reliably predicted, more size will be taken up by things like the relocation table. |
|
| The patch mechanisms of RCM files are similar to that of New Super Mario Bros. Editor's. It contains direct analogs for the {{arepl}}, {{ansub}}, {{trepl}} and {{tnsub}} hook types. Rather than indicating hooks to the patcher by means of specific label names, RCM uses a hook table at the end of the file instead. To write a hook table, place the following code at the end of a source file: |
|
| %%prettify |
| {{{ |
| HOOK_TABLE( |
| //your hooks here... |
| ); |
| }}} |
| /% |
|
| Inside the parentheses goes a comma-separated list of hook definitions. These use the macro functions {{HOOK_ANSUB}}, {{HOOK_AREPL}}, {{HOOK_TNSUB}}, {{HOOK_TREPL}}, {{HOOK_DATA32}}, {{HOOK_DATA16}}, {{HOOK_DATA8}}, {{HOOK_LOAD}}, and {{HOOK_UNLOAD}}. The first four function in the same way as the hook types from the New Super Mario Bros. Editor work. The {{HOOK_DATAxx}} hook types, rather than creating branch instructions in the target code, serve to replace arbitrary data of either 32, 16, or 8 bits. This may be useful for patching some variable, a table entry, or replacing a single instruction. The {{HOOK_LOAD}} and {{HOOK_UNLOAD}} types specify a callback function that is to be called when the RCM is loaded and unloaded, and an arbitrary number can be present in the file. Any source file may contain a hook table, and hook tables from all source files get combined into one hook table during build. |
|
| For example, a hook table that replaces the code at the address {{0207AA4C}} with a branch to {{MyFunction}} and replaces the 32-bit data at {{0217AA14}} with {{1234}}, a hook table would look like: |
|
| %%prettify |
| {{{ |
| HOOK_TABLE( |
| HOOK_ANSUB(0x0207AA4C, MyFunction), |
| HOOK_DATA32(0x0217AA14, 1234) |
| ); |
| }}} |
| /% |
|
| When the RCM is unloaded, the hook table is traversed again to un-patch the previously patched code and data. Avoid writing overlapping hook destinations, and writing to patched data when unloading to avoid ordering issues. |
|
| To build an RCM file, a specific folder setup is required for the default build setup. Each {{code.rcm}} should have a folder inside the main code patching folder, alonside the {{source}} folder if using NSMBe. Inside the RCM project folder, place the {{Makefile}} and {{linker.x}} from the RuntimeCodeModules repository on GitHub. Then, simply run {{make}} in the code folder, and, on successful build, a {{code.rcm}} file will be produced. Note that for external thumb functions to work correctly, ensure that the LSB of thumb symbols is set in the parent {{symbols.x}} file, as the RCM build setup relies on this information to generate correct outgoing branch instructions. |
|
| With an RCM file built, simply place it into the root of one of the supported archive files (supported archives listed on the GitHub repository) and the loader will take care of the rest. |
