Super Mario Bros. Meta-Disassembly

[segaloco]

Got another iron in the fire: https://gitlab.com/segaloco/smb

I started working up a disassembly of plain old Super Mario Bros. so I'd have code to compare for my real goal: a code-flow analysis between Super Mario Bros. and Doki Doki Panic (and SMB3 if I get to it).

After seeing some chit chat concerning All Night Nippon Super Mario Bros. and some other stuff, I decided to take what I had kinda half-assedly clobbered together and put some polish on it, producing the start of a repository containing one code-base that builds into all four Super Mario Bros. variants: the Famicom title, the FDS reissue, Super Mario Bros. 2, and All Night Nippon. The process isn't too different from what I've been doing with other stuff, although it technically started as straight Famicom only, so the other three streams have a bit of catchup to do. In any case, it's mostly just looking at the PRG bank for each title side by side, seeing where the few differences are. Of course, I'm not sussing everything out with a magnifying glass, a quick pass like that and then through the assembler, some diffing, and anything that gets missed gets picked up in that pass. In any case, it's proving to have a nice flow to it just like working with a single binary file.

Some advice if you truly want to play around with this (there ain't much there yet...I've been focused on the logistics of a 4-way build system that isn't a nightmare...):

First, extracting assets requires using the various scripts provided. There's one for each title, and they all expect "headered" images, so iNES for the Famicom title and "FDS" for the Famicom Disk System images. I've seen FDS games distributed both with and without headers. In the latter situation (indicated by the first 16 bytes of the image including something like NINTENDO-HVC) you really just need to pad the beginning with 16 bytes before shooting it through an extraction script, the script doesn't care about the header, just the padding. Each script is geared towards a particular title, as such, running them all may present some redundancy, as for instance the CHR between the Famicom and FDS versions of Super Mario Bros. are identical.

The Makefile expects to build the Famicom version by default. As such, it provides the necessary ASFLAGS for this version. I have not settled on precisely how I want to handle this in the Makefile, nothing portable has presented itself thus far and manually adjusting the added ASFLAGS when testing other builds isn't a hastle, much less than producing something that won't work when I inevitably switch back to FreeBSD or give illumos another spin or whatever. Maybe the subset of make(1)s between them support a common ifdef system...but meh it ain't in POSIX. Anywho, to get the other builds, replace the ASFLAGS_FC inclusion near the top of the makefile with the appropriate set, all four should already be present there. In addition, be sure to issue the name of the correct output, currently the iNES ROM is the default make rule.

So basically, to build All Night Nippon Super Mario Bros. with this repository:

- Run the necessary extraction script on a 16-byte-headered ANN FDS image
- Replace ASFLAGS_FC with ASFLAGS_ANN in the ASFLAGS assignment in the Makefile
- Issue "make ann.fds"

The preprocessor defintions serve a few purposes. Some section off code particular to a given title. Others section off platform or revision specific code, the latter mostly referring to the dichotomy between the two issues of Super Mario Bros. vs ANN and 2. The latter two are on the later version of the engine while the former are largely identical save for FDS differences required in the transportation to the disk system.

This project is not my top priority right now, and I am uploading it quite early in the process. As such, it probably won't be useful for quite a while, but I wanted to both get it up online so I don't lose it in some tragic accident and get an example of this sort of thing up that I can point to when explaining some of the variations between straight Famicom and Disk System stuff, different bank-based building approaches, shared code stuff, etc. Ultimately though, my personal use for this is to have a source of comparison with Doki Doki Panic. Being able to trace key design and code elements between the two is my central goal here.

[segaloco]

Just a little bump to note that I've incorporated Vs. Super Mario Bros. into this disassembly as well, I'm just about caught up with the other streams, just working through the level end and general screen routines, then what's there thus far should have parity across versions, at least as far as the ordering in the binary is concerned (meaning the title stuff isn't done for SMB2/ANN as it has been relocated in the binary.) I'm glad they all seem to come from the same underlying design, it'll be nice to have a single point of truth on precisely what was different between versions, plus, it might make producing Vs. Super Mario Bros. 2 pretty trivial...but that's not something I intend to work on, just something I hope someone's able to draw from this work someday when it's done.

[Pokun]

they all expect "headered" images, so iNES for the Famicom title and "FDS" for the Famicom Disk System images. I've seen FDS games distributed both with and without headers. In the latter situation (indicated by the first 16 bytes of the image including something like NINTENDO-HVC) you really just need to pad the beginning with 16 bytes before shooting it through an extraction script, the script doesn't care about the header, just the padding.

