MAME Layout Files: Composing Emulated Screens, Artwork, and Interactive Elements

MAME’s artwork system is more than a decorative bezel placed around a game image. A layout can describe one or more views, arrange emulated screens, draw images and shapes, expose device outputs as lamps or displays, and let users hide selected collections. A good layout therefore documents a machine’s presentation model. It can make a multi-screen cabinet legible, show an illuminated control panel, or reproduce a physical color overlay without changing the emulated game logic.

This is MAME’s .lay XML system, not RetroArch’s overlay format and not a post-processing CRT shader. It runs in MAME’s render/layout path, with the emulated screens remaining distinct screen items. Understanding that boundary avoids using artwork to hide driver, aspect-ratio, or video problems.

The document model

A MAME layout file must have a top-level <mamelayout version="2"> element. The current layout documentation specifies version 2; MAME rejects other layout versions. At top level, define parameters, reusable elements and groups before the views that reference them. A view is a named arrangement for a host render target. It can contain screen items, layout-element instances, groups, collections, and repeated blocks.

The basic object types have different responsibilities:

A screen item presents an emulated display produced by the machine. Identify it by a zero-based index or a relative device tag, never both.
An element definition describes reusable graphics or text. It may contain image, rectangle, disk, text, or display components. An element instance places that definition in a view.
A group packages screens and elements into a reusable coordinate space.
A collection groups items that the user can show or hide in the UI. This lets an artwork file offer optional cabinet graphics without making the base view unusable.

Screen indexes follow the order screens appear in machine configuration, not a universal console or player numbering convention. If a view references a screen that is absent, MAME marks that view unviable, warns, and continues loading other views. This is useful for optional slot hardware, but it also means a typo may remove only one named view instead of stopping MAME entirely.

Start with a deliberately small view

The following example shows a screen inside a bordered cabinet area, plus a title label. It uses only built-in rectangle and text components, so no image assets or machine-specific input tags are needed. The bounds are layout coordinates, not an assertion that the source screen is 640 by 480 pixels.

<mamelayout version="2">
  <element name="cabinet-frame">
    <rect>
      <bounds x="0" y="0" width="640" height="480" />
      <color red="0.08" green="0.08" blue="0.08" />
    </rect>
  </element>
  <element name="cabinet-label">
    <text string="ARCADE DISPLAY" align="0">
      <bounds x="0" y="0" width="640" height="30" />
      <color red="1.0" green="0.85" blue="0.2" />
    </text>
  </element>
  <view name="Cabinet example">
    <bounds x="0" y="0" width="640" height="480" />
    <element ref="cabinet-label">
      <bounds x="0" y="8" width="640" height="30" />
    </element>
    <screen index="0">
      <bounds x="48" y="44" width="544" height="408" />
    </screen>
    <element ref="cabinet-frame">
      <bounds x="0" y="0" width="640" height="480" />
    </element>
  </view>
</mamelayout>

View items are listed from front to back. In this example the label is in front, the screen is behind it, and the opaque rectangle is the background behind both. Components inside a single element are drawn in reading order with alpha blending, so their order has a separate effect. A real bezel image can replace the frame element, but its alpha channel, intended screen opening, and scaling need to be tested. MAME supports PNG, JPEG, Windows BMP/DIB, and SVG image content. A bitmap alpha file must have the same dimensions as the image, and image assets should live alongside the layout file or in the same archive.

Save an external layout as a .lay file in a directory searched by artpath, which defaults to artwork; MAME documents -artpath for choosing one or more external layout and artwork directories. Verify the expected short-name folder and layout filename with the installed build and an official example rather than assuming every frontend uses the same packaging convention. Keep a small folder structure and label custom assets clearly so an update does not overwrite or obscure your files.

Coordinates, scale, and aspect ratio

Layout coordinates are arbitrary floating-point values. They are not required to match the game’s pixel dimensions. A view’s coordinate system can be explicit through a direct <bounds> child, or computed from the union of its screens and elements. MAME scales the view to fit the destination while preserving its proportions; content outside explicit view bounds is cropped. If you add a large background element, it can change the computed view bounds even when the game image itself did not change.

