Mac RetroArch Setup Tutorial for Arcade Games - Part I

Update June 2024: Some small, but great RetroArch news considered here. First, HDR screenshots work now! And the new function "Add To Playlist" is such an important usability improvement of RetroArch Playlists. Last section "Other Arcade Cores" also updated.

February 2024: so finally the RetroArch Tutorial Part II is out, but please be sure to have gone through this Part I first 😊

21 April 2023: Added a short section as regards the Steam version of RetroArch.

20 March 2023: RetroArch 1.5.0 a.k.a. ‚The MacOS Release‘ (just kidding) was released - it is a huge improvement for Macs - https://www.libretro.com/index.php/retroarch-1-15-0-release/ and everything in this article also applies to the new stable build. I have not tested the Steam version, though because updating the newest Nightly manually is very convenient on MacOS, as also described below.

About this posting: As the new Vulkan driver for MacOS is a game changer for Retroarch in MacOS, it became necessary to update this entry. Don't be too afraid of this lengthy article, it's a checklist of what RetroArch is capable of, and the result of this work is an unmatched gaming experience, even in old-school arcade games.

INITIAL SETUP

Download: Download the Metal Build of RetroArch (as so much is currently going on and we want to use the Vulkan driver (now default in MacOS), I always recommend a nightly build, but stable builds are also quite fresh.

You need the latest RetroArch_Metal.dmg from this place.

MacOS Background Info: $HOME/Library on your Mac

The ~Library or $HOME/Library directory is a hidden directory in your User directory: press command+shift+.  - and all hidden directories appear, including the Library directory in your user directory. Drag this folder it into the Finder Favorites on the left, so that it's easily accessible. You‘ll need it quite often (also useful for other app settings).

Move away old RetroArch Preferences: Can be very important if you screwed up earlier! Prior to installing and running a new RetroArch version, consider backing up/deleting from here previous preferences. They are located in ~youruser~/Library/Application Support/RetroArch (just rename the entire directory for the time being).

Install RetroArch into your Applications directory. Run it for the first time, and it will create a new directory in ~Library/Application Support

Steam Version

I installed the Steam version of RetroArch on my Mac for testing purposes (with quite some hesitation, as I otherwise do not use Steam). There are some interesting differences between the Steam version and the Standalone version:

Updating - is very smooth within the Steam ui (however, not decisive for me, as updating the newest nightly build by overwriting the app bundle is very convenient as well)

Controller setup - within Steam, preferred by some (also not decisive for me, as my controllers bind automatically in RetroArch standalone)

Cloud saves - that's frankly very cool, indeed, to have all your RetroArch saves at one place (in version 1.7.0 and nighties, a dedicated Cloud sync for Apple devices is built in and works quite nicely - discussed in this blog at a different place)

You are buying these add-ons with quite some additional software (e.g. all three shader types are bundled, you get a certain selection of cores pre-installed) let alone the logon to Steam. All in all, I clearly prefer RetroArch standalone for the time being.

In MacOS, you find the Steam RetroArch App Support directory here: 

~Library/Application Support/Steam/steamapps/common/RetroArch/ 

CHECK: Vulkan driver as default

As Vulkan is the biggest innovation of recent MacOS builds, be sure that you have the right version that defaults to Vulkan (especially if your retroarch.cfg comes from earlier times).

Background Info: RetroArch directory split in MacOS

Admittedly the default directory split of RetroArch in MacOS is a bit complicated, but as long as you are aware of them, it's no problem. For whatever reason, RetroArch uses three different file locations in MacOS:

- Applications directory: Only for the codesigned app bundle, which is very convenient! Because upgrading RetroArch does not remove anything of your own stuff, neither your configuration nor dedicated shaders or anything else. Means that upgrading to the latest nightly build ist just drag-and-drop and overwriting the old app bundle, RetroArch remains in an identical configuration state.

This is why I do not need the Steam build. Upgrading by drag and drop just works best for me.

- ~/Library/Application Support/RetroArch: Very important system directories are located here (see instructions above how to access them).

Just let me address some directories that are important for this post:

- config: Here you find retroarch.cfg, the global configuration file. In the event of significant changes, you may want to create a backup file from here before moving forward. Moreover, you find all the core-specific configurations in subdirectories named by this core. Very useful for core-specific or game-specific configurations. My game-specific shader configurations also belong into the FinalBurn Neo subdirectory located here. For further details, see Part II.

- cores: This is the directory, in which you download all RetroArch cores. See Part II for further explanations.

- playlists: These are the playlists for each core, as explained below. You can manually edit them, but again, I would suggest a backup before manually editing a playlist generated by RetroArch.

- screenshots: Apparently this is the directory for screenshot created from within RetroArch (during running game Quick Menu/Take Screenshot (currently does not work in HDR, a known bug)

- shaders: This is the directory used by RetroArch to download the stock shaders. You must also place your custom shaders into here. In case of the vulkan driver, the shaders must be in the subdirectory shaders_slang.

- ~/Documents/RetroArch: 

These directories are easily overlooked, but they are rather important:

- logs: If you want to debug a problem and turn on logging, the log files are stored here.

- saves: Another very very important directory/your treasury, this is where the cores save your core-specific saves. Another thing you want to backup frequently!

- states: This is where RetroArch stores save states, the RetroArch specific save of a certain state of the core. You should never mix saves and states in one game, you could run into issues.

- system: Very important for other cores than arcade that rely on bios and other system files. FinalBurn Neo, for example also saves the hiscore.dat here into a subdirectory. You also must place FinalBurn Neo samples into the samples directory here!

Next a recommendation - play safe with this setting: Turn OFF "Save Configuration on Quit" (in Settings/Configuration)

Why? With the default setting turned ON, everything you try out in the settings is saved once you quit RetroArch. As you configure a lot in RetroArch, mistakes will happen. In such cases, I am personally better off if I can just quit RetroArch and discard all changes that I have not saved manually. Of course you then must not forget to manually save configuration changes prior to exit RetroArch. Your choice.

From now on: Manually save any new configuration step (in Main Menu/Configuration File) – including the previous step! Otherwise you‘ll loose it at quit.

JOYPAD CONFIGURATION 

Many joypads work out of the box, but you need to be sure about it. All navigation is best done with the joypad. Besides an impeccable binding of your joypad controls, check the following:

Recommendation: Swap OK and Cancel (in Settings/Input/Menu Controls)

Really a matter of taste. Most of the in-game controls, including those of FinalBurn Neo, have DOWN as OK/Button 1 and RIGHT as CANCEL/Button 2. That’s why I prefer to swap it in RetroArch as well.

Optional: Set Menu Toggle Controller Combo (in Settings/Input/Hotkeys):

This is very important in order to (i) configure very important settings in the Quick Menu (below) and (ii) to safely exit Cores in any state. Choose between the available options (joypad left/right). I prefer L1 + R1, as it hardly comes into your way during gaming - but it may not be totally convenient for you with some cores that make use of L1 and R1, such as PS1 and N64. 

In very recent Nightly Builds, the joypad PS4 Home Button finally works in MacOS - and of course this button suits perfectly for switching to the Quick Menu.

Be sure that your Port1 Controls work perfectly!

Suggestion: Bind Analog Control to Digital Control (in Settings/Input/Port 1 Controls)

The consequences of this setting are nicely described, but as long as you do not need an analogue stick, it is easier to play, at least I do not play with the D-Pads of my PS4 controller. For single games, you can disable here during a game (remember: Menu Control set above).

ENABLE HDR (if available for you)

As explained in my Sneak Peek, only the Vulkan driver enables HDR on Macs. The option should be available under Settings/Video/

I recommend checking the HDR default settings because HDR monitors seem to vary sigificantly. In my case, these settings work far better than default settings:

Peak Luminance: 450.x (<- this setting should match with the peak luminance of your monitor)

Paper White Luminance: 80.0x

Contrast: 5.00x

Expand Gammut: OFF

In my case HDR gives a visible benefit, even when playing very old school games, thus highly recommended.

Update June 2024 - a  long-lasting bug is fixed now: HDR-screenshots from within RetroArch now work! As you trigger screenshots from within the Quick Menu, this is the perfect way to properly time your sceenshots.

ONLINE UPDATER (in Main Menu/Online Updater)

Only after perfect joypad configuration, head for the Online Updater. Things to update – basically all of those, most importantly the Core Info Files, the Assets, the Databases and the Slang Shaders:

Then download the Final Burn Neo Core (in Main Menu/Online Updater/Core Downloader):

CONFIGURATION: Game Directory (in Settings/Directory)

You will save a lot of time if you point RetroArch to your game directory, otherwise you need to go down from the root directory all the time.

FIRST START OF FINALBURN NEO (in Main Menu/Load Content/Start Directory)

Only now you can do your first start into FinalBurn Neo, best by choosing one of your favorite arcade games. Expect no glorious picture, as no shaders have been set so far.

Looks mediocre without shaders

FURTHER SETUP FROM WITHIN A RUNNING GAME (in Main Menu/Quick Menu)

Make friends with the Quick Menu! One of the peculiar things in RetroArch is that some important settings can only be done from within a running game. These settings will still apply to all games, unless you decide differently. By pressing the Menu Combo (configured above); you get into the Quick Menu of RetroArch, where all the following settings can be configured. 

Always remember: Without a running game, the configuration of the Quick Menu is not available.

Quick Menu - Shaders

Set a nice and easy CRT Shader (in Main Menu/Quick Menu/Shaders):

After setting Video Shaders to ON, also set Remember Last Used Shader Directory to ON.

Once you turn Video Shaders ON, you load a shader preset

Load a Shader Preset in shaders_slang/CRT – for a change, try crt-easymode-halation. 

Briefly switch back to the game and see whether it works. 

If you like what you see, go back into the Menu and head for Save/Save Core Preset. By this, all games run by FinalBurn Neo run this shader.

Save Core Preset is the nicest option for the beginning

Don’t get lost in all these different shaders. Good reliable shaders are of course CRT-GEOM and the deluxe variant.

As soon as you get accustomed with shaders, you might consider trying out the real thing: my Arcade Bezels with the koko-aio shader. Already the stock version of koko-aio is best in town.

Latency Settings - Preemptive Frames / Run- Ahead 

(alternatively in Main Menu/Quick Menu/Latency)

In the RetroArch Nightly Builds, Preemptive Frames come as a new options for reducing latency. The RetroArch team recommends to use Preemptive Frames whenever possible. For me, this works flawlessly in RetroArch - 1 frame just like in the Run-Ahead option. 

You may save this globally (under retroarch.cfg) or for the specific core (as Core Override - in Quick Menu/Overrides/) 

Saving as Core Override means that the Latency Setting only applies to this Core - FinalBurn Neo in our example. This might be convenient.

Should the game audio crackle in your system, try Run-Ahead instead of Preemptive Frames (but do not use the Second Instance for FinalBurn Neo):

In my tests, 1 Frame Preemptive Frame/Run-Ahead is very nice for FinalBurn Neo. I did also not experience any audio issues so far.

With the Preemptive Frames/Run-Ahead feature of RetroArch, you get very snappy gaming experience with zero latency. With newer versions of FinalBurn Neo, also highscores start working together with these settings. Where hiscores do not work, consider as Save State (unless you play in the Hardcore Mode of RetroAchievements, where Save States are forbidden).

Hiscore Support in FinalBurn Neo 

It's another great development that hiscore support gradually arrives in FinalBurn Neo, even if you have Preemptive Frames/Runahead enabled. There are two prerequisites:

- Hiscore support must be enabled in the FinalBurn Neo core options (it's enabled by default)

- You must manually download the hiscore.dat file in Main Menu/Online Updater/Core System Files Downloader

You can easily check whether it works with 1942 or 1943. If hiscore works with some games but not with others, the game itself probably does not yet support it. It's always an alternative to save a Save State (again, unless you play in the RetroAchievement Hardcore Mode, where Save States are not allowed).

VIDEO CONFIG (new): Force 60 Hz (Quick Menu/Core Options)

With recent FinalBurn Neo versions, the best way of getting smooth gaming experience on 60 Hz fixed rate monitors is to turn this setting ON:

This is a very good compromise for 60 Hz fixed rate monitors, as some games run originally at non-standard rates. For example, Moon Patrol runs at 56.74 Hz, which results in a very jittery scrolling during gameplay. Forcing this game to 60Hz makes it a bit faster than on original hardware, but scrolling is flawlwess.

Side note: This setting also seems to help with Apple ProMotion displays, which do not seem fully supported by RetroAch (see issue https://github.com/libretro/RetroArch/issues/14807).

As with any Core Option changes, closing the game and a restart is mandatory. Core Options are always saved by closing/restarting the game.

Max Swapchain Images -> set to 2 (Settings/Video/Synchronization)

Although the documentation presents this option in connection with latency, setting this option from 3 to 2 made a huge positive impact on scrolling, in particular on my old Intel iMac Late 2013. It's also completely safe for me to set this option on the M1 Mac Mini, but the effect was far more pronounced on the iMac.

Be careful to watch out for performance issues -> if not, highly recommended!

Note: If you reach this point, you should have perfectly smooth arcade video under FinalBurn Neo. This works for me even on the old Intel iMac Late 2013. If not, check again. Intel Macs with integrated Intel video will not make it, though.

Automatic Frame Delay (optional)

While all other default video sync options seem ok for arcade games, this one seems to further help in reducing latency. You can also choose this feature alone for reducing latency if you do not want to head for the Runahead feature described before.

This very new feature is described in this article very nicely.

ALTERNATIVE VIDEO CONFIG: No Automatic Frame Delay, but Max swapchain images reduced to 2

With the "Force 60 Hz" Core Option of FinalBurn No, the following is virtually irrelevant, but I leave this legacy information here:

If your scrolling shows some micro-stuttering and you have (like me) a Fixed Refresh Rate Monitor running at 60 hz, you can only achieve acceptable results, which never will be optimal. Warning: If you look for this in the Internet, you get hundreds of best combinations, it's not an easy thing to choose, and this is my best guess.

These are the topics you need to closely look into:

Settings/Video/Output/Estimated Screen Refresh Rate: let Retroarch run until you reach 2048 samples, then the deviation should be below 3.5%, press RETURN to transfer this refresh rate to the Vertical Refresh Rate setting above

Settings/Video/Synchronization/Automatic Frame Delay - OFF

Settings/Video/Synchronization/Max swapchain images - 2

Why? Frankly I do not know, but that seems to be my best settings for acceptable scrolling.

Compared to this, the output on a 144 Hz GSync gaming monitor is impeccable, no micro-stuttering at all. There you just head for one option:

Settings/Video/Synchronization/Sync to Exact Content Framerate (GSync, FreeSync) - ON 

And you are set and done.

Setup of RetroAchievements

As a huge fan of RetroAchievements, its setup is mandatory for my basic RetroArch setup. Desribed here in detail.

CREATE A PLAYLIST (in Import Content)

Although you can start each game manually via the “Load Content” Command, it is nicer to create a RetroArch Playlist. I tend to set up this playlist rather slowly by adding individual games → Scan File. If you scan an entire directory, you get all game clones in, and that’s then not much difference to the Load Content command.

In Playlists, you then assign each game to a Default Core. Later on, you can also Reset the Core Association or set a different one.

Unfortunately, the automatic assignment of RetroArch will spread some of the arcade games across the different Cores (see the above screenshot). 

MANAGE YOUR PLAYLISTS (Update June 2024)

In recent RetroArch builds, a brand new functionality arrived, which is very important for Playlist Management: "Add to Playlist"

Note: It seems that the "Add to Playlist" option is not visible by default. If this also happens to you, head for: Settings/User Interface/Menu Item Visibility/Quick Menu -> and enable "Show 'Add to Playlist'. I have no idea whether this seems to be set off by default. 

You can find this in two places: Either in the Playlist Entry of the game or in the Quick Menu when you run the game. As the name indicates, it allows you to copy the entry to another Playlist. That's just perfect to consolidate different Arcade Playlists within one.

As explained above, the Playlist Entry does not decide which core you run: 

Via "Set Core Association", you tell RetroArch which core to launch by default. The Playlist is irrelevant for this setting.

 

Congratulations: You are now basically set to enjoy arcade games with FinalBurn Neo!

Upgrading

Upgrade RetroArch: As long as you are fine with your current settings, you can just download and install a new version of RetroArch. As all your cores and settings are located in ~/Library/Application Support, nothing will be deleted. If you are unsure, just move this directory away and start from scratch. You can then also migrate manually, most importantly playlists or other very individual settings.

Upgrade FinalBurn Neo Core: From the Online Updater, you can update FinalBurn Neo to the latest Nightly Core (and this is what you download via the Online Updater). May I also note that FinalBurn Neo has been very stable for months now. I have not experienced any crashes of RetroArch that could be associated with FinalBurn Neo. It seems that the buggy times of the RetroArch/FinalBurn Neo combo on Macs is a matter of the past.

What about the other Arcade Cores?

Currently FinalBurn Neo clearly has the edge over all other Arcade cores in RetroArch. 

• FB Alpha Cores: I do not touch them, they give no edge over FBNeo, seem to be for older machines
• MAME 2000: I do not touch them, this is a 20 years old MAME for low-end computers
• MAME 2003: That’s a fallback core for games that do not run in FBNeo. Very little use, however. The "Plus" version of 2003 might be worth a try as it implements further changes, but it can be very buggy (the plus version stabilized on Silicon Macs over the past few months a bit). Supports the Run-Ahead feature as a big plus.
• MAME 2010: No support of Silicon Macs, immediately crashes. Another fallback core for games that do not run in FBNeo. Not as stable as MAME 2003, however. Does however not support the Run-Ahead feature.
• MAME current: Significantly improved over recent months in MacOS and is both stable and performant. Koko-aio shaders now work identically to FinalBurn Neo. It's also a nice fallback core for games that FinalBurn Neo does not support. Probably most precise emulation. Drawbacks are no RetroAchivement support and long loading times.

And finally the RetroArch Tutorial Part II is out now.