Toejam and Earl Disassembly

[RyanfaeScotland]

Intro Post Part 1/2

Preamble
Have you ever searched this forum for Toejam and Earl hacks? Or for general information relating to which is considered by many (including myself) to be the single greatest game on the Sega Megadrive? If you haven't let me save you the time, a search for "Toejam" (as at 24/1/2016) turns up a measly 8 results and 3 of them are mine!

Although it isn't just RHDN that is sparse on information, even googling "Toejam and Earl Rom Hack" turns up next to nothing, a solitary page on Sonic Retro with some sparse notes about uncompressed graphics and ASCII text: http://forums.sonicretro.org/index.php?showtopic=20964

Well, this project aims to change all that!

TL;DR – I'm creating a disassembly of Toejam and Earl, I'm about 5% through, I've only done the easy parts I've created a disassembly of Toejam and Earl! You can check out the source code on its BitBucket repository here or keep reading to find out more about the project and the work done to date.

Intro
I am Ryan and I am from Scotland, hence the user name RyanFaeScotland. I've been posting here and ROM hacking on and off for several years now and despite having my own site dedicated to the information I've discovered, a few video tutorial on ROM hacking and even an accepted (and then rejected) submission to RHND I'll be the first to admit I am still yet to contribute anything of any serious substance or value to the community. That is part of the reason why I've set myself the rather lofty challenge of creating a complete disassembly of Toejam and Earl on the Sega Megadrive.

The other part of the reason is that it is without a doubt the one game that has cemented its place deep within my childhood memories. It is a game I used to play for hours on end with my best friend (who has since moved to America) and alone on single player. It scares me to think how many hours I lost to this game, easily on par with games that are actually meant to be long like Shining Force 2, FF7, Metal Gear and so on.

I'm now at a point where I find myself, as an adult software developer, more interested in the magic behind the game than I am in actually playing the game itself. Just what is it that makes Rocket Skates impossible to stop? What is the game doing behind the scenes during the elevator cut scenes? How does the random level generator work? And, most importantly, how can I make the game more centred around spending time in the hot tub with the hula girls?

So this project is more than just a means of giving back, it is also a tribute or a living memory of my childhood and all the joy T&E brought to it, a sort of labour of love to honour the game that gave me so much enjoyment.

The whole thing kicked off back in October 2015 when a ROM hacker by the name of Juan Perez contacted me saying he had created a disassembly of Toejam and Earl and would like my help to get the results understood. He had worked out a few things but since the disassembly had been created fairly blindly by running disasm.exe against the entire ROM file the output contained a mess of data, instructions, tiles, music and text which had all be decompiled as code.

Although I haven't heard from Juan since it was enough of a proposal to really capture my interest and get my off by butt and start and now that I am I'm resolved to complete it!

Project Goals
This post will be kept up to date as the project progresses and goals will be added and removed as time goes on.

Main Goal
There is of course one main goal that will always remain:

• Create a complete, annotated disassembly of Toejam and Earl that can be modified, reassembled and played on real hardware.

Sub Goals
To help me achieve the main goal here are some additional sub-goals that will make it possible (these will always be needing fleshed out):

• Get Megadrive initialisation mapped out and understood.
• Get intro loop mapped out and understood.
• Get initial game menu mapped out and understood.
• Locate uncompressed graphics.
• Locate compressed graphics.
• Understand graphics compression algorithm.
• Locate uncompressed text.
• Locate compressed text.
• Understand text compression algorithm used.

Fun Goals
And here are some fun goals to do along the way to save me going too crazy looking at line after line of 68K!

• Slingshot to be a deadly tomato cannon.
• Make Santa chase Toejam / Earl.
• Make it possible to change which presents are in the inventory.
• Change the presents T&E start the game with.
• Make presents always identified.

Progress Reports

Progress Report 1 - 2016-Jan-24
I started the project in earnest at the end of December 2015 and have done this initial post on the forum on the 24th of January 2016. At this point roughly 5% of the game has been disassembled and marked up, however, a large portion of this is made up of the uncompressed graphics that are clearer visible in the ROM using Tile Layer Pro so don't get too excited.

