LAY File Basics - Part I

A layout file (LAY file) describes objects to draw when running a particular system in XML format. The layout file format documentation is available on the MAMEdev documentation web site.

Systems that only have simple arrangements of screens generally use automatically-generated layouts. Systems that need more complex screen arrangements or additional interactive elements use internal layout files. You can browse the internal layouts in MAME’s source code.

All external artwork utilizes layout files to tell MAME where to put all of the different artwork pieces and screens (if applicable).

ELEMENTS

MAME can utilize any of the following different types of “components” in a layout file:

• External image files
  • The image must be in PNG, JPEG, Windows DIB (BMP) or SVG 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 4000 pixels wide.
  • A bezel artwork file (the type which surrounds the game screen), should have a center window with an alpha transparency value of zero (i.e. the middle should be “see-through”).
  • 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.
  • Disk
    • Just like above, except instead of a square/rectangle, you have a circle/oval.
  • Multi-segment LED display
    • 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.
    • MAME has internal support for standard 7-segement displays, and multiple types of 14-segment and 16-segment displays
  • Text
    • You can even display text as an element, using MAME’s default UI font. This is typically used for button/LED labels in internal layout files.

For all internally rendered components, you must define the ARGB (alpha, red, green, blue) color of the element, using channel values from zero to one. So for example, where the 8-bit-per-channel RGB value of orange is (255, 127, 0), this would be represented in the layout file as (1.0, 0.5, 0.0).

“Elements” are built up from components. An element is drawn as a single textured rectangular surface in the final scene graph. The components are drawn into the element texture using alpha blending.

VIEWS

Each layout file must have at least one defined “view” to tell MAME how to position all of the different elements and screens. Each item in a view must include:

• An opening tag, where you specify the element you’re using, the blending mode, and I/O bindings for the element.
• A closing tag, which states that you are done defining that object.

An item may also include:

• An animate element specifying separate I/O bindings for the item.
• A bounds element specifying the position and size of the item, or multiple bounds elements for parameter animation.
• A color element allowing the item’s color to be modified by RGB multiplication, or multiple color elements for parameter animation.

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, instantiated with an element element.

• Screen
  • The screen shows the image on an emulated screen or video output.
  • The screen is the playable game screen. The beginning tag for this in a single-screen system is:
    • <screen index="0">
  • The value of “index” is the zero-based index of the screen in the system. For systems that have one screen, this value will always be zero If a system has two screens, the value for the second screen would be "1", and so on.
  • The screen can also be specified by “tag” using its tag, relative to the device that loaded the layout. This is most useful for internal layouts for devices that are used as parts of larger systems.
  • If a system has multiple screens, you can choose to only display one of the screens, if you so wish.

• Element
  • Instantiates an element defined earlier in the layout file. By default, elements are drawn with alpha blending; the blending mode can be overridden with a “blend” attribute. The following blending modes are supported:
    • Alpha blending (alpha):
      • The element will be drawn with alpha blending, and will obscure any elements/screens instantiated earlier in the view.
    • Additive blending (add):
      • This is useful for backdrops. Many arcade games from the ’70s and ’80s utilized a cabinet where the monitor was laid down, and reflected to the player by a semi-silvered mirror, with backdrop artwork sitting behind the mirror. This gave the effect of a much cooler looking-game, back when the hardware was more simple. To get this effect, you can place the backdrop over the screen and specify additive blending, or vice versa.
    • RGB multiply (multiply):
      • This is useful for translucent overlays. 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. To get this effect, you can place the overlay over the screen and specify RGB multiplication.

For each item in a view, you need to define the “bounds” to tell MAME what coordinates to use to place the item. 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 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:

<?xml version="1.0"?>
<!-- vanguard.lay -->

<mamelayout version="2">
	<element name="bezel">
		<image file="vanguard_bezel.png" />
	</element>
	<view name="Upright Artwork">
		<screen index="0">
			<bounds x="1060" y="790" width="1920" height="2560" />
		</screen>
		<element ref="bezel">
			<bounds x="0" y="0" width="4000" height="3810" />
		</bezel>
	</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:

• 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.
• Opening Header Tag
  • This defines the type of XML file this is; in our case, a “mamelayout” file.
• 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”.
• 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 “Video Options” menu of the internal MAME user interface.
  • The first item is the screen. It has an index of "0", as it is the only screen for this game.
  • The next item instantiates the element named "bezel".
  • Once all objects are defined, you need a closing tag to finish this “view”.
• A closing tag to end the “mamelayout” file.
• 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

Note very carefully the values of the width and the height for the screen:

• The screen ratio for most vertical arcade games is 3:4.
• The screen ratio for most horizontal games is 4:3.

Let me explain that now. Most arcade games through the 20th century and into the early 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 resolution an arcade PCB runs internally, it is expected to be stretched out to a standard 4:3 monitor. So if you want to calculate the screen ratio correctly:

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

(Exceptions include games that supported wide-screen monitors. Sega Virtua Racing and Capcom Street Fighter III 2nd Impact: Giant Attack are examples of games that can be configured to use a 16:9 widescreen monitor.)

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.

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