The day I reverse engineered a furry Gameboy Advance game

🎥 Talk: https://www.youtube.com/watch?v=RMM_5bq3Ct8

Let’s learn how you can create your own ROM hacking for your favorite game!

You will discover how the loved Gameboy Advance works, understand a crazy ARM assembly and reverse engineering stuff, to create a level editor running on the browser.

Reverse engineering is a heavy topic, so what do you think of learning it in a fun way through this challenge: developing a level editor for the furry game “Klonoa: Empire of Dreams”?
It's an exciting challenge because we need to understand the GBA's architecture, discover how the game works, and finally use our knowledge to build our tool.

Transcript

1. The day I reverse engineered a furry Gameboy Advance game With @macabeus D E F C O N F u r
2. WTF?! THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
9. github.com/macabeus/klo-gba.js
10. github.com/macabeus/klo-gba.js
11. Tools THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
12. https://problemkaputt.de/gba.htm
13. https://www.hex-rays.com/products/ida
15. Stretching the bridge THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
19. Here is the bridge
20. Here is the debugger panel
21. This is the tile ID. In this example, all tiles with the ID 9B are the bridge left-corner. 9A is the ID of the continuous part of the bridge.
22. This tells us where the tile is stored in the memory. In this example, it is at 0600F1AD.
23. https://www.coranac.com/tonc/text/hardware.htm
24. https://www.coranac.com/tonc/text/hardware.htm The address found is expected 0600F1AD given that everything between 0600 and 0601 is part of the section known as VRAM.
25. Our bridge starts here!
26. Our bridge starts here!
27. And now we grow it bigger!
28. And now we grow it bigger!
29. And now we grow it bigger! WTF??!
30. Understanding the DMA THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
33. VRAM pulls the tilemap containing exactly what the player has to see from somewhere else that has the entire thing.
34. https://www.coranac.com/tonc/text/regbg.htm
35. https://www.coranac.com/tonc/text/regbg.htm Direct Memory Access D M A
36. https://www.coranac.com/tonc/text/regbg.htm DMA
37. https://www.coranac.com/tonc/text/regbg.htm It is a feature of computer systems that allows certain hardware subsystems to access main system memory (random access memory), independent of the CPU
38. https://www.coranac.com/tonc/text/regbg.htm tldr; makes copying and pasting faster
39. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 84000048
40. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 84000048 The closest to the bytes of our bridge (0600F1AD).
41. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 84000048 In other words, VRAM is updated here
42. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 84000048 This byte is the VRAM data source. It’s located in the Fast WRAM section.
44. And going to this address…
45. Our bridge starts here!
46. Stretching it…
47. Stretching it… And…
48. Stretching it… …It works! And…
49. Stretching it… …It works! And… WTF??!
50. Stretching it… …It works! And… WTF??!
53. Our extra tiles disappear when out of the player vision range.
54. LET’S TALK ABOUT PHYSICS THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
55. Object Attribute Memory O A M
56. OAM
58. This is the address in which Klonoa is stored on the memory
59. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 8400003E
60. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 8400003E We can see exactly the byte that writes on Klonoa’s object (07000000).
61. DMA3: 03000900 0600E000 80000400 DMA3: 03001100 0600E800 80000400 DMA3: 03004DB0 0600F000 80000200 DMA3: 03004800 07000000 8400003E We can see exactly the byte that writes on Klonoa’s object (07000000).
63. The first byte on an object defines the Y position…
64. …and updating it…
65. …and updating it…
66. …on running the next frame, we can notices that it changes the Klonoa Y position!
67. …on running the next frame, we can notices that it changes the Klonoa Y position! But also returns this byte for the correct value…
68. …and Klonoa continues to fall as to be nothing happened
71. Camera 03002926:03002927
72. Camera 03002926:03002927 63 00 63 00
73. Camera 03002926:03002927 63 00 63 00 In-game position 03002922:03002923
74. Camera 03002926:03002927 63 00 63 00 In-game position 03002922:03002923 88 01 76 01
75. Camera 03002926:03002927 63 00 63 00 In-game position 03002922:03002923 88 01 76 01
76. After a lot of researches, I found it:
77. Here is where updates the in-game Y position
78. Here is where it decides if it should update or not the Klonoa's position…
79. …and it uses the tile id stored at the Slow WRAM Here is where it decides if it should update or not the Klonoa's position…
80. https://www.coranac.com/tonc/text/hardware.htm
81. https://www.coranac.com/tonc/text/hardware.htm
82. After updating the tile map at the Slow WRAM…
83. After updating the tile map at the Slow WRAM…
84. LET’S find the tilemap on rom THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
85. The data flow Cartridge
86. The data flow Cartridge Slow WRAM >
87. The data flow Cartridge Slow WRAM > Fast WRAM >
88. The data flow Cartridge Slow WRAM > Fast WRAM > VRAM >
89. The data flow Cartridge Slow WRAM > Fast WRAM > VRAM > Display >
90. Slow WRAM Our research flow Cartridge Display VRAM Fast WRAM > > > >
92. Level loader instructions
93. swi… what?
94. i SW
95. SoftWare Interrupt i S W
96. SoftWare Interrupt i S W = Bios Calls
98. BIOS is a firmware that is intended to initialise the physical components of the system
99. BIOS is a firmware that is intended to initialise the physical components of the system In GBA, its BIOS exposes many functions often used in games, including data compression and decompression
100. BIOS is a firmware that is intended to initialise the physical components of the system In GBA, its BIOS exposes many functions often used in games, including data compression and decompression Each function has an associated numeric code, which must be used as a parameter in the SWI statement
101. How division works on GBA: swi 0x06
102. How division works on GBA: swi 0x06 Input: R0 
 numerator R1 
 denominator
