Intro Post Part 2/2Project Output
The disassembly is stored here in the online source control system BitBucket
. By visiting there you can get the latest version of the disassembly and view up-to-the-minute comments made on the most recent commit.
I also post occasional updates to the projects own page on my own site here: http://www.mybrillgamesite.com/projects/?id=86
As a courtesy I’d like to ask 2 things of anyone who uses the information I work out:
- Please don’t reproduce large sections of it on your own site or submit it to places like the RHDN database. When the time comes I will decide myself if and how I want to submit it, until then I’d prefer it to stay in one place that is easy to maintain (note my site is ad free so this isn’t a money making exercise, although I’d be lying if I said I don’t enjoy seeing the little visitor count go up!)
- Please give me a shout out if it helps you in your work or in one of the thousands of awesome Toejam and Earl hacks that I hope are produced as a result! This isn’t because I’m vain and want achieve world fame (honest!) but is because I’m curious and want to know just how helpful something like this is to the community and how much quality work is spawned as a result. If I see the project is successful, a lot of people like it and a lot of good things come of it I may turn my hand to other some games in the future (always wanted to know more about Mega-lo-Mania and Dune 2…).
Of course I have no way to enforce this and arguably no right to do so so I’m relying on your own sense of fairness and morals (god help me…).Toolchain, Process and References
This project is as much about learning as it is about disassembling. To this end here you will find link to all the specific items that I’ve used throughout the project from the emulators for exploring code, to the topics I’ve posted for help through to the sites and books I’ve used as reference. If you have any questions on any part of the project please, please ask. I love sharing knowledge almost as much as I love gaining it.ToolchainExodus
– Used to generate the initial disassembly that has been used as the basis for this whole project. It's Active Disassembly function is breathtaking, allowing bit-perfect disassemblies to be generated in mere hours. Also has great debugging capabilities.GENS r57shell Mod
– Used for exploring the ROM in real time, has a great 68K debugger with step by step instruction execution and breakpoints as well as a RAM watcher and editor. Before this I was using GENS KMod, GENS Tracer and GENS Hacking Version but have found this to be a suitable replacement for all 3. I also gave MAME a trial as I heard it had great debugging capabilities but r57shell’s more intuitive interface made it an easier option to get to grips with.Easy68K
– Used for re-assembling the disassembled ROM. Very useful as it displays the opcodes of the instructions in hex meaning you can enter an existing instruction (such as DEC.b $#01, D0) and change it (eg ADD.b $#01, D0) and see what the new hex code is which you can then apply directly to the ROM via a hex editor without re-assembling (if you are so inclined).Visual Studio Code
– Although I use Easy68k for building the assembly source code I use VSCode for editing it. It has a plethora of tools, shortcuts and extension there to help make your programming life easier including keyword highlighting, a code minimap, source control integration, search all files and replace in all files (these have been invaluable!) and it even has themable Easy68k syntax highlighting!
Disasm.exe – This is the initial tool used to disassemble the Toejam and Earl rom. It was run over the entire file meaning all the graphics and data were also disassembled as code. Part of the process of this project was rooting out these sections and separating them until the disassembly generated by Exodus replaced this version.HxD
– Free and decent hex editor. Process
Initially there were 2 ways I was disassembling the ROM / understanding the disassembly, one was in execution order where I started from the entry point of the ROM (offset $00000202) and followed the code through separating and annotating routines in order as I went. The second was jumping to known areas of interest and following the code forwards and backwards from there. Finding an area of interest was fairly straight forward: use the RAM search tool to work out a value that changes, such as lives, and then set a watchpoint to break on that value changing in one of the debuggers. When it hits, note down the address it was at and then go to the code in the disassembly at that point and read, understand and annotate the code.
This worked pretty well, but after creating the whole disassembly and starting to split it out into multiple files I needed a way to work faster and smarter and that's when I switched to Visual Studio Code (VSCode).
Using VSCode I can quickly move entire sections of code into different files, named and stored in directories based upon what they relate to. I can also rename labels and locations, such as RAM addresses, throughout the entire disassembly with just a few keystrokes. Once the RAM addresses have meaningful names throughout it is easier to read the code and work out what each section is doing or at least what it relates to. It can then be moved to the relative file, making the remaining code clearer and the process can be repeated.
By doing this I'll eventually have all the related code in roughly well categorised areas and can begin looking more in-depth at how each section works.
Taking an in-depth look at certain areas is already (or still!) something I do when I'm bored, or even just distracted when I accidently find something interesting. I've already mapped out how input is read, had a close look at how the inventory works, started pulling out some graphics into editable formats, and looked at the main game loop and other fun things.
To do this I tend to have Exodus or GENS r57shell Mod open alongside VSCode and step through the instructions in the emulator's debugger whilst noting in the disassembly what is going on.References
For anyone wanting to learn how to do this sort of task here are the resources I recommend reading:RNDH Documentation
- Over the years I have read everything there is filed under Genesis and the vast majority of items under Assembly that aren’t processor specific (and even a few that are). Of particular interest are Tony Hedstrom’s documents on how to create Game Genie codes, anything by Fonzie and anything official.Tony Hedstrom’s Guides
- The Megadrive doesn’t have nearly as much documentation as it’s NES and SNES cousins but Tony has produced a considerable amount of Megadrive focused hacking documents and if you were only to read guides from one author on the subject (I strongly suggest you read more!) then I would make it him. He single handedly explains all you need to know about how to make real, hardware compatible GameGenie codes which in the process teaches you a huge amount about ROM hacking in general.BigEvilCorporation
- BEC focuses more on developing your own games for the Megadrive than it does disassembling others. In fact if you look at his more recent posts you’ll see he’s actually working on a rather polished looking game right as we speak. This doesn’t stop it being a great resource for disassembly though as all the information you gain on initialising the Megadrive, displaying sprites, performing loops and so on are all items you will encounter while reading through the disassembled code. DarkDust / Marc’s Domain
- Before BigEvilCorporation there was DarkDust. A lot of the information you see here centres around getting the Megadrive initialised and how the VDP works. The writing style is a bit more technical than BEC but don’t let that put you off, there is still really useful insight to be gained once you wrap your head round it.Sprite’s Mind (Main site and Forum)
- Home of Kaneda, creator and maintainer of GENS Kmod and all round Megadrive super Guru. Again, like DarkDust, documents here might get a little technical for some people’s liking (especially when reading through the forums) and because Kaneda’s native language is French a lot of the earlier documents can be a little disjointed but they are still brilliant and mandatory reading. I only add them below the others as you’ll want to be at least a little Megadrive savvy to get the full benefit from them.
His forums are also home to the Exodus, Regen and KMod emulators and the UMDK dev kit so there is a lot of Megadrive knowledge in the people who call Sprite’s Mind home.http://68k.hax.com/
- Quick reference for the 68K instruction set, actually pretty detailed as well.https://youtu.be/qztuEucrNBc
- Inspirational YouTube video.Forum Topics
Here are some specific topics I've made about issues or queries that have came up throughout the project:Code Skipping in GENS
– A topic about how the 2 tracing versions of GENS output their trace logs.Memory Map Visualising
– A topic about the best way to visualise a memory map.Which Emulator Should I Put My Efforts Into
– A discussion about the different hacking based emulators.Contribute!
Yes, you can contribute to the project. Please forward all cash donations to the following PO Box address… just kidding!
Contributions can come in 2 forms, neither of them money related!Technical Contributions
At this point I’m not really looking for any technical assistance. I want to complete the majority of the disassembly myself for my own learning and own satisfaction.
However, if you have the technical know-how and are so inclined then I would be grateful to have anything I publish double checked, even just at a passing glance, for any obvious errors or omissions. I will always strive to publish information that is complete and accurate but I am aware of my own limitations and as this is a learning process mistakes are sure to get through. Any effort to help reduce them not only helps me but anyone else who will be using my work and as a result is greatly appreciated.
Also, if you happen to know the ‘signature’ of any compression algorithms or tell-tale signs of their use then I’d be all ears to know about them!Non-Technical Contributions
This is the type on contributions I’m really looking for just now!
I want to see this project through whether there is call for it or not but I’d love to hear about some of the uses you can see coming out of having a full disassembly of Toejam and Earl at your disposal!
How would you change the game?
What kind of presents would you like to add? Would you add more characters? More players? How about changing the goal of the game so that Toejam starts on level 1, Earl start on level 25 with the aim to be to meet up with the game getting harder and harder the closer you get?
And to this end, what parts of the game do you need to know the details of to achieve it? This may sway the order in which I disassemble certain sections.End Note
So that is it! Well this ended up a bit of a goliath post didn’t it? Hopefully you’ve found it at least a little interesting and if you’ve skipped it all and came right here don’t worry, I’m still interested in your replies!
Now please, fill this topic up with suggestions like it is a Toejam and Earl specific Hack Ideas thread. I think I’ve got the skill but I know there will be people out there with better ideas of what to do with it than me. Seeing lots of awesome ideas will help keep my encouraged and hopefully make me progress a bit faster and get the project completed a little sooner.
Please also be sure to ask any questions you have about anything related, whether it is info on the game or more general questions about the hacking process.
Finally, please also be sure to call me a hero/fool as you see appropriate and post words of encouragement (such as this video over and over https://www.youtube.com/watch?v=qztuEucrNBc
) or anything else you think will help.
Thanks for reading.