To date the majority of time has been spent trialling different emulators and related tools to see which ones are going to aid me best in the project. A little write up of the current toolchain and process used to disassemble and understand the ROM is given below but as it stands I am currently using GENS r57shell Mod for my exploration and testing of the ROM, Easy68K for my re-assembling and Notepad++ for the majority of my note taking.

Progress Report 2 - 04-Mar-2016

Progress Report 3 - 01-Nov-2016

Progress Report 4 - 19-Jul-2018

Progress Report 5 - 13-Mar-2019

Progress Report 6 - 20-May-2019

Progress Report 7 - 30-Jun-2019

Progress Report 8 - 19-Jun-2020

Sections of Interest

Here are a few sections of interest I've uncovered so far:

Game Setup
Part of setting up the game, setting lives, score, cash.

Code Select Expand

*
* Loading lives and so on
*
0000BB78 207C 00FFA248            MOVE.L    #$00FFA248,A0
0000BB7E 4A10                     TST.B     (A0)             *Checks if Toejam is in the game.
0000BB80 6D1C                     BLT       $0000BB9E
0000BB82 13FC 0001 00FFA2A6       MOVE.B    #$01,$00FFA2A6
0000BB8A 13FC 0017 00FFA252       MOVE.B    #$17,$00FFA252   *Sets Toejam's health to $17 on game start.
0000BB92 10BC 0003                MOVE.B    #$03,(A0)        *Sets Toejam's lives to 3 on game start.
0000BB96 13FC 0003 00FFA24A       MOVE.B    #$03,$00FFA24A   *Sets Toejam's cash to 3 on game start.
0000BB9E 4A28 0001                TST.B     $0001(A0)        *Checks if Earl is in the game
0000BBA2 6D1E                     BLT       $0000BBC2
0000BBA4 13FC 0001 00FFA326       MOVE.B    #$01,$00FFA326
0000BBAC 13FC 001F 00FFA253       MOVE.B    #$1F,$00FFA253
0000BBB4 117C 0003 0001           MOVE.B    #$03,$0001(A0)
0000BBBA 13FC 0003 00FFA24B       MOVE.B    #$03,$00FFA24B
0000BBC2 13FC 00FF 00FFA259       MOVE.B    #$FF,$00FFA259
0000BBCA 13FC 00FF 00FFA258       MOVE.B    #$FF,$00FFA258
0000BBD2 13FC 00FF 00FFDE50       MOVE.B    #$FF,$00FFDE50
0000BBDA 13FC 00FF 00FFDE51       MOVE.B    #$FF,$00FFDE51
0000BBE2 4878 0001                PEA       $0001
0000BBE6 42A7                     CLR.L     -(A7)
0000BBE8 4EBA F2AE                JSR       $0000AE98(pc)
0000BBEC 4878 0001                PEA       $0001
0000BBF0 4878 0001                PEA       $0001
0000BBF4 4EBA F2A2                JSR       $0000AE98(pc)
0000BBF8 42A7                     CLR.L     -(A7)
0000BBFA 4EBA EE3E                JSR       $0000AA3A(pc)
0000BBFE 4878 0001                PEA       $0001
0000BC02 4EBA EE36                JSR       $0000AA3A(pc)
0000BC06 42A7                     CLR.L     -(A7)
0000BC08 4EBA F0A0                JSR       $0000ACAA(pc)
0000BC0C 4878 0001                PEA       $0001
0000BC10 4EBA F098                JSR       $0000ACAA(pc)
0000BC14 42A7                     CLR.L     -(A7)
0000BC16 4EBA F7AC                JSR       $0000B3C4(pc)
0000BC1A 4878 0001                PEA       $0001
0000BC1E 4EBA F7A4                JSR       $0000B3C4(pc)
0000BC22 4FEF 0028                LEA       $0028(A7),A7
Initial Presents Setting

Code Select Expand

*
* Adds Bonus HiTops to Toejam's inventory, 4 on single player, 2 on 2 player.
*
0001435C 4E71                     NOP
0001435E 588F                     ADDQ.L    #$4,A7
00014360 14BC 001B                MOVE.B    #$1B,(A2)
00014364 157C 001B 0001           MOVE.B    #$1B,$0001(A2)
0001436A 4A39 00FFA249            TST.B     $00FFA249
00014370 6C0C                     BGE       $0001437E
00014372 157C 001B 0002           MOVE.B    #$1B,$0002(A2)
00014378 157C 001B 0003           MOVE.B    #$1B,$0003(A2)
0001437E 4A39 00FFA249            TST.B     $00FFA249
00014384 6D2C                     BLT       $000143B2
00014386 4878 0001                PEA       $0001
0001438A 4EBA 07D4                JSR       $00014B60(pc)

