This is a major achievement - after several unsuccessful attempts, it seems that I have finally managed to create a near-perfect MAME Homebrew setup on my Mac. Let’s explore why this effort was worth the time.
Why does this matter?
Managing your MAME install via Homebrew should address the following major issues around any MAME installation:
MAME system and user files stay separately: With this setup
the MAME system files, which are regularly upgraded via Homebrew, stay in the Homebrew repository of your Mac, while
your user data, such as inis, rom files, artwork and all other content, are in a separate folder of your Mac, where MAME can find them.
Seamless upgrades: By keeping MAME system data separate from your user data, you upgrade MAME via Homebrew without the need for any user data migration.
No Gatekeeper woes: Running MAME via Homebrew does not hit Gatekeeper restrictions. MAME is treated like any other CLI tool installed through a trusted package manager. This is why you can launch it without the “macOS cannot verify the developer” or “move it to the bin” popups.
Launch MAME from anywhere: Just open the Terminal and type e.g. mame 1942, and the game launches. It is no longer needed to launch MAME from the home directory.
With only one minor deficiency that needs a workaround as explained below, it’s ready. It’s really great to keep MAME up-to-date in an admin-friendly way.
Requirements for this setup on your end
ARM64/Silicon Mac (for the time being, but Intel Macs only require minor changes)
Basic Terminal knowledge (my recommendation: iTerm2 app)
Basic Editor knowledge (my recommendation: Visual Studio Code app)
An existing Homebrew installation (for Apple Silicon)
Understand how to access and use the hidden folder $HOME/Library/Application Support/ folder of your user account $HOME
Let's start from scratch!
Step 1 - install MAME via Homebrew
In the Terminal
brew install mame
brew install rom-tools
(rom-tools are optional, if you also want to have MAME’s cli-tools for rom management installed)
After installation, do not start MAME, as we have plenty of further things to do.
Step 2 - create plain MAME ini files
In the Finder, create an empty directory of your choice, for this setup it will be
$HOME/Games/mame
Technical Note: This folder is only a precautionary step for the time of the setup, after completion of this setup, you can delete this folder.
In the Terminal, change into this new directory and execute:cd $HOME/Games/mame
mame -cc
This creates the initial files
mame.ini and
ui.ini in this folder. Don't worry about the error about the missing plugins - it comes expected.
Step 3 - create an empty MAME Application Support folder
It is important that you start fresh, so please check in your Application Support folder whether any prior MAME installation has created a mame directory - if so, rename it and keep it as a backup.
After this, go back to the Terminal, and from within your
$HOME/Games/mame folder and start MAME for the first time:
mame
You should enter the MAME User Interface (at the time of this writing, version 0.283), exit again by
Esc. By this first launch, a
cfg folder has been created in your
$HOME/Games/mame directory - this is not of our interest.
Importantly, also a fresh folder in
$HOME/Library/Application Support/mame was created. This will be the place for your User data.
Step 4 - edit mame.ini and move user data to the right place
Now the most crucial part of the setup comes by setting up the correct mame.ini file. We will edit the mame.ini file we have created in Step 2 above.
Let's see first what we want to achieve - User Data first, this folder structure has to be set up manually (without the roms and software subfolders, only for illustration):
Technical note: These folders contain User data of various kind, as briefly explained above. In principle, they should not be affected by an actual MAME Homebrew update. Anything here is manipulated by you, but not Homebrew.
Please move all of your user data into the appropriate directories. The root directory of MAME should remain empty for now.
In contrast, the system data provided by Homebrew covers the following directories. These have already been set up automatically by the Homebrew installation of MAME:
Technical note: There should be no need for you to manipulate these folders, so let Homebrew deal with them. As an exception please already take note of the artwork/bgfx folder, which we need to cover in the last step of this setup.
As soon you have set up the User Data Structure, the mame.ini file needs to be changed as follows: Starting from line 7:
#
# CORE SEARCH PATH OPTIONS
#
homepath "$HOME/Library/Application Support/mame/"
rompath "$HOME/Library/Application Support/mame/roms"
hashpath /opt/homebrew/share/mame/hash
samplepath "$HOME/Library/Application Support/mame/samples"
artpath "$HOME/Library/Application Support/mame/artwork"
ctrlrpath "$HOME/Library/Application Support/mame/ctrlr"
inipath "$HOME/Library/Application Support/mame;$HOME/.mame;.;ini"
fontpath "$HOME/Library/Application Support/mame/fonts"
cheatpath "$HOME/Library/Application Support/mame/cheat"
crosshairpath "$HOME/Library/Application Support/mame/crosshair"
pluginspath /opt/homebrew/share/mame/plugins
languagepath /opt/homebrew/share/mame/language
swpath "$HOME/Library/Application Support/mame/software"
#
# CORE OUTPUT DIRECTORY OPTIONS
#
cfg_directory "$HOME/Library/Application Support/mame/cfg"
nvram_directory "$HOME/Library/Application Support/mame/nvram"
input_directory "$HOME/Library/Application Support/mame/inp"
state_directory "$HOME/Library/Application Support/mame/sta"
snapshot_directory "$HOME/Library/Application Support/mame/snap"
diff_directory "$HOME/Library/Application Support/mame/diff"
comment_directory "$HOME/Library/Application Support/mame/comments"
share_directory /opt/homebrew/share/mame/share
Technical notes: These changes to the folder paths reflect the structure outlined above. It is important that virtually all output directories are placed in your User directory, since MAME will write data into them. This arrangement also ensures that MAME does not write data into the directory from which you launch the program. For this reason, you can eventually delete the
$HOME/Games/mame folder, as it is no longer needed.
Change of line 256 (assuming that you want BGFX shaders):video bgfx
And starting from line 253:
#
# OSD VIDEO OPTIONS
#
video bgfx
numscreens 1
window 0
maximize 1
waitvsync 0
syncrefresh 0
monitorprovider auto
Starting from line 350:
#
# BGFX POST-PROCESSING OPTIONS
#
bgfx_path /opt/homebrew/share/mame/bgfx
bgfx_backend metal
bgfx_screen_chains crt-geom
bgfx_shadow_mask slot-mask.png
bgfx_lut lut-default.png
bgfx_avi_name auto
Technical note: Quite importantly, bgfx uses the Homebrew path.
Then move mame.ini: The modified mame.ini file is ready for being moved into the $HOME/Application Support/mame folder.
Step 5 - workaround for BGFX Artwork
Now the only workaround that needs to be applied: For some reason, the folder /opt/share/mame/artwork/bgfx must be copied into your user artwork directory. I tested several mame.ini settings, but multiple artwork folders proved unreliable and caused errors with the BGFX shaders. Therefore, copy your BGFX folder by executing the following Terminal command:
cp -R /opt/homebrew/share/mame/artwork/bgfx "$HOME/Library/Application Support/mame/artwork/"
These are the only system files that require manual upgrades if the BGFX artwork is changed in future MAME versions. This appears to be a negligible issue - according to GitHub, the BGFX artwork folder has seen only a minor change to a single file in the past two years. However, if in doubt, simply replace the BGFX artwork folder by running the above Terminal command after upgrading MAME.
Step 6 - test, backup and tweak further
MAME should be ready for testing. From any directory, fire up one of your favorite games in the terminal, e.g. mame 1942, and all should be up and running - including BGFX
If everything runs as it should be: This is a good moment to backup your mame.ini for further use.
You then can apply any further tweaks to mame.ini, such as
If all is fine, just enjoy your MAME installation and further upgrades from within Homebrew! As always, feedback would be much appreciated.
To-Do:
- explain differences on Intel Macs
- should also work under Linux
No comments:
Post a Comment
Comments are welcome - spam and ads will be removed!