This is my attempt at reverse-engineering Epyx's Jumpman Junior cartridge
for the Atari 800/XL/XE computers.
The end result of this will be fully commented & documented source code
for the game. I'm about 2/3 of the way there now, I think.
The source is in the file "jumpmanjr.dasm" [1]. It's generated by da65 [2],
and it can be assembled with ca65. At some point, when I've finished
mapping out the entire ROM, I'll be editing the source to make it more
human-readable, but for now da65's output will do.
If you just want to read the code, jumpmanjr.dasm and a text editor is all
you need... or, a web browser pointed at:
http://urchlay.naptime.net/repos/jumpmanjr/plain/jumpmanjr.html
There are also a few text files with notes about the various data tables
in the games, which will eventually become comments in the code, once
I stop needing to use da65.
There's also a cheats.txt that will explain how to use the atari800
debugger to give infinite lives, warp to a different level, etc. This
is useful for reverse-engineering the game, but it might also be fun
just to mess with...
If you want to modify the code or help me document it, see the
Makefile. You'll need:
- cc65, the 6502 cross-compiler suite. I use a git version from December
30 2015, but other versions should work fine.
- a 'make' utility. I use GNU make, but BSD make should work fine as I
don't use any of the GNU extensions.
- perl. I use v5.22.2, but any recent 5.x should work.
- A UNIX-ish environment (at least sh, echo, cp, mv, cat, true, and
sed). Linux is what I use, but there's no reason you couldn't use BSD,
OSX, Cygwin, etc.
- If you want to assemble your own (possibly) modified Jumpman Junior
ROM, you'll need a way to run it. I use the Atari800 emulator. Other
possibilities would be Atari++, Altirra (Windows or Wine only),
MAME/MESS, or running on a real Atari via some sort of flash cartridge
(or an old-school EPROM). If you're going to be modifying the ROM
or helping me document it, you'll want an emulator with a debugger.
- If you want to regenerate the HTML version of the source, you'll need
a recent version of vim and some patience (it takes over a minute to
generate, on my system). Also if you want the background to be black
like the jumpmanjr.html in the source, you'll have to edit 2html.vim...
Most of the above should be available as distro packages for any flavour
of Linux, with the possible exception of cc65 (which you can compile
easily enough).
If you come up with anything that should be added to the project, send
me your patch (preferably made with "git diff") to yalhcru@gmail.com. No,
I don't have a github/bitbucket/whatever account, email is fine.
The workflow I use is basically this:
1. Load main.info, mklevelinfo.pl, and jumpmanjr.dasm in a text editor.
2. Eyeball jumpmanjr.dasm, cogitate, and figure out what some bit of code
actually does. This may also involve running the game in the
emulator (via 'make test') and pressing F8 to get to the debugger [3],
and dumping/changing memory, etc.
3. Edit & save main.info and/or mklevelinfo.pl. There's no point in
editing jumpmanjr.dasm itself, it's a generated file and any
changes would be overwritten.
4. Run 'make' (this is bound to the F9 key in my .vimrc), to regenerate
jumpmanjr.dasm with your new labels/comments/etc. Reload jumpmanjr.dasm
in your editor buffer, if you need to (depends on the editor).
5. GOTO 2
Also, another useful thing: in step 2 above, it's useful to try changing
parts of the code (or data tables) to see what effect it has on the game.
The way I do this:
1. Run 'make', which creates jumpmanjr.dasm and also copies it to
jmjtest.dasm.
2. Edit jmjtest.dasm as desired. Be careful: running 'make' (or 'make
all') again will overwrite your modified jmjtest.dasm with a copy of
jumpmanjr.dasm... but it'll rename the old one to jmjtest.dasm.bak
first, so you can recover from a simple mistake.
3. Run 'make test', which assembles jmjtest.dasm to jmjtest.bin and launches
it in the emulator [3]. If you've modified jmjtest.dasm, you can ignore the
'Binary FAILS to reassemble correctly' message (since you already know
your modified one isn't going to match the canonical one).
4. Play with it, see what happens. If you discover something useful, add
it to main.info and/or mklevelinfo.pl.
Official XKCD comic of this project: https://xkcd.com/1349/
Notes:
[1] If you're wondering about the .dasm filename extension: ca65's standard
extension for asm source is .s, which is also used for x86 and x86_64
asm. I use vim, and its syntax highlighting for .s is terrible for
ca65's syntax... so I wrote a 6502-specific syntax definition. Back
when I did that, I used Matt Dillon's DASM (hence the .dasm)... but
the syntax mode works fine for ca65 also, and ca65 doesn't care about
the filename of its input (cl65 does care, but I'm not using it for this
project). You can think of .dasm as being short for "disassembly" if you
like.
[2] da65 is a very powerful and flexible disassembler, but has some
limitations that make it impossible to just use its output as the
final product. For one thing, no multi-line comments. Also, no comments
without a label... and comments always precede the line they're a
comment for (no way to place them in the right margin like usual 6502
assembly style). And for this project, you'll notice a lot of labels
with names like "foo_minus_one", because the Jumpman Junior author used
1-based indexing (with DEX, BNE to check for loop exit), meaning instead
of writing "LDA foo,X", he would have written "LDA foo-1,X" and
initialized X to the actual table size instead of the size minus one.
I can't find a way to make da65 produce negative label offsets...
[3] You can use labels from the source code in the atari800 debugger, if
you enter "load labels jmjtest.lbl" at the debugger prompt. The
Makefile will print this for your copy/pasting convenience, but I
don't see a way to have atari800 automatically do this (short of
modifying atari800, which is a project for another day).