*
* Adds Bonus HiTops to Earl's inventory, 4 on single player, 2 on 2 player.
*
0001438E 4E71                     NOP
00014390 588F                     ADDQ.L    #$4,A7
00014392 157C 001B 0010           MOVE.B    #$1B,$0010(A2)
00014398 157C 001B 0011           MOVE.B    #$1B,$0011(A2)
0001439E 4A39 00FFA248            TST.B     $00FFA248
000143A4 6C0C                     BGE       $000143B2
000143A6 157C 001B 0012           MOVE.B    #$1B,$0012(A2)
000143AC 157C 001B 0013           MOVE.B    #$1B,$0013(A2)
000143B2 245F                     MOVE.L    (A7)+,A2
000143B4 4E75                     RTS
Input Polling (Pad1)

Code Select Expand

*
* Input Reading Routine
*
00027006 33FC 0100 00A11100       MOVE.W    #$0100,$00A11100   *Turn off Z80
0002700E 13FC 0040 00A10009       MOVE.B    #$40,$00A10009
00027016 13FC 0000 00A10003       MOVE.B    #$00,$00A10003     *Request Low byte from A10003 (Pad1)
0002701E 323C 000A                MOVE.W    #$000A,D1          *Move A (10) into D1
00027022 51C9 FFFE                DBRA      D1,$00027022       *Loop until D1 = 0 (short delay to read pad)
00027026 7000                     MOVEQ     #$00,D0            *Clear out D0
00027028 1039 00A10003            MOVE.B    $00A10003,D0       *Move value from A10003 (Pad1) to D0
0002702E E508                     LSL.B     #2,D0              *Bit shift D0 left 2 bits
00027030 0200 00C0                AND.B     #$C0,D0            *And it with C0
00027034 13FC 0040 00A10003       MOVE.B    #$40,$00A10003     *Request High byte from A10003 (Pad1)
0002703C 323C 000A                MOVE.W    #$000A,D1          *Move A (10) into D1
00027040 51C9 FFFE                DBRA      D1,$00027040       *Loop until D1 = 0 (short delay to read pad)
00027044 1239 00A10003            MOVE.B    $00A10003,D1       *Move value from A10003 (Pad1) to D1
0002704A 0201 003F                AND.B     #$3F,D1            *And it with 3F
0002704E 8001                     OR.B      D1,D0              *Or them together
00027050 4600                     NOT.B     D0                 *Negate D0
00027052 5539 00A0004A            SUBQ.B    #$2,$00A0004A
00027058 13F9 00A0004B 00FFE46E   MOVE.B    $00A0004B,$00FFE46E
00027062 33FC 0000 00A11100       MOVE.W    #$0000,$00A11100   *Turn on Z80
0002706A 4E75                     RTS
Present Time Counter

Code Select Expand

*
* From around this address controls the length of time left for presents
*
000158F0 3002                     MOVE.W    D2,D0
000158F2 48C0                     EXT.L     D0
000158F4 207C 00FFDE50            MOVE.L    #$00FFDE50,A0
000158FA 4A30 0800                TST.B     $08(A0,D0.W)
000158FE 588F                     ADDQ.L    #$4,A7
00015900 6C4C                     BGE       $0001594E
00015902 6048                     BRA       $0001594C
00015904 3002                     MOVE.W    D2,D0
00015906 48C0                     EXT.L     D0
00015908 D080                     ADD.L     D0,D0
0001590A 204A                     MOVE.L    A2,A0
0001590C 5370 0800                SUBQ.W    #$1,$08(A0,D0.W)   *Subtracts 1 from the amount of time left on the present.
00015910 3030 0800                MOVE.W    $08(A0,D0.W),D0
00015914 0C40 012C                CMP.W     #$012C,D0          *Checks if less than 300 cycles are left on present.
00015918 6302                     BLS       $0001591C
0001591A 6030                     BRA       $0001594C
0001591C 3002                     MOVE.W    D2,D0
0001591E 48C0                     EXT.L     D0
00015920 D080                     ADD.L     D0,D0
00015922 0C72 0064 0800           CMP.W     #$0064,$08(A2,D0.W) *Checks if less than 100 cycles are left on present.
00015928 6314                     BLS       $0001593E
0001592A 3002                     MOVE.W    D2,D0
0001592C 48C0                     EXT.L     D0
0001592E D080                     ADD.L     D0,D0
00015930 7200                     MOVEQ     #$00,D1
00015932 3232 0800                MOVE.W    $08(A2,D0.W),D1
00015936 700C                     MOVEQ     #$0C,D0
00015938 C280                     AND.L     D0,D1
0001593A 6712                     BEQ       $0001594E
0001593C 600E                     BRA       $0001594C

