Research: The Pokemon Ruby/Sapphire Dissassembly/Decompilation Project

I'm genuinely surprised and dumbfounded noone has posted this yet.

Anyways: I am a member of a public github project to dissassemble (and decompile!) Pokemon Ruby/Sapphire. It can be found here: https://github.com/pret/pokeruby

Questions

What is decompilation you ask? Decompilation is the process of taking compiled assembly and running it backwards through the original compiler in order to get the original programming that was written by Game Freak. In this case, starting with generation 3 (up to 5), the Pokemon games were written in C and compiled into the console-specific assembly that you see on all ROMs.

How do we know this is the matching compiler? Basically looking at the GBA SDK we immediately realized the compiler used was an open source GPL-licensed one (specifically gcc) and this is why we're able to tell you this without any legal risk whatsoever. So, to decompile these games, it was just a matter of trying to find the correct compiler and the default settings/likely settings used.

Why Ruby/Sapphire and not Emerald or Fire Red/Leaf Green? Well, the answer for that is a decompilation process one. Game Freak started generation 3 with Ruby/Sapphire, but internally, the gen 3 base was molded and changed into different games over the course of the years gen 3 was active. Specifically, Ruby/Sapphire was partially rewritten into Fire Red and Leaf Green, which then it was re-molded back into Emerald for the last gen 3 main release. Because of this, there are some pretty heavy engine differences between the games. Specifically, the menu and text and window system is extremely different between R/S and FR/LG/E. Turns out, the newer one is extremely hard to get matching decompiled code (as of now we do have a matching text.c for Emerald, but not a completely matching window.c), even though we know Game Freak did not update the compiler or anything like that (for reasons). For this reason we mainly focus on R/S until we're somewhat close to a complete decompilation project.

Why use this over standard binary hacking methods? Well, for one, editing C is 1000x easier than assembly. You can implement things on a source level so much quicker than with standard script editor and map editor tools. Take Instant text for example, which in R/S text speed 0 does not produce an instant text effect, where as in Emerald it does. Implementing support in R/S via asm edits would probably require rewriting most of the text functions in the text.c area block of assembly, but via the C file, it's only a few lines of changes.

As of 5-26-2017, the ROM is somewhat around 30% decompiled.

NEW UPDATE 8/26/2017:
The ROM is somewhat around 60% decompiled now. The relevent lists have been updated.

Decompilation Status
Engine System

Undecompiled
- [ ] m4a_3.s

Decompiled/Available in C
- [X] agb_flash.c
- [X] agb_flash_1m.c
- [X] agb_flash_le.c
- [X] agb_flash_mx.c
- [X] blend_palette.c
- [X] cable_club.c
- [X] clear_save_data_menu.c
- [X] clock.c
- [X] decompress.c
- [X] libc.c
- [X] link.c
- [X] load_save.c
- [X] m4a_2.c
- [X] m4a_4.c
- [X] m4a_tables.c
- [X] main.c
- [X] main_menu.c
- [X] menu.c
- [X] menu_cursor.c
- [X] mystery_event_menu.c
- [X] mystery_event_script.c
- [X] name_string_util.c
- [X] naming_screen.c
- [X] option_menu.c
- [X] palette.c
- [X] play_time.c
- [X] rtc.c
- [X] record_mixing.c
- [X] rng.c
- [X] save.c
- [X] save_failed_screen.c
- [X] save_menu_util.c
- [X] script.c
- [X] siirtc.c
- [X] sound.c
- [X] sound_check_menu.c
- [X] sprite.c
- [X] strings.c // actually a data file of nothing but engine-relevent strings
- [X] string_util.c
- [X] task.c
- [X] text.c
- [X] text_window.c
- [X] tileset_anim.c
- [X] time_events.c
- [X] trade.c
- [X] trainer_card.c
- [X] trig.c
- [X] util.c
- [X] reset_rtc_screen.c

Engine Special Scene

Undecompiled
- [ ] cute_sketch.s

Decompiled
- [X] berry_blender.c
- [X] egg_hatch.c
- [X] evolution_scene.c
- [X] intro_credits_graphics.c
- [X] hall_of_fame.c
- [X] evolution_graphics.c
- [X] intro.c
- [X] contest_painting.c
- [X] credits.c
- [X] title_screen.c
- [X] new_game.c // birch scene is considered a special scene.

Field Movement & Event

Unfinished

Undecompiled
- [ ] cable_car.s
- [ ] cable_car_util.s

