(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:

./mame -debug

to start into the GUI, or:

./mame -debug bzone

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.

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">
    <script state="run">
    <script state="off">

  <cheat desc="No Volcano Draw 5824">
    <script state="on">
    <script state="run">
    <script state="off">

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