add README and jumpmanjr.html

1 files changed, 104 insertions, 0 deletions

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