update README, add cheats.txt

2 files changed, 92 insertions, 10 deletions

diff --git a/README b/README
index 660257f..3054893 100644
--- a/README
+++ b/README
@@ -4,7 +4,7 @@ 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,
+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.
@@ -18,6 +18,11 @@ 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:
 
@@ -37,7 +42,8 @@ Makefile. You'll need:
   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).
+  (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
@@ -48,21 +54,28 @@ 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 [2],
+   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.
+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.
+   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 1
+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.
@@ -77,7 +90,7 @@ The way I do this:
    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
+   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).
 
@@ -94,9 +107,21 @@ Notes:
     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
+    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
diff --git a/cheats.txt b/cheats.txt
new file mode 100644
index 0000000..71234e2
--- /dev/null
+++ b/cheats.txt
@@ -0,0 +1,57 @@
+
+All these cheats assume you're running atari800 built with debugger
+support. To get into the debugger, load the game normally, then press
+F8. After making changes in the debugger, give the "cont" command to
+get back to the game.
+
+If you're using some other emulator besides atari800, see its
+documentation for how to enter/exit its debugger, and how to change
+memory (the "c" command in atari800). Specifically, don't ask me,
+'cause I don't know :)
+
+Infinite Lives
+--------------
+Well, 200 lives, anyway. Start the game, wait until the intro music
+is done and Jumpman has finished materializing, then press F8. In the
+debugger:
+
+c 70a c8
+cont
+
+The game will still display 3 lives, until you get killed the first
+time. Then it'll display a bunch of lives with a + next to them.
+
+The "c8" can actually be up to "ff" (255), but if you ever get over 255
+lives (due to getting extra lives), it'll overflow to zero and the game
+will be over the next time you get killed!
+
+If you start running low on lives, you can use this cheat again.
+
+Warp to Level
+-------------
+To start the game on a particular level, press F8 at the "Player #1
+Speed?" prompt. In the debugger:
+
+c 6f6 3
+cont
+
+The number you enter is the level number minus two. In the example, the
+game starts on level 5 (Figurits Revenge). Remember the monitor uses hex,
+so use "a" for 10 (which will start on level 12). For level 1 you'd use
+"ff" (aka -1 in twos-complement). Entering "b" (for the nonexistant
+level 13) will take you back to the "Number of Players?" prompt. Any
+other invalid level will make the game lock up when it starts.
+
+This cheat also works during a level, but it won't take effect until
+you finish the level you're currently playing.
+
+Random Levels
+-------------
+This is like the randomizer mode in the original Jumpman. At the "Number
+of Players?" or "Player #1 Speed?" prompt, press F8, then:
+
+c 6f3 1
+cont
+
+This cheat also works during a level, but it won't take effect until
+you finish the level you're currently playing.