Decompiled
- [X] bard_music.c
- [X] bike.c
- [X] berry.c
- [X] braille_puzzles.c
- [X] daycare.c
- [X] decoration.c
- [X] fieldmap.c
- [X] field_camera.c
- [X] field_control_avatar.c
- [X] field_door.c
- [X] field_effect.c
- [X] field_effect_helpers.c
- [X] field_fadetransition.c
- [X] field_ground_effect.c
- [X] field_map_obj.c
- [X] field_map_obj_helpers.c
- [X] field_player_avatar.c
- [X] field_poison.c
- [X] field_screen_effect.c
- [X] field_special_scene.c
- [X] fldeff_cut.c
- [X] fldeff_softboiled.c
- [X] fldeff_strength.c
- [X] fldeff_sweetscent.c
- [X] fldeff_teleport.c
- [X] heal_location.c
- [X] mauville_old_man.c
- [X] map_obj_lock.c
- [X] metatile_behavior.c
- [X] roamer.c
- [X] rotating_gate.c
- [X] safari_zone.c
- [X] scrcmd.c
- [X] script_movement.c
- [X] secret_base.c
- [X] trainer_see.c
- [X] wild_encounter.c

Field Menu & Scene

Undecompiled
- [ ] easy_chat.s
- [ ] pokenav.s
- [ ] roulette.s
- [ ] roulette_util.s
- [ ] slot_machine.s

Decompiled
- [x] berry_tag_screen.c
- [X] birch_pc.c
- [X] choose_party.c
- [x] coins.c
- [x] coord_event_weather.c
- [X] decoration_inventory.c
- [x] dewford_trend.c
- [x] diploma.c
- [x] event_data.c
- [x] field_region_map.c
- [x] field_message_box.c
- [X] field_specials.c
- [X] field_tasks.c
- [x] hof_pc.c
- [x] item.c
- [x] item_use.c
- [x] landmark.c
- [x] lottery_corner.c
- [x] map_name_popup.c
- [x] money.c
- [x] party_menu.c
- [X] pokeblock.c
- [X] pokeblock_feed.c
- [x] player_pc.c
- [x] script_menu.c
- [x] shop.c
- [x] start_menu.c
- [x] starter_choose.c
- [X] use_pokeblock.c
- [x] wallclock.c
- [x] tv.c
- [X] item_menu.c
- [X] region_map.c
- [x] trader.s
- [x] fldeff_flash.s
- [x] menu_helpers.s

Contest

Undecompiled
- [ ] contest.s
- [ ] contest_ai.s
- [ ] contest_effect.s
- [ ] contest_link_80C2020.s
- [ ] contest_link_80C857C.s

Battle System

Undecompiled
- [ ] battle_1.s
- [ ] battle_2.s
- [ ] battle_9.s

Decompiled
- [X] battle_3.c
- [X] battle_4.c
- [X] battle_5.c
- [X] battle_6.c
- [X] battle_7.c
- [X] battle_8.c
- [X] battle_10.c
- [X] battle_811DA74.c
- [X] battle_interface.c
- [X] battle_message.c
- [X] battle_party_menu.c
- [X] battle_records.c
- [X] battle_tower.c
- [X] battle_transition.c
- [X] battle_setup.c
- [X] battle_ai.c
- [X] calculate_base_damage.c // note: doesnt match but is probably functionally equivalent.
- [X] post_battle_event_funcs.c

Battle Anim

Undecompiled
- [ ] battle_anim_80CA710.s
- [ ] battle_anim_81258BC.s
- [ ] battle_anim_812C144.s
- [ ] battle_anim_813F0F4.s

Decompiled
- [X] pokeball.c
- [X] battle_anim.c
- [X] battle_anim_807B69C.c
- [X] battle_anim_80A7E7C.c
- [X] smokescreen.c
- [X] battle_anim_8137220.c

Pokemon

Undecompiled
- [ ] pokedex_area_screen.s
- [ ] pokedex_cry_screen.s
- [ ] pokemon_item_effect.s
- [ ] pokemon_storage_system.s
- [ ] pokemon_summary_screen.s

Decompiled
- [X] pokedex.c
- [X] pokemon_1.c
- [X] pokemon_2.c
- [X] pokemon_3.c
- [X] pokemon_menu.c
- [X] pokemon_size_record.c
- [X] pokemon_summary_screen.c
- [X] learn_move.c
- [X] mail.c
- [X] mail_data.c
- [X] mon_markings.c
- [X] pokemon_icon.c

This is probably a dumb question, but do you guys have any idea when a usable version will be released?

This is really cool regardless. Can't wait to see what people do with this. Pokecrystal has already been jumping and spawning some really awesome stuff, so let's hope this'll have the same effect.

Could we have more information on what exactly one does to contribute to this?

How do you verify that a decompiled routine matches 100%? Is there some kind of documentation? What methodology do you have for actually approaching what to decompile; is it just in order? Wouldn't starting with music / compressed images significantly increase how much is decompiled from the get-go?

This is very interesting but I've never really had a clear idea in my head of how work on it actually works.

ProjectRevoTPP said:

I'm genuinely surprised and dumbfounded noone has posted this yet.

Click to expand...

I posted a topic about this back in January. https://www.pokecommunity.com/showthread.php?t=387832

camthesaxman said:

I posted a topic about this back in January. https://www.pokecommunity.com/showthread.php?t=387832

Click to expand...

It wasn't really a general resource thread.

Just popping in to say "Wow Revo".

Also to identify myself as a contributor to this project. Howdy!

A lot of progress has happened since this post was updated. Our decompilation efforts are estimated to be at least 42% as of this post.

And now, we're over 50% thanks to DizzyEgg's work on battle_4.c!

Deokishisu said:

I can almost see it. PokeRuby explodes onto the hacking scene. Gazing upon what man has wrought, it sheds a single manly tear. With just a terminal, it wipes away our folly, leaving only perfection in its wake. The age of darkness has ended. Now there is only light.

Click to expand...

Couldn't put it better. {XD}

But you are right, pokeruby is going to change our romhacking scene forever. And once it happens, there will be no coming back.

Stay hyped!
And pls contribute

At some point in the future I would like to contribute; but I would like to see the Japanese version disassembled as well. Would that require a separate disassembly or could it just be a fork instead?

Decompilation is an important step, but the real magic will happen during the documentation and labeling/refactoring that happens after decomp finishes.

This is really interesting, but could someone working on it make a little README to describe files and directories in this projects.
I think this can help to understand how it works.

bien cordialement,

Edwearth said:

This is really interesting, but could someone working on it make a little README to describe files and directories in this projects.
I think this can help to understand how it works.

bien cordialement,

Click to expand...

Documentation will take a higher priority when this project is above 90-95% decompiled. The reason being if we have to refactor anyway we might as well do that after we rearrange everything so work isnt wasted.

Yes you're right, but it will be easier for a foreigner to understand your work and help you.
A short documentation about the directories and main files could be a good idea and isn't a waste of time, in my opinion.
Thanks

Edwearth said:

Yes you're right, but it will be easier for a foreigner to understand your work and help you.
A short documentation about the directories and main files could be a good idea and isn't a waste of time, in my opinion.
Thanks

Click to expand...

I have already begun a PR seen here: https://github.com/pret/pokeruby/pull/403 which splits up all the files in src/ and puts them into folders relevent to their purpose as part of step 1 of the initial documentation. Hopefully the next step is a slight refactor of the headers when the dissassembly is in a more advanced state and most files are decompiled.

Documentation is just as important as decompilation. Naming functions and variables, and adding comments where appropriate would help immensely. The vast majority of labels are still sub_XXXXXXXX and gUnknown_XXXXXXXX, and it would be nice to give those meaningful names. I know there are a lot of ROM hackers here who have great knowledge of the inner workings of the Gen 3 games and could help with that.

I just noticed that Pokeruby is already buildable. Took its sweet time but after 10 minutes or so I've got Pokeruby.gba!
I'm so glad the method's way easier than Pokecrystal's with cygwin, packages and stuff too, nice work Pret and every single person who contributed with the project in one way or another so far!



I'm sure it's not ready to be used yet, but I'll play through it and see if I can find any bugs <3
Should I report any bug I find over here or it won't be necessary?

Lunos said:

I just noticed that Pokeruby is already buildable. Took its sweet time but after 10 minutes or so I've got Pokeruby.gba!
I'm so glad the method's way easier than Pokecrystal's with cygwin, packages and stuff too, nice work Pret and every single person who contributed with the project in one way or another so far!

Spoiler:

I'm sure it's not ready to be used yet, but I'll play through it and see if I can find any bugs <3
Should I report any bug I find over here or it won't be necessary?

Click to expand...

If you do

make compare

Click to expand...

instead of just make, it will tell you if the ROM matches the original one.

NEW UPDATE 8/26/2017:
The ROM is somewhat around 60% decompiled now. The relevent lists have been updated.

(sorry for the bump)

Our plans for the near future:
Part of the reason we started on R/S before Emerald was to make decompiling Emerald easier when we finally get around to it. You see, most of Emerald's base is just R/S base but changed, so we are following that development path in order to make it straight forward.

There are a number of files in pokeruby that, for the most part, are not changed fundamentally besides malloc access added. For example, field_special_scene.s (the file which does the truck scene and porthole scene on SS Tidal) does not change. Most of the battle AI cmd functions in battle_ai.c also did not change besides the AI processing code itself. Because of this, a lot of emerald decomp with matching pokeruby functions is just copy paste and updating labels, so this makes that step a lot easier once we get there. We're aiming for at least 80% pokeruby decomp before we start laying the proper groundwork for pokeemerald.