[altoiddealer]

I'm not any form of hacker - just the end user.

I'll be following this.  TJ&E is an amazing game, definitely my childhood favorite.  Ya better believe I was another one googling "Toejam & Earl rom hack" and met with some disappointment.

I look forward to seeing what comes out of this 

Good luck!

If I had one suggestion on something to be added, some kind of boss battle or other end-of-game challenge requirement would be pretty cool.  I don't expect that will ever happen but your title suggests you're open to ideas so 

[RyanfaeScotland]

Intro Post Part 2/2

Project 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.

Toolchain
Exodus – 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.

[altoiddealer]

Well, I do have another idea for anyone hacking this game... It would be interesting to have items that instantly take effect (other than food, phones, bucks, etc).  Sprites on the map such as Icarus wings, rocket skates, bonus hightops, pogo stick, innertube, boombox and tomatoes would be interesting instant items.  Some of the negative items could make interesting "roadblocks" as the bad food items and enemies occassionally do on tight passages.

[RyanfaeScotland]

Feels good to finally get this posted up, like it is one more thing in place so that I can crack on and focus purely on the task at hand.

I was also thinking it might would be good to get MBuild set up and a few different versions of the ROM in place showcasing different changes. That way it is a lot easier to demonstrate the latest updates rather than dropping code nuggets on everyone which although ok for some might not be palatable for a wider audience.

...If I had one suggestion on something to be added, some kind of boss battle or other end-of-game challenge requirement would be pretty cool.

...It would be interesting to have items that instantly take effect (other than food, phones, bucks, etc).  Sprites on the map such as Icarus wings, rocket skates, bonus hightops, pogo stick, innertube, boombox and tomatoes would be interesting instant items.

Nice, I really like the boss battle idea. Would be trickier to do on the random generated levels of course but I don't see it being too bad on the fixed world. My preference would be to have several of them throughout the game, maybe on every 4th of 5th level, perhaps beating them is how you get your rocket ship piece?

To this end it could be interesting to make the elevator only appear once you have defeated every enemy on a level? Would need a way of always being able to attack them of course, maybe giving the player tomatoes by default when they don't have an active present. Perhaps removing Pause (the game pauses when the map is open anyway) and using Start to toggle to sneak between tomatoes and sneaking.

Second idea is cool as well and could make for some interesting game play. Don't know if instant wings would make a big difference since they are player controlled anyway but instant tomatoe rain or rocket skates could certainly shake things up a bit!

[RyanfaeScotland]

Progress Report 2

Date: 04-Mar-2016
Current Goal: Create a complete disassembly, without annotations, which compiles into a ROM identical to the original.
Complete: 5%

Well I've made progress but not in the areas I had planned.

I've found that progress is steady but there are still areas of the process that are slowing me down dramatically, the main one being updating my website with newly gained information.

As my site is a largely static site (i.e. no content generated on the fly) updates to it take a considerable amount of time to perform, especially with the amount of mark-up and formatting the ROM information sections contain. As a result I've been looking into ways to make the process of updating easier. Rather than make the changes on the website side I opted to address the issue at the disassembling point.

To this end I've created myself a simple tool that reads my disassembly notes (that are now marked up via XML) and can spit out some HTML based on them. I intended to continue this through to get the program to spit out exactly the HTML I need for my site so that I can copy and paste it in and have the update completed in a fraction of the time but then I had a thought: Why have the program work on my disassembly notes when it could work directly on the disassembly?

