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.

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