From c35d85e5b1a014193ecc34a249e5a20aed729779 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Mon, 29 Aug 2016 19:49:06 -0400 Subject: add README and jumpmanjr.html --- README | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 README (limited to 'README') diff --git a/README b/README new file mode 100644 index 0000000..660257f --- /dev/null +++ b/README @@ -0,0 +1,104 @@ +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, +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. + +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 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). + +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 [2], + and dumping/changing memory, etc. + +3. Edit & save main.info and/or mklevelinfo.pl. + +4. Run 'make' (this is bound to the F9 key in my .vimrc), to regenerate + jumpmanjr.dasm. + +5. GOTO 1 + +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 [2]. 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] 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). + -- cgit v1.2.3