Prerequisites#
To proceed with the tutorial, it is a good idea to have a solid understanding of, in order of importance:- ARM assembly
- ARM EABI
- The C programming language
Patch Methods#
There are a couple of different methods of code patching that are used in Mario Kart DS modding. The oldest and most widely used method involves using the New Super Mario Bros Editor by Szymbar. Memory use limitations with this method of patching prompted the creation of a patching method that can make better use of main memory, and that system is Runtime Code Modules (RCM). In the vein of more general code patching, TheGameratorT authored NCPatcher, a tool for code patching similar to New Super Mario Bros Editor but more streamlined and with more functionality.NSMBe Patching#
The New Super Mario Bros. Editor patch system places new code at the beginning of the main memory arena, shifting the low address over by the size of the added code. When hooks are used, the instructions at those locations are overwritten depending on the hook's type. It is very important to be mindful of the amount of code being added so as not to cause memory shortage problems, since any memory use by your custom code is memory that can't be used for anything else anymore. To use New Super Mario Bros Editor to make an ASM hack, the following software is required:- Szymber's New Super Mario Bros. Editor fork
- devkitARM with libnds
To start a hack with this method, create a folder containing a ROM with a clean ARM9 program. Alongside it in the same folder, you will need a symbols.x, linker.x, arenaoffs.txt, and Makefile. The symbols.x file contains a list of symbols used by the hack, and the linker will use this file to look up any external symbols. Use an up-to-date symbols file to be sure you have access to all symbols you may need. The linker.x file contains instructions for the linker when producing the resulting object file and can be safely harvested from another hack, likewise for the Makefile and arenaoffs.txt. Code will go into a folder called source. These can be assembly source files (.s), C source files (.c), and header files (.h).
To write a hook, write a function (C) or label (assembly) whose name starts with either arepl_XXXXXXXX, ansub_XXXXXXXX, trepl_XXXXXXXX, or tnsub_XXXXXXXX, where XXXXXXXX is the address of the instruction to patch (in DS address space). The first character of these labels indicates whether the hook should be an ARM hook (a) or THUMB hook (t), and whether to branch (nsub) or branch and link (repl). Both ansub and arepl hooks take up 1 instruction, and as such their patches only consume 4 bytes. A trepl takes one 4-byte wide instruction, and a tnsub takes 3 instructions totaling 8 bytes. The patcher treats all branch destinations as being ARM code (not thumb). Knowing the type of hook used is critical in returning to normal game code correctly (e.g. don't return with BX LR using an ansub hook, unless the hooked function should actually be returning).
To patch the code into the game, open the ROM with NSMBe, navigate to the Tools tab, then click Run Make and Insert. The first time through, since no backup folder exists, it may throw an error but create a backup folder after. If this does happen, run Make Clean, then Make and Insert and the code should patch without issue. Close NSMBe to commit the changes to the disk, and then you're left with a ROM with patched code. Under normal circumstances, do not modify the ARM9 copy kept in the backup folder, as this is what NSMBe will use as a base when patching code in the future.