This is why design should begin with the display geometry. A layout coordinate plane can use convenient units such as 640 by 480, 1000 by 600, or a square panel. What matters is the relationship between the full view and each screen opening. The screen’s native visible area and physical aspect ratio remain characteristics of the emulated screen. Do not stretch the screen item to force square pixels unless that is an intentional presentation choice. Use MAME’s existing automatic views as a baseline, then compare a custom view with the game’s native and physical aspect behavior.

MAME also has view selection and output-window options outside the .lay file. A layout offers named views; command-line -view and per-window -viewN choose among them. Automatic view selection tries to keep all emulated screens visible where possible. A saved view selection in machine configuration may take precedence over the initial view specified by command line or INI. Therefore, a valid layout does not guarantee that the view you authored is currently selected.

Connect artwork to emulated state carefully

An element can have an integer state supplied by an emulated output or an I/O port field. That state can determine whether components draw, which image appears, the size and color of a shape, or the value shown on a segmented display. For example, a machine output called lamp_start can drive a simple active/inactive lamp by assigning the corresponding output name to an element instance. Input-bound elements use inputtag and inputmask, with the tag relative to the device that caused the layout to load.

This creates a meaningful distinction between a static bezel and an interactive cabinet reconstruction. A static image may be sufficient to frame the display. A lamp or clickable control should be wired to the machine’s actual output or input port, not animated from a guess about gameplay. Output names can be global; repeated device instances can make that naming ambiguous. Verify the output or port against MAME’s machine configuration and test each state transition in the target system.

Components are alpha blended in reading order. Color modifiers multiply the component color, which means a white image tinted by a color is not equivalent to a colored transparent overlay drawn over a screen. If an authentic physical overlay filtered the game image, the overlay should be layered over the screen item in the intended order and with measured or documented transparency. A decorative bezel that is meant to sit beside, rather than over, the screen should instead reserve a screen opening in its geometry.

Reuse and optional artwork

Use a group when several views share a control panel or when one layout arrangement is repeated with different bounds. Use a repeat block for regular arrays such as lamps or LED segments, and parameters to change the index, position, or output name. Define referenced elements before use. Duplicate element names are errors, and groups may not recursively instantiate themselves.

Collections are helpful for optional categories such as a control panel, labels, or a marquee. A user can toggle these separately without changing the machine’s emulated state. Keep essential elements outside optional collections. MAME limits a view to 32 collections, so avoid using one collection per decorative object.

Do not assume the layout must replace MAME’s automatic views. MAME generates views for emulated screens, physical and square-pixel aspect variants, cocktail arrangements, and multiple-screen grids. A custom file is additive presentation data; the driver still determines how many screens exist, their tags, dimensions, rotation, and timing. If all you need is a different host monitor arrangement, first inspect MAME’s existing per-window view and screen options before authoring new XML.

Validate the file in layers

The MAME source tree includes scripts/build/complay.py, which checks many layout syntax errors and can be run without an output path to validate a .lay file. It does not execute the whole layout engine, so it cannot catch every issue, including all unresolved references or recursive group errors. If you have the MAME source checkout, run:

python3 scripts/build/complay.py artwork/example/default.lay

Then test the layout in the exact MAME executable and machine. Enable verbose diagnostics, select the named view, and confirm that each expected screen and collection is present. A view that references an absent screen index can be skipped with a warning while MAME continues. A syntax error, by contrast, can prevent views from that layout from loading. Check both cases rather than treating a successful process exit as proof that the intended view is active.

Use a short acceptance matrix: one machine with the expected number of screens, one with a different orientation, and one launch with artwork disabled or the custom art path removed. Confirm that the fallback view remains usable, the image assets resolve, screen bounds preserve the intended aspect, toggled collections behave independently, and UI-saved view selection does not surprise the launcher. Record MAME version, layout file checksum, art path, selected view, host display dimensions, and whether scaling or cropping is enabled.

Keep the layout and assets version-controlled together. Test images at the smallest and largest expected window sizes, and inspect transparent edges, cropping, and color blending. MAME’s layout compiler check is a syntax aid, not a screenshot or visual-design test. Visual verification on the actual frontend remains necessary because the host window, monitor scaling, rotation, and saved view can all affect the result.

Related:

Sources: