XML Cheat Documentation

If you are having problems finding or using cheats for an Emulator (particularly MAME/MESS) or have found a trick that you wish to share this is the place to do it. But please read the Cheat FAQ first.
Post Reply
User avatar
NotAGoodName
Posts: 331
Joined: Wed Feb 18, 2009 7:09 am
Location: MO, USA
Contact:

XML Cheat Documentation

Post by NotAGoodName »

As there is a rather minimal amount of documentation in existence for the XML format, I'm going to do my best to document the entire thing.

From Cheat.C

Code: Select all

<mamecheat version="1">
        <cheat desc="blah">
           <parameter min="minval(0)" max="maxval(numitems)" step="stepval(1)">
              <item value="itemval(previtemval|minval+stepval)">text</item>
              ...
           </parameter>
           <script state="on|off|run|change(run)">
              <action condition="condexpr(1)">expression</action>
              ...
              <output condition="condexpr(1)" format="format(required)" line="line(0)" align="left|center|right(left)">
                 <argument count="count(1)">expression</argument>
              </output>
              ...
           </script>
           ...
           <comment>
              ... text ...
           </comment>
        </cheat>
        ...
    </mamecheat>
Never fear. I'm not mailing it in. I'm going to describe all of this in as much detail as I know how. If it looks complicated, it shouldn't. It's pretty easy for most of what you'll ever want to do.


Quick Intro to XML
For the most part, if you've learned HTML, you should conceptually know how MAME's XML cheat system works. The only difference is that XML is much more finicky. All tags in XML must be closed off at some point. All quotations must be closed. Any errors in XML files can cause MAME to crash. Be cautious and avoid doing anything that increases the chance of making a mistake. Even misplaced tags and typographical errors are potentially fatal.

If you're using a tag as a container, then it must have have an appropriate closing tag.
Example: <tag>stuff</tag>

If a tag is only being used for its attributes, then it must be closed immediately.
Example: <tag attribute="stuff" />

Avoid using < and > for anything. If you want them as characters, use < and > (same as HTML). As comparisons, use LT and GT.


Using and editing XML files
All of MAME's XML cheats are packed in a file called cheat.zip which goes in the root MAME directory (such as C:\MAME). Cheats can be extracted to the cheat directory (C:\MAME\cheat) but you should only extract files that you wish to modify. You do not need to place your modified cheat files in cheat.zip. Files in the cheat directory override cheat.zip.

There is no reason for the editing process to seem complicated. It is simple.

1) Open cheat.zip
2) Find the file you wish to edit
3) Place said file in cheat folder
4) Edit file

That's it. MAME includes a reload cheats feature. It will load the file in the cheat folder if there is one. If there's an error, MAME will probably crash with a random error. Don't make mistakes. lol
Aww yeah. AMD A10-7850K givin' MAME and MESS systems what for.
User avatar
NotAGoodName
Posts: 331
Joined: Wed Feb 18, 2009 7:09 am
Location: MO, USA
Contact:

Re: XML Cheat Documentation

Post by NotAGoodName »

Primary Tag: <mamecheat>
Attributes:
version - So far, always 1

This no different than the HTML tag in HTML. All files have <mamecheat version="1"> at the beginning and </mamecheat> at the end. All cheats are placed inside of this "container". Unless you're writing a cheat file from scratch, this is unimportant.


1. Main Tag: <cheat>
Attributes:
desc - The text displayed in the cheat menu!

This is the tag which contains all of the action for the cheat. It can also be used as sort of divider in cheat files. <cheat desc=" "/> is equal to <hr> (horizontal line) in HTML.

All cheats have some standardized variables available to them:
temp0 - temp9 - Ten temporary variables
param - Adjustable parameter value
frame - Can be used as "frames passed before cheat executes"
argindex - "for arguments with multiple iterations, this is the index" Honestly, I don't know what this does. Must not be that useful.

By Pugsy's standards, <cheat> and </cheat> are preceded with two spaces.


2. Comment Text: <comment>
Attributes:
none

Comments are the exact same thing as they were in DAT format. Move over a cheat with a comment and the comment text is displayed at the bottom of the screen. Comments are good for describing to the user how to use cheats that change a game mechanic. Really, you should know if you need a comment.

Pugsy places <comment> after <cheat> on the same line.

Example from pc_smb3.xml:

