Understanding MAME overlay config to port them to Libretro config

I’m trying to automate the porting of OrionsAngel’s amazing arcade overlays (see here), that are pre-configured as MAME overlays, to Libretro overlay configs.

From what I can see, the Mame overlays configuration consist of two main files.

The first is a “gamename.cfg” file for which I can’t find any documentation. It usually looks like this:

<mameconfig version="10">
    <system name="altbeast2">
            <screen index="0"
                    voffset="0.008000" vstretch="0.656000" />

I have no idea what these values represent. I assume they are multipliers, but for what? Screen resolution? Layout rendering? What are they used for?

The other important file is in a zip file (matching the rom name), and is called “default.lay”. This one is a little bit documented but not much. The content seems pretty obvious: it defines elements to draw and then specifies where to draw them.

<mamelayout version="2">
	<element name="nmva_widescreen">
		<image file="altbeast.png" alphafile="mask.png" />
	<view name="NMVA_Widescreen">
		<bezel element="nmva_widescreen">
			<bounds x="0" y="0" width="1280" height="720" />
		<screen index="0">
			<bounds x="232" y="54" width="816" height="612" />

The problem is that the coordinates specified in the file do not match the image.

Above is the configuration taken from the Altered Beast overlay.
The “bezel” element seems to indicate that the screen should be in 720p. But applying the screen coordinates to the bezel resized in 720p makes the screen much larger that the area it’s supposed to be in: https://ibb.co/jSjT9R

Multiplying the positions and/or sizes by the “stretch” and “offset” values from the first file does not come close to where the screen is supposed to be, so I’m assuming that’s the wrong approach.

So my question is: which calculations should I do to convert a MAME overlay to a Libretro overlay?

I’m assuming OrionsAngel overlay are correctly configured and work for everyone out of the box, but maybe that’s where I’m wrong, and MAME overlay always require moving things around when you change your screen resolution?

Thanks for you help :slight_smile:


Hi cosm0, I think I can help after some quite long trial and errors. Based on John Merrit’s and OrionsAngel’s brilliant work, I started two GitHub repositories for Realistic Bezels, one in MAME, one in Retroarch:

MAME - https://github.com/estefan3112/MAME-Realistic-Bezel-Artwork

Retroarch - https://github.com/estefan3112/Retroarch-Realistic-Bezel-Artwork

Please note that contrary to OrionsAngel’s configuration, my default.lay files are self-dependent, and thereby platform-independent. It seems to me that OrionsAngel’s configurations are for Windows/hlsl configurations only.

My Retroarch repo is in very early stages because it is far much more work. The beauty of MAME default.lay is that they fit to screen automatically (irrespective of your actual screen resolution), while Retroarch always builds up on your actual screen resolution. Moreover, Retroarch paths vary on the different systems, which makes portability much more difficult.

Take the example of 1942, both on MAME and on Linux (take the Linux configuration file, which I documented inside a lot). In MAME, you only need to define the size of your overlay and put the screen into relation. Irrespective of your actual screen resolution, it will work. In Retroarch, you need to scale up or down the four parameters defining Overlay and Screen, at least according to my understanding.

On the more complex MAME overlays, where I split the screen from the cabinet for switching on and off inside of the game, I also wrote this post:

Good luck and please let me know whether this makes sense to you.


@estefan3112 thanks for the heads up ! :slight_smile:

Did you find out how to compute the screen size and position based on the MAME config ?

My own repository is finished, and it includes OrionsAngel’s work, but I had to manually measure the sizes and positions using Photoshop.

You can copy my files if you’re interested, I don’t mind :wink:

@cosmo0: Oh you code, I envy you :slight_smile:. I have already starred your repo before and it seems that I need to take a close look into your way of doing things.

All work done by me is manually, including measuring in GIMP :roll_eyes:. I need to think about it anyway, if you move away from 1080p MAME (pure default.lay), there should be a logic to move to the Retroarch way of doing things - in 1080p…

EDIT - yes it should work! If you have a clean MAME default.lay in 1080p, just like this for 1943:

Look at the screen bounds: bounds x=“585” y=“50” width=“750” height=“1000”

Then look into the 1943 config file for Retropie in 1080p:

Voila: custom_viewport_width = “750” custom_viewport_height = “1000” custom_viewport_x = “585” custom_viewport_y = “50”

This is the beauty of pure MAME default.lay, it scales up and down, irrespective of the actual resolution. This you can translate into the corresponding configuration in Retroarch!


@estefan3112 well, my scripts are pretty basic, I don’t think it would be difficult to tune them.
In src\import-mame.js you will find a script to create the basic template of a Retroarch overlay from a MAME overlay : it extracts the image from the zip and creates the cfg files from the lay file. But you still have to measure the positions using Gimp/Photoshop.
If you’re interested in using/tweaking it, I can help you.

I have tried to use the screen bounds, but in OrionsAngel’s work it doesn’t work that way, they pretty much all have the same screen bounds (one set of coordinates for horizontal games, another for vertical). I’m guessing MAME has multiple ways of doing things, or maybe it changed in some version since John Merit’s work.

