(back to top)

Working with the MAME Debugger

MAME includes a debugger that has a lot of useful features but can be a little obscure at times. In what follows I assume you already have the game set up and working.

The first thing to do is start MAME with the debugger enabled. The easiest way to do this is from the command line. Pick your favorite shell; Windows PowerShell (Win+R then "powershell") works fine. Use cd to change to the MAME directory, then run the program, adding the -debug flag:

to start into the GUI, or:

to start the game "bzone" directly.

When you start a game, it should come up windowed rather than full-screen, with an additional "debug" window on top. The game will pause before executing the first instruction to give you an opportunity to set breakpoints. There is a line at the bottom of the debug window where you can type commands; the first one you should use is "help".

If you want to see an example, this video demonstrates launching Missile Command and editing values in memory to jump to wave 255.

Some Handy Things

The debugger has many features. These should get you started.

• Continue execution with F5, or by typing the command g (followed by Enter) in the command-line interface.
• Stop execution at any time by hitting tilde (~) in the game or debugger window, or a single-step command like F10 in the debugger window. (Hitting P in the game window to pause the game will also freeze the debugger, so don't use that.)
• F10/F11 are the basic single-step keys. F10 is "step over", F11 is "step into", and Shift+F11 is "step out", i.e. run until the next RTS/RTI.
• Various other windows are available from the Debug menu, notably windows for breakpoints and memory display (hex and disasm). The memory windows update every few frames.
• You can hex-edit values in the memory window directly, by clicking on a byte and typing values. By default this only works for RAM.
• Set an execution breakpoint with bps <address>. It will assign the breakpoint a number. You can clear it with bpc <#>, or just type bpc to clear all breakpoints. You can also set memory address watchpoints; type "help wps" to see the options available.
• Change register values with the "do" command, e.g. "do a=1f" will set the 6502 accumulator to $1f.

• If you hit F10 in the game window you will disable the frame-rate throttling and the game will run at high speed. Just hit it again to toggle throttling back on. (This actually comes in very handy if you want to "fast forward" the game.)
• The F12 key performs a screen capture in the game window. If you hit it in the debug window, it grabs the screen and then hides the debugger. Use ~ to get the debugger interface back.

Modifying ROM Locations

When disassembling code it's sometimes useful to modify the code to see what effect it has. For example, if a chunk of code is doing something with a sound effect but you're not sure what, you can tweak or disable it and then observe the change. If you try to do this from the memory window you'll find that it doesn't work.

The trick is to change the "Region" pop-up in the Memory View window from the default to "Region ':maincpu'". Once you've done this, you can edit ROM values directly.

Using the Cheat Engine

If you're going to be doing something often, you can use the "cheat engine", which can modify and restore small sections of ROM from the menu. The following uses Battlezone as an example. MAME looks for Battlezone files in a directory called "bzone", e.g. the ROM files are in roms/bzone. Cheat descriptions are stored in a directory called "cheat", in XML documents named after the game, so we need to create a file called cheat/bzone.xml.

1. Start in the MAME installation directory.
2. Create a directory called cheat if it doesn't already exist.
3. Create a new text document with the game's short name (e.g. cheat/bzone.xml).
4. Edit the file with your favorite XML editor (I use vim).

We want to define changes that can be done and un-done from the cheat menu. Here's a cheat file with two entries:

<mamecheat version="1">
  <cheat desc="No Volcano Update 58BA">
    <script state="on">
      <action>temp0=maincpu.mb@58BA</action>
    </script>
    <script state="run">
      <action>maincpu.mb@58BA=60</action>
    </script>
    <script state="off">
      <action>maincpu.mb@58BA=temp0</action>
    </script>
  </cheat>

  <cheat desc="No Volcano Draw 5824">
    <script state="on">
      <action>temp0=maincpu.mb@5824</action>
    </script>
    <script state="run">
      <action>maincpu.mb@5824=60</action>
    </script>
    <script state="off">
      <action>maincpu.mb@5824=temp0</action>
    </script>
  </cheat>
</mamecheat>

This adds two very similar entries to the cheat menu. Each of them when switched on will save a one-byte value from the specified address to a local variable called "temp0", then will replace the byte with $60 (RTS). When switched off, the original contents of the memory location are restored. (These two items disable movement of volcano particles, and rendering of volcano particles, respectively.)

To use the "cheat", add the -cheat flag to the command line when starting MAME:

./mame -debug -cheat

Or in the UI front-end, select "Configure Options", then "Miscellaneous Options", then toggle "Cheats" on. (This was not persistent in my installation.)

Launch the game as usual. Hit Tab to bring up the menu, which will have a new "Cheat" entry. Select that to bring up a list of all the items that parsed correctly. Use the arrow keys to select an item and toggle it on/off. If the game rejected an entry you will see some error messages in the shell window (so you really do want to be running this from the command line). Hit Tab a second time to close the menu.

The stand-alone file should take precedence over an entry in the monstrous 7zip cheat archive.

The cheat menu only works while the game is playing. If you stop at a breakpoint the cheat menu becomes inoperable, making it difficult to patch the ROM at a specific time. You can specify certain conditions in the cheat patch description, but these are sparsely documented.

The best sources of information on how to write cheat files are these guides, the source code, and this forum posting.

For a working example, you can download my Battlezone cheat file.

Copyright 2020 by Andy McFadden