Code: Select all

  <cheat desc="Emulate Debug Mode"> <comment>Select+Up/Down to change suit.  Select+B for shoe.</comment>
    <script state="run">
      <action condition="cart.pb@0017==28 and cart.pb@00ED LT 06 and (frame % 10 == 0)">cart.pb@0578=(cart.pb@00ED + 2)</action>
      <action condition="cart.pb@0017==28 and cart.pb@00ED == 06 and (frame % 10 == 0)">cart.pb@0578=01</action>
      <action condition="cart.pb@0017==24 and cart.pb@00ED GT 00 and (frame % 10 == 0)">cart.pb@0578=(cart.pb@00ED)</action>
      <action condition="cart.pb@0017==24 and cart.pb@00ED == 00 and (frame % 10 == 0)">cart.pb@0578=07</action>
      <action condition="cart.pb@0017==60 and (frame % 10 == 0)">cart.pb@0577=(cart.pb@0577 ^ 01)</action>
    </script>
  </cheat>

3. Parameter variables: <parameter>
Attributes:
Optional min - Minimum value allowed for param (0 or higher)
Optional max - Maximum value allowed for param (a value higher than minimum)
Optional step - Typically, you want 1. But 2 will give you every other number. So forth.

The parameter tag is used two ways and always affects the variable "param". Here, I'll describe the first method.

Example from pc_wcup.xml:

Code: Select all

  <cheat desc="Select Current Score PL1">
    <parameter min="0" max="99" step="1"/>
    <script state="change">
      <action>cart.pb@0517=tobcd(param)</action>
    </script>
  </cheat>
This is how you use <parameter> in your typical "start on..." or "current points" cheat. It allows you to select a number 0-99 and whatever number you select, that's the value of "param". tobcd(param) means that the number is taken literally and not converted to hexidecimal.

Pugsy places 4 spaces before <parameter>


3b. Selectable parameters: <item>
Attributes:
value - The value passed to "param"

"Items" are contained in <parameter> and give you the option of selecting texts instead of numbers. Basically, this is for things like character and weapons select.

Example from mk3ghw.xml:

Code: Select all

  <cheat desc="Select Character PL1">
    <parameter>
      <item value="0x00">Kano</item>
      <item value="0x01">Sonya</item>
      <item value="0x02">Jax</item>
      <item value="0x03">Nightwolf</item>
      <item value="0x04">Sub-Zero</item>
      <item value="0x05">Stryker</item>
      <item value="0x06">Sindel</item>
      <item value="0x07">Sektor</item>
      <item value="0x08">Cyrax</item>
      <item value="0x09">Kung Lao</item>
      <item value="0x0A">Kabal</item>
      <item value="0x0B">Sheeva</item>
      <item value="0x0C">Shang Tsung</item>
      <item value="0x0D">Liu Kang</item>
      <item value="0x0E">#Smoke</item>
      <item value="0x0F">#Motaro</item>
      <item value="0x10">#Shao Kahn</item>
      <item value="0x11">##Noob Saibot</item>
    </parameter>
    <script state="run">
      <action>maincpu.pb@FF0127=param</action>
    </script>
  </cheat>
Something like 0x00 means hexidecimal value 00. You can use decimal values such as "99" instead of "0x63" if you want. Also note that # is used to denote special options like secrets and unavailable bosses and ## is used to denote options that may be unwise to select.

Pugsy places 6 spaces before <item>.
Aww yeah. AMD A10-7850K givin' MAME and MESS systems what for.
User avatar
NotAGoodName
Posts: 331
Joined: Wed Feb 18, 2009 7:09 am
Location: MO, USA
Contact:

Re: XML Cheat Documentation

Post by NotAGoodName »

4. Go go gadget cheat! <script>
Attributes:
state - How/when to use the contained actions (on, off, change, run)

This is where the real action takes place.

About states:
on = Now! cheats. Also called one shot cheats. You push enter, the cheat does its action. That's it.
change = Now! cheats with parameters. Select a parameter and push enter. This is commonly used for crash prevention.
run = Where enabled means always enabled (unless frame is used or a loop is instated)
off = Something to do when the cheat is disabled. Pugsy often uses this to restore ROM when disabling ROM cheats.

You cannot mix change and run, but you can mix the others.

Pugsy places 4 spaces before <script>


4b. Lights, Camera, <action>?
Attributes:
Optional condition - Defines a condition at which the action is executed. Absurdly useful.

This is the most important part of making a cheat, so knowing how it works is important.

Pugsy places 6 spaces before <action>.


Cheat Break Down

At this point, we need to break down how cheats actually work.

* Standard Cheats *
Usually, you just want to plug a value into something and make it stay there. Set it and forget it.