@cosmo0 That’s why I started up my MAME repo - to create MAME default.lay files that are independent on additional HLSL settings. And this requires to look into every single png and measure the screen in 1080p. This makes the MAME layouts platform-independent. I tried them all over Mac (my home system), Windows and Ubuntu, and they work across all systems in the same way :slight_smile:

So I guess that from these standalone default.lay files, it would be possible to create Retroarch files - with the catch that Retroarch directories are different in Mac, Windows and Linux. At least Linux, it seems to me, can be dealt with in the same way for Retroarch (upstream) and Retropie.

I will have further looks into this. Though MAME rules the overlay section, Retroarch is the better choice in many other ways, in particular shaders. That is my motivation for this work.


Keeping my eye on this topic. Love a bezel myself.

Could you guys think about consolidating your repos and sending PR’s to this one?

Be nice to keep things organised and safe for the future

1 Like

I think consolidating will be a thing do to. Currently I am still experimenting what to do, with a focus on MAME layouts. I have starred your repository before and would be more than happy to push finished work there!

1 Like

Hey guys, how are you?

I am trying to move from standalone MAME to the RA core, but I am facing a problem with the overlays; I need to select the cfg file per game, and once loaded, I need to tweak the screen size to match the png.

Do you have a way of placing the cfgs and pngs in a specific folder and/or set something up so that RA reads them automatically once the rom is loaded?

Hi, you are right, the way Retroarch handles Overlays is much more complex. In which system are you? I try to write instructions here, but I am actually missing Windows:

General rule:

  • Find out where Retroarch stores Overlays -> it is defined in the Settings under ‘Directories’
  • Game-specific settings are a bit more difficult -> and you need to set these per Core individually

Hope this helps. Some time I will look to Windows as well.


Thank you Estefan. I guess I will be reverting back to standalone MAME. When I use MAME artwork in RA, the quality gets heavily downgraded for the bezels, that is why I wanted to use RA Overlays.

Hi @Kondorito

For “system” overlays, it depends on your installation.
For game overlays, try to place the game config file next to the rom. For instance, to set an overlay for altbeast.zip, create a game config altbeast.zip.cfg (note the double file extension: .zip.cfg).

Basically, a RetroArch overlay needs 3 files:

  • a system or game config file
  • an overlay config
  • an overlay image

The overlay image is a PNG with a cutout where the screen will go.
The overlay config is just saying “use this overlay image”.

overlays = 1
overlay0_overlay = xxxxxx.png
overlay0_full_screen = true
overlay0_descs = 0

The system or game config file will point towards the overlay config, and sets the screen position.

video_force_aspect = true
video_scale_integer = false
aspect_ratio_index = 22 # custom aspect ratio

custom_viewport_x = "469"
custom_viewport_y = "119"
custom_viewport_width = "359"
custom_viewport_height = "467"

input_overlay_enable = true
input_overlay_opacity = 1.0
input_overlay_scale = 1.0
input_overlay = /path/to/overlay.cfg

You can check out my configs/setup here : https://github.com/cosmo0/retropie-arcade-overlays ; they’re for Retropie, but I assume they can be adjusted to work with any RetroArch version.

1 Like

Thank you cosmo, I will give it a try later on!

Yes, while I am aware of that solution to place overlay config files into the rom folder, you can never then change anything in your configuration from the RGUI application. To the contrary, if you (accidentally) change settings, you end up with conflicting configuration files - one in the rom folder and one in the system folder. That’s why I stick with the system folder.


What kind of settings do you change with the GUI?
Personally, I tend to set everything up in manually written config files so if I want to change something, I just edit the configs.

I personally just keep overlays in the “overlay” folder.

Kondo I have a batch script that can make the configs and probably the video settings (if all the same) for game settings. It’s at Hyperspin I will tag you.

Well, there is so much in Retroarch to try during gameplay, in particular Video settings (frame skip, throttle etc.). Of course you can edit everything outside of RGUI, but just in case (and also only accidentally), you may end up with two config files that conflict with each other. Probably a matter of taste :-). Cheers!

cosmo0! Sorry for bumping this old topic, but I am revisiting @Orionsangel bezels and I am getting the problem you are describing in your first post (the game screens are getting below the bezel like in your example https://ibb.co/jSjT9R ).

I have checked the lay files X and Y coordinates against the pngs, and indeed they are stored to be below the bezel (so ironically, I am getting correctly what the lay file has). You can even see in the lay file that the width and height are 1280x720, so I am assuming that if you are using a 1080p one (I do), the whole lay file stretches proportionately, idk.

Where you able to resolve this?

Orion, if you see this message and are able to shed some light in the matter, please do :slight_smile:

Thanks guys.

If the game is stretched out behind the bezel I adjust the screen with the slider controls. Mame saves it.

Thanks. The stretch is set in each game’s cfg right? I believe I have the default 1.0 for both X and Y.

Strangely I checked with another user and he is seeing it correctly from the get go, and his stretches are 1.0.

The default MAME horizontal and vertical bezels look fine on my set, so I might have something else configured to take the lay info exactly as stated, without taking the account the 1080p png vs the 720p lay cfg.

1 Like