103. How division works on GBA: swi 0x06 Input: R0 
 numerator R1 
 denominator R0 
 numerator / denominator R1 
 numerator % denominator R3 
 abs(numerator / denominator) Output:
104. And in this case, the software is calling the Huffman Decompress and lz77 Decompress functions
105. Huffman + lz77 = deflate
110. 6E 6E 6E B0 B1 BD 77 AB B3 AB B3 7C 6E 6E 6E 6E 6E 6E 6E 6E 7C 6E 6E 6E 6E 7C 6E 6E
111. 6E 6E 6E B0 B1 BD 77 AB B3 AB B3 7C 6E 6E 6E 6E 6E 6E 6E 6E 7C 6E 6E 6E 6E 7C 6E 6E 6E 6E 6E B0 B1 BD 77 AB B3 AB B3 7C 6E 6E 6E 6E 6E 6E 6E 6E 7C 6E 6E 6E 6E 7C 6E 6E
112. 6E 6E 6E B0 B1 BD 77 AB B3 AB B3 7C 6E 6E 6E 6E 6E 6E 6E 6E 7C 6E 6E 6E 6E 7C 6E 6E 6E 6E 6E B0 B1 BD 77 AB B3 AB B3 7C 6E 6E 6E 6E 6E 6E 6E 6E 7C 6E 6E 6E 6E 7C 6E 6E =
113. Let’s paint the tilemap THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
114. 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F
115. 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F
116. 0x1A 0x1B 0x1C 0x1D 0x1E 0x1F
117. H · W = 25020 
 H,W ∈ ℕ
119. x x x x a x x x x 
 x x x x b x x x x I’m on tile a Below me is the tile b
120. x x x x a x x x x
121. x x x x a x x x x 
 x x x x b x x x x From the tile a to b there are 9 bytes (= 9 tiles), so the length of the tilemap is exactly 9 I’m on tile a
123. Breakpoint here
124. The tile address which Klonoa is standing on
125. The tile address which Klonoa is standing on
126. When I change this byte…
127. When I change this byte… …it reflects right there, and it’s our tile a,…
128. When I change this byte… …it reflects right there, and it’s our tile a,… …at 02008439
129. Then we should update the tiles below Klonoa…
130. …to drop him one level Then we should update the tiles below Klonoa…
131. Then get the tile address on the one level below
132. Changing this byte…
133. Changing this byte… …we found the tile b!
134. Changing this byte… …we found the tile b! It's at 020085DD
135. 02008439 - 020085DD = 1A4 (420) 
 The length of the level is 420!