Yeah many emulators doesn't require the header of the FDS format since it is quite redundant as it mostly only is used to tell how many disk sides there are. And since the FDS format uses a fixed file size that only changes with the number of disk sides the game has it is easy to figure out without the header.
Nintendulator (the original) requires the FDS header while Mesen can take either variant IIRC.

[segaloco]

I've just reached an important milestone on this project, which can still be found here:

https://gitlab.com/segaloco/smb

This repository should now feature all content from Super Mario Bros., including the PAL and FDS releases, as well as Vs. Super Mario Bros. There are plenty of bits of the latter I haven't thoroughly documented yet, but the code is at least there. I still have pieces of SMB2 and All Night Nippon to work through (namely the data2, data3, and data4 PRG banks) but as far as the original release, it should be fully disassembled.

This all constitutes the first pass at this, so there is certainly still much to do including documenting constants, ensuring commentary is accurate, and verifying that there is nothing left that depends on any sort of hard-coded address or assumption about indexing. In addition to avoiding hard-coded addresses, I've also in many places defined indices as a function of the collections they describe, for instance the various notes in the APU engine are gathered in an enum that refers to the label on each note, such that modifying the note table should be relatively simple. Anything in the song data pointing at a particular note should still point at that particular note so long as it isn't deleted or moved outside of the allowable values. Not every single collection is indexed this way, but that is an eventual goal in the second phase such that dropping new items into lists or moving code around should be largely intuitive, of course keeping limits and locality in mind.

I've been really pushing on this one to get to this point, and as such I now intend to take a little break, maybe work on some other projects, before getting back to the bits of SMB2 and ANN that aren't done yet.

The information in the README should be reasonably complete as far as how to actually work with this. I haven't done any further analysis on how easy this is to modify yet, so there could be a pointer somewhere that gets misaligned if you start moving things around. If any of you do decide to pull this down and play around with it, I would certainly appreciate feedback on things that get out of whack, as that's probably indicative of a pointer or index somewhere that isn't keeping up with where the actual code is moving around to.

Just to detail work that remains before I consider this "done":

- Disassemble data2, data3, and data4 PRG files from both SMB2 and ANN
- Incorporate code changes relevant to the Nintendo World Championships 1990 version
- Likewise at least add some conditional code pertinent to bundled versions (i.e. I don't really intend on disassembling Duck Hunt...yet...but could at least ensure this repo includes ifdefs towards the end of building the SMB side of a SMB/Duck Hunt cart)
- Assess inclusion of any pertinent PlayChoice-10 stuff.

The SMB2/ANN stuff is the most important, the others just aim for completeness in demonstrating every little augmentation this engine absorbed over the course of its use by SRD/Nintendo.

Finally, I want to thank all the folks at SRD and Nintendo for the work they put in so many years ago to create this and many other memorable titles. Super Mario Bros. is a technical feat warranting this and more praise, and I hope that the work I've done here helps folks appreciate just what sort of technical limitations they were up against and all the clever ways they got the job done.

Have fun, make cool things!

[tepples]

Once you finish this disassembly, how hard do you think it'd be to port the game to UNROM, for one ROM encompassing all courses from SMB, SMB2, ANN, and a port of SMB Special to the SMB engine?

[segaloco]

I think the changes to support more than 8 courses in SMB2 provide a template for supporting an expansive collection. Working in a mapper shouldn't be too prohibitive, iirc some SMB level editors convert the original to MMC1 mapping, so theoretically it's doable. There's also the prospect of just adding further BLOBs to the FDS version, give or take disk swapping code.

SMB Special is an interesting idea. I don't know enough about it to say one way or another, but that would also entail porting in a host of new objects. The Special version is also for Z80 computers, so it wouldn't be just extra code to forklift from one 6502 engine to another. I do find myself curious how similar they are in operation under the hood. That could be a cool cross-examination to perform...

[tepples]

On the other hand, SMB Deluxe and SMB Special are both for machines with 8080-family CPUs. You just made me curious how much structure they share or don't.

[segaloco]

Yeah I've been thinking the exact same thing...whether Nintendo would've tried at all to start with the code from Hudson or rolled Deluxe from scratch. Either way, I did start tinkering around with what disassembling a PC-8801 title looks like and thus far have a CLI utility for extracting the disk sectors. Next is the filesystem and then pouring over docs to figure out where things get loaded. Are you aware of any existing work on Super Mario Bros. Special? That would certainly give me a leg up on the feasibility analysis. Aside from porting objects unique to that title, there's also the possibility that the level data itself isn't necessarily formatted comparably. This is a cool next direction to look in though, I'm glad you brought it up tepples!