So now I'm spending some time looking into making a cleverer disassembly program. It's still mostly an idea at the moment but playing around with the concept of creating a tool that can look at a games disassembly and combine the data from there with trace files to try and output more legible code, perhaps even re-assemblable (although that is more of an end goal).

It's a shame I haven't looked at more of the actual game code but I'm hoping creating a program to aid the process will pay dividends in the long run.

[PresidentLeever]

For gameplay changes, the things I can think of right now is removing the randomizer (alternatively making identification cheaper) and making all movement a bit faster and more responsive, including for example the bounce animation after falling down and earl picking his pants up (or remove this feature). There's actually a movement speed GG code but 2x seemed a bit much.
If possible you could also make discovered stuff like warp doors, food, presents and mail boxes also show on the game's map screen to make exploration more convenient.
Perhaps some of the dead space, which there's a lot of, could be removed/filled with stuff by tweaking the randomization of the maps?
Finally, and I don't have any concrete ideas for it but I think the build-up to the last ship piece could be made more climactic somehow.

Some things could also be done with the music in terms of sound quality; it barely ever uses all FM channels, no PSG channels that I'm aware, and rarely uses sampled drums for some reason. As a side project inspired by a Sega-16 thread I've made a few remakes of MD tracks that could sound better; https://www.youtube.com/user/Alianger/videos.
If they could be inserted it'd be interesting to remake some or all tracks from TJ&E and I'm pretty sure others would join in on such a project. Maybe some sequel tracks could be included too?

Graphically I'm not sure how flexible the engine is, it seems rather basic, but it'd be nice to see the game look more on par with the sequel. 

"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?"
I really like this idea!

Anyway, good luck with your project.

[TheUnderfaker]

What I'd love to see is maybe a small remake of TJ&E2 with the Funkotron planet art from the last level.

The 2nd game was originally supposed to be just like the first one, but on Funkotron.

[Bawchee]

Oh I am so excited for this!  My wife and I play this game every now and then (that may be a bit of an understatement).  We just started wondering if anyone would have hacked this game to offer some variety.  I am so stoked at what the potential from your work could produce!  More levels would be great!   Or a level builder!  I appreciate you and your work!

[RyanfaeScotland]

Progress Report 3

Date: 01-Nov-2016
Current Goal: Create a complete disassembly, without annotations, which compiles into a ROM identical to the original.
Complete: 5%

I returned to this recently after a bit of a break and have turned my attention back to mapping out the RAM and how it is used throughout the game. I've managed to get quite a bit of interesting things figured out such as where all the level data is kept (as in item placements, presents, dropped presents, enemy locations and so on) and am currently looking at the level layout which I've managed to pinpoint but now just need to get the specifics of which value results in which map tile. Not too challenging to do but a little time consuming.

Thankfully during this process I've discovered Lua and the power it provides to quickly change memory values in-game which saves a lot of the time that was previously spent creating a savestate, opening it in a hex editor, editing a value, saving, reloading. Now I just set a given memory address to increase on one button press, decrease on another and I can tweak the memory values from my controller in game! Very handy!

However I think my most important discovery to date, ignoring the dull full enemy, present and level layout, has to be the discovery of how to make tomatoe rain last forever! Certainly adds a new element of challenge!

I'm thinking soon I'll look at documenting the specifics of a present, likely Rocket Skates. I'd really like to know where it's timer data is grabbed from, how does it disable the presents menu from showing, how does it stop you entering elevators, how does it speed you up and all sorts of other things. Thinking about it though I might instead start with Rose Bushes or something with a little less impact on the player. Finding out how to lay 10 rose bushes instead of 1 could be interesting, right?

[altoiddealer]

Exciting 

More hack ideas (I know it's not what you're doing):

Maybe you could figure out how to make an item similar to rocket skates, but where you can fly over the empty space.

A "race mode" to race TJ vs Earl with segments involving rocket skates, flying, swimming, pogo, etc.

Figure out a means to (store) mail presents to yourself via mailbox

Keep up the good work!

[RyanfaeScotland]

Exciting 

More hack ideas (I know it's not what you're doing):