136. Jimp github.com/oliver-moran/jimp
137. const Jimp = require('jimp') const { drop } = require('ramda') const fs = require('fs') const data = drop(3, fs.readFileSync(‘dump/level-1/tilemap'))
138. const Jimp = require('jimp') const { drop } = require('ramda') const fs = require('fs') const data = drop(3, fs.readFileSync('dump/level-1/tilemap'))
139. const getPixelColor = hexTile = > { if (hexTile === 0) { return 0x000000 } return 0xFFFFFF }
140. new Jimp(300, 600, (err, image) = > { let x = 0 let y = 0 for (let i = 0; i < data.length; i += 1) { const value = data[i] x += 1 if (x === 420) { y += 1 x = 0 } let color = getPixelColor(value) image.setPixelColor(color, x, y) } image.write('image.png') })
147. LET’S see the project THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
148. Coding THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
149. Stack
150. React.js GitHub Pages WebAssembly
151. React.js GitHub Pages WebAssembly
152. React.js GitHub Pages WebAssembly
153. React.js GitHub Pages WebAssembly
154. architecture
156. 🖌 Brush
157. 🖌 ✂ Brush Scissors
158. Z 🖌 ✂
159. Z 🖌 ✂ Extract data 
 from the ROM Get constants values Update the 
 ROM data UI
160. Web assembly
161. Tilemap compressed > Old C code to uncumpress it Decompressed Tilemap >
162. Tilemap compressed >
163. Tilemap compressed > Old C code to uncumpress it Decompressed Tilemap >
164. Tilemap compressed > Old C code to uncumpress it Decompressed Tilemap > Emscripten WebAssembly > >
165. huffman.c lzss.c > Emscripten > huffman.wasm 
 lzss.wasm huffman.js 
 lzss.js +
166. const lzssModule = require('./wasm/lzss.js' ) const { FS } = lzssModul e const lzssDecode = (buffer) => { FS.writeFile('filelzss', buffer ) lzssModule._LZS_Decode( ) try { return lzssModule.FS.readFile('filelzss', { encoding: 'binary' } ) } catch (e) { throw new LzssDecodeError(e ) } }
167. const lzssModule = require('./wasm/lzss.js' ) const { FS } = lzssModul e const lzssDecode = (buffer) => { FS.writeFile('filelzss', buffer ) lzssModule._LZS_Decode( ) try { return lzssModule.FS.readFile('filelzss', { encoding: 'binary' } ) } catch (e) { throw new LzssDecodeError(e ) } }
168. const lzssModule = require('./wasm/lzss.js' ) const { FS } = lzssModul e const lzssDecode = (buffer) => { FS.writeFile('filelzss', buffer ) lzssModule._LZS_Decode( ) try { return lzssModule.FS.readFile('filelzss', { encoding: 'binary' } ) } catch (e) { throw new LzssDecodeError(e ) } }
169. const lzssModule = require('./wasm/lzss.js' ) const { FS } = lzssModul e const lzssDecode = (buffer) => { FS.writeFile('filelzss', buffer ) lzssModule._LZS_Decode( ) try { return lzssModule.FS.readFile('filelzss', { encoding: 'binary' } ) } catch (e) { throw new LzssDecodeError(e ) } }
170. const lzssModule = require('./wasm/lzss.js' ) const { FS } = lzssModul e const lzssDecode = (buffer) => { FS.writeFile('filelzss', buffer ) lzssModule._LZS_Decode( ) try { return lzssModule.FS.readFile('filelzss', { encoding: 'binary' } ) } catch (e) { throw new LzssDecodeError(e ) } }
171. const lzssModule = require('./wasm/lzss.js' ) const { FS } = lzssModul e const lzssDecode = (buffer) => { FS.writeFile('filelzss', buffer ) lzssModule._LZS_Decode( ) try { return lzssModule.FS.readFile('filelzss', { encoding: 'binary' } ) } catch (e) { throw new LzssDecodeError(e ) } }
172. function docker_run_emscripten { local filename="$1" echo "Compiling $filename..." docker run \ --rm -it \ -v $(pwd)/scissors/src/wasm:/src \ trzeci/emscripten:1.38.43 \ emcc -s WASM=1 -s ALLOW_MEMORY_GROWTH=1 -s MODULARIZE=1 \ -s EXTRA_EXPORTED_RUNTIME_METHODS=[\”FS\"] \ -s EXPORT_NAME=\"$filename\" -o ./$filename.js $filename. c } docker_run_emscripten huffma n docker_run_emscripten lzss
173. function docker_run_emscripten { local filename="$1 " echo "Compiling $filename... " docker run \ --rm -it \ -v $(pwd)/scissors/src/wasm:/src \ trzeci/emscripten:1.38.43 \ emcc -s WASM=1 -s ALLOW_MEMORY_GROWTH=1 -s MODULARIZE=1 \ -s EXTRA_EXPORTED_RUNTIME_METHODS=[\”FS\"] \ -s EXPORT_NAME=\"$filename\" -o ./$filename.js $filename. c } docker_run_emscripten huffma n docker_run_emscripten lzss
174. const extractFullTilemap = (romBuffer, addressStart) = > romBuffer.slice(addressStart ) |> huffmanDecod e |> lzssDecode
175. Saving the new tilemap
176. First Level Second Level Third Level Each level is stored continually in the memory
177. First Level Second Level Third Level
178. First Level Second Level Third Level Changes in the first level >
179. Customised
180. > Second Level Third Level Customised
181. > Second Level Third Level Customised
183. Thumb ARM
184. Faster to run Instructions demand less memory Thumb ARM
185. Faster to run Instructions demand less memory Can perform more complex instructions Thumb ARM
187. The switch between ARM and Thumb must be done by bx instruction.
188. The switch between ARM and Thumb must be done by bx instruction. This instruction only can read a register
189. The switch between ARM and Thumb must be done by bx instruction. This instruction only can read a register bx updates the PC by the register value used in its parameter
190. Very big hole space at the end of cartridge First Level Second Level Third Level Instruction to load a level
191. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole
192. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 0836720 FC 27 1B 0 8 0836724 00 77 36 0 8 0836728 5C 3E 1B 0 8 083672C B0 86 36 0 8 0836730 AC 50 1B 0 8 0836734 80 93 36 08
193. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 0836720 FC 27 1B 0 8 0836724 00 77 36 0 8 0836728 5C 3E 1B 0 8 083672C B0 86 36 0 8 0836730 AC 50 1B 0 8 0836734 80 93 36 08
194. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 0836720 FC 27 1B 0 8 0836724 00 77 36 0 8 0836728 5C 3E 1B 0 8 083672C B0 86 36 0 8 0836730 AC 50 1B 0 8 0836734 80 93 36 08
195. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 0836720 FC 27 1B 0 8 0836724 00 77 36 0 8 0836728 5C 3E 1B 0 8 083672C B0 86 36 0 8 0836730 AC 50 1B 0 8 0836734 80 93 36 08
196. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole
197. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole Original Loader 08043B0A mov r4, r0 08043B0C add r0, r5, 4 08043B0E mov r1, r4 08043B10 bl 0805143Ch
198. First Level Second Level Third Level Instruction to load a level (patched) Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole Original Loader 08043B0A mov r4, r0 08043B0C add r0, r5, 4 08043B0E mov r1, r4 08043B10 bl 0805143Ch Patched Loader 08043B0A mov r4, r0 08043B0C bl 08367610 h 080v3B10 bl 0805143Ch
199. First Level Second Level Third Level Instruction to load a level (patched) Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole Patched Loader 08043B0A mov r4, r0 08043B0C bl 08367610 h 080v3B10 bl 0805143Ch R0 is the pointer to which the tilemap will be loaded. We should update it to the address of the custom level
200. First Level Second Level Third Level Instruction to load a level (patched) Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole Patched Loader 08043B0A mov r4, r 0 08043B0C bl 08367610 h 080v3B10 bl 0805143Ch
201. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 08367610 mov r0, r15 ; r15 = PC
 08367612 add r0, 3Ch
 08367614 bx r0
202. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 08367650 add r0, r4, 4 h 08367654 ldr r4, [r15, #-3Ch ] 08367658 cmp r0, r 4 0836765C ldreq r0, [r15, #-40h ] 08367660 ldr r4, [r15, #-40h ] 08367664 cmp r0, r 4 08367668 ldreq r0, [r15, #-44h ] 0836767C ldr r4, [r15, #-44h ] 08367680 cmp r0, r 4 08367684 ldreq r0, [r15, #-48h ] 08367688 mov r4, r 1 0836768C bx r14
203. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 08367650 add r0, r4, 4 h 08367654 ldr r4, [r15, #-3Ch ] 08367658 cmp r0, r 4 0836765C ldreq r0, [r15, #-40h ] 08367660 ldr r4, [r15, #-40h ] 08367664 cmp r0, r 4 08367668 ldreq r0, [r15, #-44h ] 0836767C ldr r4, [r15, #-44h ] 08367680 cmp r0, r 4 08367684 ldreq r0, [r15, #-48h ] 08367688 mov r4, r 1 0836768C bx r14
204. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 08367650 add r0, r4, 4 h 08367654 ldr r4, [r15, #-3Ch ] 08367658 cmp r0, r 4 0836765C ldreq r0, [r15, #-40h ] 08367660 ldr r4, [r15, #-40h ] 08367664 cmp r0, r 4 08367668 ldreq r0, [r15, #-44h ] 0836767C ldr r4, [r15, #-44h ] 08367680 cmp r0, r 4 08367684 ldreq r0, [r15, #-48h ] 08367688 mov r4, r 1 0836768C bx r14
205. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 08367650 add r0, r4, 4 h 08367654 ldr r4, [r15, #-3Ch ] 08367658 cmp r0, r 4 0836765C ldreq r0, [r15, #-40h ] 08367660 ldr r4, [r15, #-40h ] 08367664 cmp r0, r 4 08367668 ldreq r0, [r15, #-44h ] 0836767C ldr r4, [r15, #-44h ] 08367680 cmp r0, r 4 08367684 ldreq r0, [r15, #-48h] 08367688 mov r4, r 1 0836768C bx r14
206. First Level Second Level Third Level Instruction to load a level Constant addresses map table Hole Customised level loader Customised First Level Customised Second Level Customised Third Level Hole Hole Hole 08367650 add r0, r4, 4 h 08367654 ldr r4, [r15, #-3Ch ] 08367658 cmp r0, r 4 0836765C ldreq r0, [r15, #-40h ] 08367660 ldr r4, [r15, #-40h ] 08367664 cmp r0, r 4 08367668 ldreq r0, [r15, #-44h ] 0836767C ldr r4, [r15, #-44h ] 08367680 cmp r0, r 4 08367684 ldreq r0, [r15, #-48h ] 08367688 mov r4, r1 0836768C bx r14
207. 1. Redirect to the patched code 2. Check if the R0 is on the table 3. If yes, load the associated value 4. Return to the original loader
208. Result THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
215. Other project THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
216. react-gbajs github.com/macabeus/react-gbajs
217. WE ARE... THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
218. BRUNO MACABEUS Senior Software Engineer 
 @outsystems macabeus bmacabeus
219. MATHEUS ALBUQUERQUE Special thanks for helping to develop the frontend at this talk ythecombinator www.ythecombinator.space
220. Raul peres Special thanks for drawing all the images Kniksis KniksisG
221. RayCarrot Special thanks for helping to extract the sprites from the rom RayCarrot RayCarrot
222. Ray1Map github.com/Adsolution/Ray1Map
223. Matt Greer Special thanks for helping to improve the emulator city41 www.mattgreer.dev
224. Smaghetti github.com/city41/smaghetti
225. This talk THE DAY I REVERSE ENGINEERED A GAMEBOY ADVANCE GAME
226. github.com/macabeus/klo-gba.js
227. github.com/macabeus/klo-gba.js
228. bit.ly/gba-posts
229. github.com/macabeus/klo-gba.js
230. github.com/macabeus/klo-gba.js
231. github.com/macabeus/klo-gba.js
232. bit.ly/theconf-gba
233. bit.ly/balccon-gba
234. OBRIGADO THANKS macabeus