RetroArch 1.17 release & RetroArch Setup Tutorial - Part II

Update June 2024: Besides minor tweaks all over the document, I included a dedicated RetroArch Cloud Sync section for FinalBurn Neo, as this cannot be put into the official documentation.

This February 2024, RetroArch reached another milestone with the release of the stable version 1.17. The significance of this frontend for the emulation community cannot be overestimated - it's the foundation/inspiration for many other projects and of course the home of an ever growing list of cores that run under this frontend. But it's also a steady inspiration for new concepts and ideas - with some of these ideas remaining in an experimental mode, while others becoming very successful and influential.

This is a follow-up to this post about configuring RetroArch from scratch - Part I.

So let's start Part II of the RetroArch tutorial with a focus on Arcade games - but most of this applies to other cores as well. As you may expect, this post is work in progress and will grow over time. If you are interested in some special RetroArch topics, just leave a comment below.

Even with 1.17 being out, let me suggest to use nightly builds.

1. Use nightly MacOS builds: 

The nightly MacOS builds of RetroArch have now been stable for several years. I can recommend using them instead of the stable builds. For example, new version 1.2.7 of MoltenVK (the Vulkan layer for MacOS) just landed two days after the stable 1.17 - apparently, this plugin is essential for RetroArch in MacOS, so you would not want to miss this update. But I do not mean that you should update RetroArch every day, but if you do, download a nightly build to benefit from the latest updates.

If things turn out strange for you, you can easily downgrade by installing the stable version over the nightly build. As shown in Part I, updating the app is simple, and you will not loose any of your settings.

2. The concept of Cores

RetroArch alone does not launch any game, but its cores do. Within the RetroArch framework, a lot of essential software is harmonized: With a very few exceptions, all the settings we‘ve discussed in Part I are global RetroArch settings that apply irrespective of the underlying Core. You find them in the RetroArch menu under Settings. In contrast, the Core Settings (discussed in a minute below) apply to one core only. They also behave quite differently to RetroArch settings.

Updating a Core is done within RetroArch in Main Menu/Core Updater. So for staying up-to-date with an emulator, you do not need to update RetroArch every single day. While I very often update the FinalNurn Neo Core in the Online Updater (more or less daily), I update RetroArch just once a month or less frequently - but then with a nightly build.

As shown in Part I of this tutorial, my current default Arcarde games core is FinalBurn Neo. It is still best of its class.

Some emulators come with different core versions, very prominently MAME. On Macs, the following MAME cores are interesting:

• MAME (current): The latest and greatest version, however with a large core to load.
• MAME 2003: A popular core built on MAME 0.78 released back in 2003, thus lightweight, but you won‘t get all the improvements of the last 20 years.
• MAME 2003plus: Tries to backport improvements to MAME2003. It can be buggy on Silicon Macs in my own experience, e.g. significant slowdowns with Gyruss. 

Please note that no MAME core officially supports RetroAchievements, even if MAME (current) triggers them in some games. MAME 2010 does not work on Apple Silicon for me.

3. The RetroArch Configuration Concept 

This section is rather intense, but understanding the different files that RetroArch uses for configurations is essential. You need to consider at least four stages of RetroArch configurations.

First: RetroArch .cfg files - triggered in the RetroArch Settings Menu (no need to run a game)

• ~/Library/Application Support/RetroArch/config/retroarch.cfg: This file contains the global RetroArch configuration found in RetroArch under Settings, which applies in the absence of Core-specific or Game-specific configurations. This is your most important configuration file, so especially at the beginning of your work in RetroArch, consider to backup this file from time to time. You can edit it with any text editor, but it's basically safer to save the configuration in RetroArch: Main Menu/Configuration File/Save Current Configuration
•  ~/Library/Application Support/RetroArch/config/FinalBurn Neo/FinalBurn Neo.cfg: This is an example for a Core-specific configuration. It overrides the global configuration and saves only these options that are different from retroarch.cfg. When planning your configurations, be very careful and consider which Core-specific configurations you really need. Besides the text editor, you save a Core-specific configuration when running a game: Quick Menu/Overrides/Save Core Overrides
• ~/Library/Application Support/RetroArch/config/FinalBurn Neo/1942.cfg: This is an example for a Game-specific configuration. Same principles apply as for the Core-specific configuration. Apparently, those configurations override both Core-specific configurations and retroarch.cfg. Be even more careful to use them. Besides the text editor, you save a Game-specific configuration when running a game: Quick Menu/Overrides/Save Game Overrides

The .cfg files are only the beginning, as other files are responsible for further configurations that are not contained here.

Second: Core Options (.opt) - triggered in the Quick Menu within a running game

We already worked with Core Options in Part I of the RetroArch setup when enabling 60Hz in FinalBurn Neo or disabling Patched Romsets in order to use RetroAchivements. Apparently these options are specific to the respective Core, so that the .cfg files cannot cover them. So while the FinalBurn Neo.cfg file covers global RetroArch options, the FinalBurn Neo.opt files covers
options that are specific to this Core alone. Be very careful to remember this distinction.

Core Overrides (.cfg) versus Core Options (.opt)

The handling of Core Options is very different to a .cfg file: Launch a game with the respective core, then head to the Quick Menu and look for the Core Options.

You can only reach Core Options during a running game.

Now comes the trick: Once you have changed a Core Options, close the game, and only this will save the change in the Core Options. This is very counter-intuitive, so be careful that you understand what you are doing. After a restart of this core, you will see that the Core Options has changed. 

Third: Controller Configurations (.rmp) - triggered in the Quick Menu of a running game

From time to time, you need to adjust your controller configurations to a Core or a specific Game (e.g. the Arcade classic Bank Panic requires an entirely different controller configuration for shooting at the three doors in a way that your controller can deal with).

• Location of Remap files: ~/Library/Application Support/RetroArch/config/remaps/FinalBurn Neo/bankp.rmp (example for a remap file of Bank Panic in FinalBurn Neo).
• Configuration: While running a game, go to Quick Menu/Controls/Port 1 Controls/ - here you can assign the buttons of this Core/game differently from the default configuration. After the change, head back to the game and test the new configuration on the fly.
• Saving: If the new controller configuration works, you must immediately save it from within the game. So while still being in the game, go to Quick Menu/Controls/Manage Remap Files/ - here you can either save a Core Remap File or a Game-specific Remap file.

Fourth: Shader Configurations (.slangp) - triggered in the Quick Menu of a running game

Note: As I exclusively use the Vulkan gfx backend, I only refer to .slangp configurations here. If you still use OpenGl in MacOS, you can achieve the same result with .glsl configurations.

As explained in Part I, it is essential to activate a shader for arcade games, as they look quite bad without a decent shader. Again, the shader configurations are saved globally, per Core and per Game.

• ~/Library/Application Support/RetroArch/config/global.slangp: If you have this file, you have saved a global shader preset in RetroArch. So this shader applies unless there is a Core-specific shader preset or a Game-specific shader preset. I prefer not to have a global shader preset, as shaders can differ quite significantly, e.g. between Arcade machines (slot mask) and handhelds (dot matrix) - but it's more a personal choice, as you can override the global preset anyways.
• ~/Library/Application Support/RetroArch/config/FinalBurn Neo/FinalBurn Neo.slangp: Example for a standard FinalBurn Neo shader preset, which applies in the absence of a game-specific shader preset. That's a quite solid choice, by which you have one identical shader preset for the FinalBurn Neo Core.
• ~/Library/Application Support/RetroArch/config/FinalBurn Neo/1942.slangp: Example for a game-specific shader preset. I work with these presets for my game-specific Arcade artwork based on the brilliant koko-aio shader, as discussed in this blog post. With this concept, each game automatically launches its specific shader preset.

