MAME:Installing

MAME (formerly an acronym for Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers, and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The current implementation is based on the v3.02.04 core and supports most features.

Installation

You will need to install MAME, provide it with the Next firmware ('boot ROM'), and get the NextZXOS image:

1. Get MAME

Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with Holub's latest Continuous Integration (CI) builds as described at the end of this article.

MAME for macOS now requires the SDL3 library.

• Windows: Download MAME for Windows.
• macOS: Download the latest SDL3 library as .dmg, and copy its SDL3.xcframework and share folders to ~/Library/Frameworks, as instructed in the included INSTALL.md file. Then download MAME for macOS.
• Linux: Install MAME from the flatpak repositories by running:

sudo flatpak install org.mamedev.MAME

Windows and macOS will likely prevent you from launching MAME (and the SDL3 framework) directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or build from sources.

• Official MAME git

• Git of Holub's fork (this may contain fixes and features before they are merged into the official repository; see instructions at the end of this article).

2. Get TBBLUE (the Next firmware or 'boot ROM')

Put the file tbblue.zip into MAME's roms folder. Don't extract it; MAME will look for the zip file when you select the "tbblue" machine.

Note: The ROMs in this zip are what is uploaded to the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to that are on the distro, SD card, or SD image file.

3. Get the NextZXOS Image

Get an SD card image file of the NextZXOS operating system. Some of the official images on specnext.com/latestdistro do not currently work with all emulators, but all images from https://zxnext.uk/hosted/ work with both MAME and CSpect, like this 2GB image. Extract the image cspect-next-2gb.img from the zip archive, then point MAME to this image with the -hard1 option (or select the image from the menu inside MAME).

Usage

MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The mame.ini file and folders like roms, bgfx, plugins, language, ... are expected there, unless the mame.ini file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for mame.ini first in the ~/.mame folder. You can use the option -inipath to point MAME to a different path for the mame.ini file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a mame.ini file. Most of the features are also available through MAME's UI, although that takes more time to configure.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx  -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img

Let's cover some useful options:

1. Run inside a window and with no mouse support, until you get familiar with the UI keys:

   > mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img

   To launch the Linux flatpak version using the same options:

   > flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img

2. Activate UI keys on startup:

   > ... -ui_active

3. Don't show the info popup on startup:

   > ... -skip_gameinfo

4. Run with debugger. If you don't request this on startup, you won't have access to it:

   > ... -debug

5. Use "crisp" pixels:

   > ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered

6. No joystick connected to PC (having this may slightly speed up MAME's startup, but remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick):

   > ... -joystickprovider none

7. Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):

   > ... -confirm_quit

Check the official MAME documentation for more advanced usage.

Security: Allowing MAME to Run on Windows and macOS

On Windows, you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. (More details needed here.)

On macOS, MAME will not open at first. Instead, this dialog will appear:

“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.

Click “Done”. Then open System Settings -> Privacy & Security, and scroll down to the message mame was blocked to protect your Mac. Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

You will then need to repeat this process for the SDL3 framework.

From now on, you can launch this version of MAME without warnings. However, you will need to repeat this each time you update MAME or the SDL3 framework.

Keys

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on macOS).

Some UI keys:

• F3 - soft reset
• Shift+F3 - hard reset
• F4 - sprites/tiles/font viewer (Enter, ], [)
• F5 - pause emulation
• F6 - save state
• F7 - load state
• Tab - emulator settings
• ~ - menu
• ` (backtick) - debugger (when enabled by starting MAME with -debug or -d on the command line)
• PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
• Esc - exit (exits menus but also the entire emulator - see -confirm_quit option above)
• F11 - DivMMC NMI
• F12 - Multiface NMI

Check the default keys documentation for more.

Changing the UI toggle key

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

• Run MAME without any command line arguments (except maybe -window) to open its GUI.
• Press TAB to enter the General Settings menu.
• Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key, e.g., Right Alt / Alt GR.
• Return to the previous menu twice, then choose Save Settings.

Creating and manipulating the NextZXOS SD card image

Most users will be fine using the pre-built SD card image mentioned above. The following guide is provided only for those wanting to create a NextZXOS SD card image from scratch.

Download the latest official NextZXOS distribution zip file (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

Download the hdfmonkey "jjjs build", a variant of the hdfmonkey tool that includes some unique features. The archive at this link also contains pre-built binaries for Windows x64, macOS x64, macOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described here.)

Extract sn-complete-WX.YZ.zip into a subdirectory like snWXYZ. Now, to create a 1GB image called NextZXOS.img, run these commands:

hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /

The first creates an empty 1GB image and formats it with the best FAT parameters for that image size.

The second recursively copies all the content of the directory snWXYZ to the image, preserving the directory structure inside, starting from the root / in the image.

One advantage of this method is that the image takes up only the space used on the image instead of its full 1GB. On Linux or macOS, use du -h NextZXOS.img to verify. On Windows, see the File Properties dialog.

The fastest way to transfer a file or a directory (including all its contents, recursively) to an image is by using a single put command of hdfmonkey (or putdir to transfer to an existing directory).

The most convenient tool to copy of all the contents from the image to a folder outside of the image is 7-zip. On Windows, use the 7-zip GUI. On macOS and Linux, see this Wiki page.

MAME Plugins and Scripts

Some useful MAME plugins and scripts for Next developers and end users are listed here. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

Continuous Integration MAME Builds

MAME is updated on a release schedule, but the latest Continuous Integration (CI) builds often contain new features or bugfixes. These are discussed on the Next Developer Discord.

CI builds are available in two locations:

• The official MAME repo Actions page, and

• Holub's MAME repo Actions page (recommended).

Of these, Holub's repo tends to contain the most recent fixes before they are accepted to the primary repo. MAME CI builds are available for Windows, Linux, and macOS and updated automatically a maintainer commits code or pushes to the primary repo.

You need to be logged in to github to download CI artifacts, so sign in or sign up.

To install a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the latest official release if you haven't already. Then back up your main binary (mame.exe or mame) from its installation location, so you can restore it if the CI build doesn't work or you don't like it.

Then open your preferred "Actions page" link above, select your architecture (CI (Windows), CI (Linux), or CI (macOS)) in the left-hand filter, and click on the first workflow run item in the main list that has a green "completed" checkmark.

Scroll down to the Artifacts section at the bottom (remember: you need to be logged in to see it), then click the Download button on the right. Unzip the downloaded file and copy the main binary (with the same name as above) to your MAME install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

More MAME related links

MAME documentation.

Report any issues with the official version of MAME on the bugtracker.

For Linux users, there are more tips (how to compile MAME from source, how to configure it to not use CWD as the starting path for resource directories, how to mount or create image files) on this page.

Stable Controller IDs: By default, MAME does not assign stable numbers to input devices. For instance, a game pad controller may be assigned to “Joy 1” initially, but reassigned to “Joy 3” after restarting. For hints to fix this, see: Youtube - Mapping your controllers for stable IDs and: Stable Controller IDs for MAME.