Maybe you could figure out how to make an item similar to rocket skates, but where you can fly over the empty space.

A "race mode" to race TJ vs Earl with segments involving rocket skates, flying, swimming, pogo, etc.

Figure out a means to (store) mail presents to yourself via mailbox

Keep up the good work!

These are brilliant, rocket skates over space shouldn't be too tricky and would make for a great early goal.

The mailbox is a very elegant solution to the issue I was wondering how to tackle whilst playing through for the billionth time last week, how to best store good but currently unwanted present for future levels. Best tactic I could think of in the current game is offloading them near the elevators but a tweak to allow them to be stored in the mailbox, perhaps for a small fee, would be very cool.

Keep'em coming!


Oh, as an aside I spent a little more time today on peripheral tasks and got Notepad++ setup with syntax highlighting and code folds for 68K which means I no longer have to take notes in XML which was stupid. Now I can code and note in one place, saving a lot of time and duplication.

[altoiddealer]

-Change the way you earn promotions?  A point system, instead of step counter?

-Terrain graphics such as space station level, shopping mall, etc.

-Walls / barriers.  Like if you could place a row of trees, but have it not be a row of trees.

-See what triggers something to boombox dance, and see if you can figure out how to make otherwise inanimate objects dance like palm trees, etc, or Santa (does he dance?) to sneak up on him easier?

-Make spring shoes always full sprooooing every single bounce - no input necessary, and also no butt bounce

-Make it so bees can sleep like other enemies... in a beehive?

-Make it so tornadoes can pick up certain enemies, and drop them randomly or just cause damage by bumping you (and dropping them in the process)

-Ship piece on all levels / no duds

-"Mushroomized" item effect (like in Earthbound) - inputs temporarily register as other directions. Cupid does this, doesn't he? 

-Jackhammer enemy like in TJ&E2 - we know there is a "vibrate" behavior because it occurs when opening instant death present.

-Status effect from insane dentist needle

-Custom anim with specific item equiped, like tomatoes casually toss it up, catch it, repeat?

-NPCs that just say something funny, or drop an item or give a hint (again, like TJ&E2).

-Make an NPC high-fiveable.  Or see if the same thing that triggers high five, can trigger pressing a standing button (like TJ&E2) that does something random.

-Side questing other items for a special ending or other unique rewards.

-Cameo from the great funkopotomus

-Funk teleport / funk abilities.

-Telephones quieter when further away, so you know you are getting warmer.

-Enemy that causes burping.

-Quicksand.  Sink too deep, you fall through to level below.

I'll pop in if I get any other ideas.  Always cherished this game so I'm excited to see it getting hacker attention

[RyanfaeScotland]

Progress Report 4

Date: 19-Jul-2018
Current Goal: Create a complete disassembly, without annotations, which compiles into a ROM identical to the original.
Complete: Unknown (My newest way of calculating says 30% but that seems a lot! Probably nearer 10%)

This continues to be a great project, I've learnt heaps about assembly, LUA Scripting and Megadrive development in general since I started and have even created what I consider to be a pretty slick development set up.

I'm now using Visual Studio Code for writing the 68K ASM, I have the code split out into multiple files rather than one single goliath one. I've got the rebuild process down to about 4 clicks (save changes in VS, switch to Easy68K, build the master file, switch to EasyBIN, reload the generated Master S68 file, click save as binary, done!) I still want to automate the part for updating my ROM Memory Map but will do that on a rainy day when I fancy a change of pace. I've also completely dropped the whole separate notes / XML thing opting instead for comments in the ASM files which makes a lot more sense in so many ways.

Disassembly wise things are progressing well as well. You can see a visualisation of how much I've disassembled here: http://www.mybrillgamesite.com/rawHTML/TE_ROM_MemoryMap.html (and keep in mind a lot of these sections point to other sections that I haven't got round to exploring yet.)

Recently I've worked out:

• From power on, how the game decides what screen to show you (i.e. SEGA screen, intro video, setup menu or main game).
• Each of the places the game checks what present you are opening from your inventory (this is a big one as it basically sign posts the way to working out how each present works).
• Lots of details about Tomato Rain including how it decides how long it lasts for (it's a count of 'rained' tomatoes, not a timer!) and how frequently it rains a tomato.
• I now know how to use CONSTANTS in assembly and use them to track RAM addresses which makes the code a lot more readable and understandable.
• A little bit about how the initial menus work (like which option is currently selected) (this will be important later as I want to create my own menu for setting in game options).

And that's about it for now. I know progress is slow but it continues to be an enjoyable background project around Real Life™. I think next I'm going to have a bit of a sprint on getting as much code as possible buildable, even if it isn't understood yet. Having the whole source code re-buildable would be a huge achievement, even if it is messy.

I'll be back when there is more to report.



Thanks @altoiddealer for the cool list of ideas, sorry I didn't see them sooner! Changing how promotions are earned is definitely on my todo list! I think at the very least killing enemies should earn you points. I really like the quicksand one as well, should be fairly straightforward to do (When it is detected that you can't sink anymore instead of just 'not sinking' jump to the same routine that runs when you fall off the level).

Keep the ideas coming folks.

[RyanfaeScotland]

Progress Report 5

Date: 13-Mar-2019
Current Goal: Create a complete disassembly, without annotations, which compiles into a ROM identical to the original.
Complete: 100% (Yup, 100%!*)



Here we finally are. 3 years, 1 month and 17 days after my initial post of this project and I have just successfully compiled an assembly that builds into an exact replica of the original Toejam and Earl game on the Sega Megadrive!

I can't believe it! I really can't believe I've completed* it! No additional files needed, just Easy68k and a directory full of source files and you're off. 

*Ok, now for all the caveats. The source is a mess! Of course it is, it's my first project of this scale! In the last update you'll see I got fed up working essentially line by line to work out what everything does whilst decompiling. It was taking forever to make progress and I really wanted to have the ability to compile the complete ROM without having to patch the existing one as well. So I decided upon a new approach, I got Exodus working and I played around with it and the Active Debugger functionality for a while. After some crashes, some trial and error and a few posts on its forum I managed to get a fairly reliable process for creating a disassembly file. I followed this process and created a file 578,020 lines long and I then started splitting this file out into 10,000 line chunks which could be assembled, compared against the original ROM and fixed as needed.

What I didn't realise at the time though is that this 578,020 line file went all the way up to address 00FFFFFF, that's an extra F on top of the original file size!! So in my last update when I calculated I was about 30% through I was probably right! And sure enough, when I checked address 000FFFFF I found the assembly generated would match the output in the end of the ROM. Reinvigorated I've basically spent the last 4 days ploughing through 10,000 line after 10,000 line to get it all in and adjusted and I'm finally there! Sure, I've got 7 or 8 files just marked 'Unknown Code.x68' but what the hell, they are there, they compile, and now I get to have the fun of working out what they do.

[danke]

Congrats! Keep it up!

[altoiddealer]

I found myself thinking about this project recently, and just did a search now and am very pleasantly surprised to see you are still going at it, and making big progress!

Congratulations!  As a user (non-hacker) and TJ&E enthusiast, I'll always be looking forward to what comes from this!

[RyanfaeScotland]

Random Update

And just like that, the first hack is a reality!



It isn't much, more a proof of concept than anything, but there is a few palette swaps, some damage changes, some changes to the starting presents and a little tweak to the logic for what presents are identified so there is a few bits and bobs in there.

Feel free to check out the short video that goes into a bit more detail: https://www.youtube.com/watch?v=eGYistHOCsc.

Hey @altoiddealer, cool to see you still checking in. 

[RyanfaeScotland]

Progress Report 6

Date: 20-May-2019
Current Goal: General exploration, commenting, RAM address identifying.
Complete: Unmeasured, progressing well though.

The code is now public in the BitBucket repository here: https://bitbucket.org/RyanFaeScotland/toejamandearldisassembly

It's finally public but that doesn't mean it is finally beautiful, clean, well documented or any of the other things you might want your code to be before releasing it into the wild! But I have a lot of Real Life (tm) going on so wanted to get this out there for others to enjoy as well rather than just hoarding it until I was finished / 100% happy with it. Let's just say I'm now at a point where I'm happy enough for it to be available to all!

I'm still going to be plugging away at it of course, so expect on going updates as I progress to the beautiful version I hope to one day make.