Example from mk3ghw.xml

Code: Select all

  <cheat desc="Infinite Lives in Galaga">
    <script state="run">
      <action>maincpu.pb@FF022F=99</action>
    </script>
  </cheat>
This is a cheat that when enabled, always puts the value 99 in the RAM address FF022F. You should understand that from the things described so far.

maincpu . p b @ FF022F = 99
maincpu = The address space that the address exists in. "maincpu" is the most commonly wanted, but as seen above, not always.
p = Type of memory. p=RAM, m=ROM, o=ROM ??? ROM cheats aren't my thing, but p is usually what you want.
b = Width of value being plugged. b=byte (0x00), w=word (0x0000), d=double (0x00000000), q=quad (0x0000000000000000)
FF022F = Address. Have fun with Midway machines. They use a very unusual system which I don't like much.
99 = The value being plugged in. (Hexidecimal)


* Bit Cheats *
There's 8 bits in a byte. That is... 01,02,04,08,10,20,40,80. You add those up and you get various values which indicate which bits are active and inactive. Pretty simple. Just think of it as toggle switches. 03 would mean that the first two toggle switches are active. 00 means none active. Etc.

Example from pc_wcup.xml:

Code: Select all

  <cheat desc="Press SELECT+A for Sliding Tackle P2 (friend)"><comment>Alternate pass function allows you to always tackle opposing team members.</comment>
    <script state="run">
      <action condition="cart.pb@0001==(A0|(cart.pb@0001 BAND ~A0))">cart.pb@03FC=9B</action>
    </script>
  </cheat>
Here I've built a cheat which uses a bit value in a condition. Ooh...scary! Here's an English description of what happens: "If the 6th and 8th bits at 0001 (in the cart address space of RAM) are active, then make 03FC's value equal 9B." It works because the NES (and probably every other system EVER) stores what buttons are held on the controller as bits in some addresses.

(A0|(cart.pb@0001 BAND ~A0))
A0 = value being plugged in
cart.pb@0001 = the relevant address and space
BAND ~A0 = Bit width of the address being poked or tested

These cheats are admittedly complicated and iffy to play with, but you have to be creative and just see what you can do with it.


* Using frames *
I admit I don't know entirely how to use the frame variable, but here's a nice application of it.

Example from pc_smb3.xml:

Code: Select all

  <cheat desc="Moon Jump"> <comment>Hold A to jump forever.</comment>
    <script state="run">
      <action condition="(frame % 7 == 0) and cart.pb@0017==(80|(cart.pb@0017 BAND ~80))">cart.pb@00CF=CD</action>
    </script>
  </cheat>
This tells the cheat engine that if I'm holding the jump button, make 00CF's value equal CD every 7 frames. This is a well tuned value derived to ensure that Mario won't jump through ceilings. There's surely other uses for "frame" but oh well. Maybe Pugsy can describe it better somewhere.


* ROM cheats *
ROM hacking isn't really my forté so I'll let Pugsy's art better demonstrate a ROM cheat.

Code: Select all

  <cheat desc="Invincibility">
    <script state="on">
      <action>temp0 =maincpu.ob@157E</action>
    </script>
    <script state="run">
      <action>maincpu.ob@157E=60</action>
    </script>
    <script state="off">
      <action>maincpu.ob@157E=temp0 </action>
    </script>
  </cheat>
This is a nice example which also demonstrates the usage of temporary variables. Never seen o before as memory type, but whatever. You can see here that Pugsy stores the original ROM value in a temporary variable and then restores it when the cheat is disabled. I'm not sure how necessary this is, but it's good practice and I figure anything Pugsy does must be correct. He's a hell of a lot smarter than I am.


* Conditions and Settings and Stuff *
I'm not going to explain all of this because I don't even know all of it. Basically, you need to know = for setting cheats. For conditions, == (equals), != (not equals), LT (less than), GT (greater than).

Just look at this.
Last edited by NotAGoodName on Tue Sep 28, 2010 9:19 pm, edited 1 time in total.
Aww yeah. AMD A10-7850K givin' MAME and MESS systems what for.
User avatar
NotAGoodName
Posts: 331
Joined: Wed Feb 18, 2009 7:09 am
Location: MO, USA
Contact:

Re: XML Cheat Documentation

Post by NotAGoodName »

5. Watching values: <output>
Attributes:
Optional condition - Same as conditions for <action>
format - How to display the values
Optional line - Which line of the screen to draw the output
Optional align - Where on the line (left,center,right)

