LAY File Basics - Part I

A layout file (LAY file) is simply code in an XML format to tell MAME how to layout different objects for a particular game.

Every game in MAME utilizes at least one internal layout file.

All external artwork files utilize layout files to tell MAME where to put all of the different artwork pieces in relation to the game screen(s).

ELEMENTS

MAME can utilize any of the following different types of "elements" in a layout file:

• External Image Files
  • The image must be in PNG format
  • It can be any size; typically, bigger is better (assuming the original image was already sharp). The high-quality artwork being used today is typically 4000px wide.
  • A bezel artwork file (the type which surrounds the game screen), should have a center window with an alpha transparency value of "0." (i.e. the middle should be "see thru")
  • Only external artwork files can use image files (unless you edit the source for your own personal MAME build; more on that later).
• Internally Rendered Elements
  • Rectangle
    • A colored square or rectangle.
  • Disc
    • Just like above, except instead of a square/rectangle, you have a circle/oval.
  • 7-Segment LED
    • Some games utilized LEDs, like on a calculator. If a game supports these in its MAME driver, then these will work accordingly. If not, then the LED will just display garbage.
  • Text
    • You can even display text as an element, using MAME's internal font. This is typically only used for internal layout files to add to the MAME documentation.

  For all internally rendered elements, you must define the RGB (red, green, blue) value of the element, using a "percentage of 255" value for each color. So for example, where the RGB value of orange is "255, 127, 0", this would be represented in the layout file as "1.0, 0.5, 0.0"

VIEWS

Each layout file must have at least one defined "view" to tell MAME where to layout all of the different objects. Each object in a view must include:

• An opening tag, where you define the characteristic of the object, and the name of the element you are using.
• A "bounds" tag, which defines the width, height, and placement of the object.
• A closing tag, which states that you are done defining that object.

Each object within a view must either be a screen, or can be an element defined at the beginning of the layout file as shown above, with the characteristic of bezel, backdrop, or overlay.

• Screen
  • The screen is the playable game screen. The beginning tag for this in a normal game is:
    • <screen index="0">
  • The value of "index" can be "0, 1, 2, or 3." For typical games that have one screen, this value will always be "0." If a game has two screens, the value for the second screen would be "1," and so on. At this time, no games in MAME use more than four screens.
  • If a game has multiple screens, you can choose to only display one of the screens, if you so wish.
• Bezel
  • If an element is defined as a bezel, then it will display above any other element (think of it as artwork displayed outside of the monitor on an arcade cabinet). If a bezel overlaps another element, that other element will not be visible below the bezel (in most cases; more later). If two bezels are defined in one view and they overlap, the bezel defined last will display above the ones before it.
• Backdrop
  • An element defined as a backdrop will display behind any other elements, including the screen. Many arcade games from the 70's and 80's utilized a cabinet where the monitor was laid down, reflected above into a two way mirror at the player's view, and then had artwork sitting behind the mirror. This gave the effect of a much cooler looking game, back when the hardware was more simple.
• Overlay
  • Again, in the early days, some games that used black and white monitors had color gel overlays placed on top of the monitor to give the game some color. An element defined as an overlay will blend in with the game screen to change the color of the screen.

For each object in a view, you need to define the "bounds" of the element, which tells MAME what coordinates to use to place each element. If you think back to geometry in school, think about when you did graphing. The x-axis is horizontal, the width, left to right; the y-axis is vertical, the height, top to bottom. Where x and y cross is (0, 0). As you go to the right, numbers get bigger (like geometry); as you go down, numbers get bigger (the opposite of geometry).

There are two ways that you can define the "bounds" for an element:

• <bounds x="*" y="*" width="*" height="*">
  • "x" and "y" are the coordinates of the top left corner of the object; "width" and "height" are the actual width and height of the object.
• <bounds left="*" top="*" right="*" bottom="*">
  • "left" and "top" are the coordinates of the top left corner of the object; "right" and "bottom" are the coordinates of the bottom right corner of the object.

Either way works; it's just a matter of personal preference. I use the first way, as I already know the size of each element I'm using. In addition, it's easier to make adjustments to move things around; you just change "x and y," leaving the width and height the same.

YOUR FIRST LAYOUT FILE

We'll start out by doing a simple layout file for an artwork bezel. First, here's the code:

---

<!-- vanguard.lay -->

<mamelayout version="2">
     <element name="bezel">
         <image file="vanguard_bezel.png" />
     </element>
     <view name="Upright_Artwork">
         <bezel element="bezel">
               <bounds x="0" y="0" width="4000" height="3810" />
         </bezel>
         <screen index="0">
               <bounds x="1060" y="790" width="1920" height="2560" />
         </screen>
     </view>
</mamelayout>

<!--

- Artwork type: Bezel
- Scanned bezel provided by Mr. Do
- Vectorized by zorg
- Lay file by Mr. Do

-->

---

Now let's look at each section:

1. Comment Line
   • This first line isn't necessary; I simply use it so I know which game I'm looking at. In a layout file (and any XML file), a comment starts with "<!--" and ends with "-->". You can put anything you want in between.
2. Opening Header Tag
   • This defines the type of XML file this is; in our case, a "mamelayout" file.
3. Elements
   • After the header tag, you define each of your elements. In this case, we have one element, using a file called "vanguard_bezel.png," with the name of "bezel."
4. View
   • After you define all of your elements, you need an opening tag for the view section, where you define the bounds for each screen and element you are going to use.
   • The "name" of the view is what will display in the "View Options" section of the internal MAME menu.
   • The first object is a "bezel," using the element named "bezel."
   • The next object is the screen. It has an index of "0," as it is the only screen for this game.
     • note very carefully the values of the width and the height for the screen:
       • The screen ratio for EVERY vertical game is 3:4.
       • The screen ratio for EVERY horizontal game is 4:3.

       Let me explain that now. ALL arcade games through the 21st century ran on a standard arcade monitor, with a 4:3 ratio, just like old CRT monitors. Vertical games simply rotated the monitor 90 degrees. No matter what resoloution an arcade PCB runs internally, it is expected to be stretched out to a 4:3 monitor (e.g. 320x240; 640x480, etc.). So if you want to calculate the screen ratio CORRECTLY:

       • The width divided by the height on a horizontal game equals 1.25.
       • The width divided by the height on a vertical game equals 0.75.

       The other note I'd like to make is that on 99% of arcade games, the borders of the bezel did not touch the border of the monitor. In fact, most games had an internal black plastic bezel between the monitor and the external artwork, and actually had quite a bit of space between the monitor and the artwork. On official artwork, I try to make the game screen as big as possible within the bezel window. But, you'll notice that, except for a few select games, the screen doesn't touch the artwork.

   • Once all objects are defined, you need a closing tag to finish this "view."
5. A closing tag to end the "mamelayout" file.
6. More comments. This is were I put notes for:
   • What type of artwork(s) this file represents
   • How the original source artwork was captured (scan, photo), and who did the work.
   • Who converted the original source to use in MAME, and if it was vectored or not.
   • Any other additional credits
   • Who wrote up the layout file

Those are the basics for now. There will later be a Part II for some more advanced examples.