Choosing a shader preset: From within the game, go to Quick Menu/Shaders/Load Preset - the RetroArch standard preset are located under: ~/Library/Application Support/RetroArch/shaders/shaders_slang/ - and koko-aio, the highest recommended shader for Arcade machines, is under /bezel/koko-aio/Presets_ng/ ... try for example Monitor_Ambilight_Immersive.slangp.

Saving a shader preset: Once you find a shader preset that you like, go to Quick Menu/Shaders/Save Preset - then save it either for this Core or for the specific Game.

Summing It Up

So it's very important to understand this concept. In forum posts, you will often find frustrated users that either cannot find an option or they fail in saving the new configuration. In most cases, these users look at the wrong place or try to save into the wrong configuration file. And if you practice this a bit, you'll see that it's not that hard to memorize.

4. Core Save Files vs Save States

First the important message: Never mix core save files with save states, as it can potentially mess up things for you!

• Core Save Files (~/Documents/RetroArch/saves/): These files save the status as the system used to do, e.g. the classic saving in game consoles. In Arcade games, these are hiscore files, and they are e.g. saved under ~/Documents/RetroArch/saves/fbneo/1942.hi in an unreadable format.
• RetroArch Save States (~/Documents/RetroArch/saves/states): Contrary to Core Saves, you can trigger Save States at any time during a game, and it saves the exact state at this moment of the game. Save States can be very helpful to help out in a difficult moment of the game, as you revisit the game at exactly that moment. For exactly this reason, Save States are not allowed when playing a game in the Hardcore mode of RetroAchievements - because this is not the way as the game was played back then.

Bearing the initial message in mind, decide wisely which way you want to go when saving games. I generally very much prefer Core Save Files over Save States. Should you want to switch from one save method to the other for a certain game, seriously consider to backup and move away the other save files. Mixing up these two methods in one game can result in very unpredictable results, including the loss of a save file (I know from own painful experience).

Final recommendation: Always backup your save and states directories, they should be a gem to you, as they cover your RetroArch gaming history. They are nicely portable over systems!

5. Screenshots - HDR Screenshots now work in the Vulkan backend!

As discussed in Part I of the tutorial, HDR screenshots work now as well.

Alternatives: Pause RetroArch (keyboard: p) and take a screenshot with the MacOS tool, that's good enough for me right now. I might want to discuss third-party tools at this place as well.

(do do: discuss https://github.com/obsproject/obs-studio)

6. Don't forget the Libretro Docs!

Finally, never forget the ever-growing RetroArch documentation that has improved significantly over time.

MacOS starting page: https://docs.libretro.com/guides/install-macos/

Just look around, there is tons of further information here.

Some recommended readings from Libretro docs:

• Getting started with arcade emulation
• FinalBurn Neo
• Introduction to shaders
• RetroArch Cloud Sync for Apple devices

7. RetroArch Cloud Sync for FinalBurn Neo - Highscores

Speaking of the RetroArch Cloud Sync function: Nothing to repeat here from the official docs (link above), but there is one peculiarity with FinalBurn Neo - be very careful with this option when it comes to your precious highscores:

Setting turned OFF: your highscores are saved in /saves/fbneo

Setting turned ON: your highscores are saved in /saves/FinalBurn Neo/fbneo

The obvious advantage of this setting turned on is that all RetroArch core saves are separated from each other in separate directories. But this speciality with FinalBurn Neo needs to be always reminded - as you can easily mix up across multiple devices.

As explained in the official documentation of Cloud Sync, identical options across your devices are key.

But be very careful with the second option: Sort Saves into Folders by Content Directory

Also activating this option will provide some veritable chaos, as RetroArch will then save your Finalburn Highscores here: /saves/FinalBurn Neo/FinalBurn Neo/fbneo (!)

So be absolutely sure what you do with these option. My advice is to use the "Folders by Core Name" option, but not use the "Folders by Content Directory" option.

But also: If you change any of these options, be sure that your existing saves move as well! Otherwise you will not find your saves, as they are then expected in a different directory. Manual copying is then advisable.