This is a sub tag of <script> just like <action> and is used to display values in memory like watchpoints. "format" is the only required tag attribute and it's not well documented.


5b. Arguments for output: <argument>
Attributes:
count - Number of arguments

This is a sub tag of <output> and is used to tell <argument> where to get its information. I've not played with this much (haven't needed to), but Walterh78 seems to know how it works so I'll use one of his submissions for an example:

Code: Select all

  <cheat desc="Watch ALL 14 tiles - Player">
    <script state="run">
      <output format="%02X %02X %02X %02X %02X %02X %02X %02X %02X %02X %02X %02X %02X %02X">
        <argument count="14">sub.pb@(2F50 + 0x04*argindex)</argument>
      </output>
    </script>
  </cheat>
Oh yeah. There's how argindex is used.
Aww yeah. AMD A10-7850K givin' MAME and MESS systems what for.
User avatar
NotAGoodName
Posts: 331
Joined: Wed Feb 18, 2009 7:09 am
Location: MO, USA
Contact:

Re: XML Cheat Documentation

Post by NotAGoodName »

Cheat Searching

Start your game with debugger enabled. When it loads up, hit F5 immediately just for the sake of convenience. How to search for cheats? Read this post by Pugsy.

If you're having too much trouble, try starting the cheat search with something like ci ub,0,ffffffff to get all of the RAM possible.

Things to really remember:
ci = cheatinit (begin new search)
cl = cheatlist (list all results)
cn ... = cheatnext (search command)
... ne = not equal (saves all addresses which are not equal to the last search)
... eq = equal (saves all addresses which are equal to the last search)
... + = increased
... - = decreased

cn in,1 = save all addresses which have increased by 1 since last search. (Note the comma.)
Last edited by NotAGoodName on Tue Oct 04, 2011 6:10 pm, edited 1 time in total.
Aww yeah. AMD A10-7850K givin' MAME and MESS systems what for.
User avatar
Pugsy
Posts: 3638
Joined: Fri Aug 17, 2001 12:59 am
Location: North Wales, UK.
Has thanked: 1 time
Been thanked: 12 times
Contact:

Re: XML Cheat Documentation

Post by Pugsy »

Nice work!!
Pugsy

Servicing your cheating needs since 1985 8)

Grab the latest cheat collection:
MAME 0.259 XML cheat collection (6 OCTOBER 2023) from http://www.mamecheat.co.uk or direct from:-
https://mega.nz/file/q4dHGZ6K#i-EUiqIjH ... KMz7hnbTfw (ZIP Archive 3.76MB)
User avatar
Abystus
Posts: 521
Joined: Sun Jul 23, 2006 6:53 am
Has thanked: 3 times
Been thanked: 22 times

Re: XML Cheat Documentation

Post by Abystus »

Say I wanted to make a cheat to where I had a list of values, but wanted them to activate by pressing enter on them like a normal "on" based cheat. Here is what I've created, though I haven't gotten it to work:

Code: Select all

<cheat desc="Test Cheat">
    <comment>This needs to activate only when I press enter on the cheat.</comment>
    <parameter>
      <item value="0x1234">Value1</item>
      <item value="0x5678">Value2</item>
      <item value="0x9ABC">Value3</item>
    </parameter>
    <script state="on">
      <action>maincpu.pw@1234567=param</action>
    </script>
</cheat>
Is this a limitation of the xml format, or am I just doing something wrong? Any help is appreciated.
Bored? Watch some of my hacks here.
User avatar
Pugsy
Posts: 3638
Joined: Fri Aug 17, 2001 12:59 am
Location: North Wales, UK.
Has thanked: 1 time
Been thanked: 12 times
Contact:

Re: XML Cheat Documentation

Post by Pugsy »

Rather than "on" as the state you need to use "change".
Pugsy

Servicing your cheating needs since 1985 8)

Grab the latest cheat collection:
MAME 0.259 XML cheat collection (6 OCTOBER 2023) from http://www.mamecheat.co.uk or direct from:-
https://mega.nz/file/q4dHGZ6K#i-EUiqIjH ... KMz7hnbTfw (ZIP Archive 3.76MB)
User avatar
Abystus
Posts: 521
Joined: Sun Jul 23, 2006 6:53 am
Has thanked: 3 times
Been thanked: 22 times

Re: XML Cheat Documentation

Post by Abystus »

Pugsy wrote:Rather than "on" as the state you need to use "change".
Very nice. Worked like a charm. Appreciate the quick response!
Bored? Watch some of my hacks here.
Post Reply