[RyanfaeScotland]

Progress Report 7

Date: 30-June-2019
Current Goal: General exploration, commenting, RAM address identifying.
Complete: Unmeasured, progressing well though.

I've been chipping away at the code and making a lot of progress over a wide range of areas. I attribute most of this progress to the decision to start working out RAM addresses and then using Visual Studio Code to rename the given address throughout the source to something meaningful. This works great, not only do you have something more meaningful than LOC_00FF1234 to go on but you can also see clearly the code that interacts with the values, making it much easier to group related code together.

However, that's not what compelled me to write this progress update, what did is the milestone I past last night: extending the ROM to contain custom code!

It wasn't much, but after a passing comment by Malias about adding code I figured it was something I'd always been interested in and that the codebase was probably in a good enough state to give it a try.

So I did!

Here is the original code that sets Toejam's initial presents when the game loads:

Code Select Expand

ToejamInitialPresents:
NOP                     *Adds to Toejam's inventory, 4 on single player, 2 on 2 player.
ADDQ.L    #$4,A7
MOVE.B    #TOEJAM_INTIAL_PRESENT_1, (A2)
MOVE.B    #TOEJAM_INTIAL_PRESENT_2, $0001(A2)
TST.B     EARLS_LIVES
BGE.B     EarlInitialPresents
MOVE.B    #TOEJAM_INTIAL_PRESENT_3, $0002(A2)
MOVE.B    #TOEJAM_INTIAL_PRESENT_4, $0003(A2)

In a previous update I tweaked this to set a few more presents by condensing the code a little and removing the TST.B:

Code Select Expand

ExtraInitialPresents:
MOVE.B    #$05,(A2)
MOVE.B    #$05,$0001(A2)
MOVE.B    #$05,$0002(A2)
NOP
MOVE.B    #$05,$0003(A2)
MOVE.B    #$00,$0004(A2)

This kept the code the same size but gave 5 presents every time instead of the usual 4 on 1 player and 2 on 2 player.

However, last night I wrote my own code at address $100000 (the end of the ROM) which set all 16 present slots to the first 16 possible presents and then I rewrote the original code to jump to it. Since I want to keep the original files building to the original game I created a brand new file and put my code in there using an ORG statement to place it at the end of the ROM. The same technique was used to overwrite the original present setting code with the JMP to my new code.

Code Select Expand

ORG $00100000
CustomPresentSetting:
MOVE.B    #ICARUS_WINGS, (A2)
MOVE.B    #SPRING_SHOES, $0001(A2)
MOVE.B    #INNERTUBE, $0002(A2)
MOVE.B    #TOMATOES, $0003(A2)
MOVE.B    #SLING_SHOT, $0004(A2)
MOVE.B    #ROCKET_SKATES, $0005(A2)
MOVE.B    #ROSE_BUSHES,   $0006(A2)
MOVE.B    #SUPER_HITOPS,  $0007(A2)
MOVE.B    #DOORWAY,   $0008(A2)
MOVE.B    #FOOD,   $0009(A2)
MOVE.B    #ROOTBEER,   $000A(A2)
MOVE.B    #PROMOTION,   $000B(A2)
MOVE.B    #UNFALL,   $000C(A2)
MOVE.B    #RAIN_CLOUD,   $000D(A2)
MOVE.B    #FUDGE_SUNDAE,  $000E(A2)
MOVE.B    #DECOY,   $000F(A2)
RTS

ORG $0001435C
NOP
JSR CustomPresentSetting
ADDQ.L #$4, A7
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
NOP

Notice I had to keep the ADDQ.L    #$4,A7 line outside of my custom code. This line increases the stack pointer, A7, by 4 and you can't do this from within the jump to my new procedure since jumping to it sets the stack to point back to where we jumped from. Adding 4 to there will just make us jump back to the wrong place so we need to do it at the original level.

The other, slightly more standout thing, is all the NOPs that have been added in the place of the original code. This is because although we no longer need the original code we do need the memory space it takes up so adding NOPs is the safest way to still use that space whilst having minimal effect on the game state (it can affect processor timings but only testing will reveal if it is an issue or not).

So that's it! A pretty awesome milestone to pass and opens up a lot of possibilities for the future.