MAME (formerly an acronym of 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 existing implementation is based on the v3.02.01 core and implements most of the features.

Installation

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

1. Get MAME

Windows: Download MAME for Windows.
macOS: Download MAME for macOS.
Linux: Install MAME from the flatpak repositories by running:

sudo flatpak install org.mamedev.MAME

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

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

2. Get TBBLUE (the Next 'ROM')

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

3. Get the NextZXOS Image

Get an SD card image file of NextZXOS. Some published images do not work with some emulators, but all images from https://zxnext.uk/hosted/#sd are now confirmed to work with both MAME and CSpect, like this one (the SD card image is the cspect-next-2gb.img file inside the zip archive). You will point MAME to this SD card image with the -hard1 or -hard2 options (or select the files 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.

Let's cover some useful options:

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

Activate UI keys on startup:
```
> ... -ui_active
```
Don't show the info popup on startup:
```
> ... -skip_gameinfo
```
Run with debugger. If you don't request this on startup, you won't have access to it:
```
> ... -debug
```

Use "crisp" pixels:

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

No joystick connected to PC (may slightly speed up MAME's startup):
```
> ... -joystickprovider none
```
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.

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

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, a dialog will appear saying:

“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.

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

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 Mac).

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

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.
Push TAB and enter the General Settings menu.
Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
Return to the previous menu twice, then choose Save Settings

Creating a NextZXOS SD card image under Linux

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the specnext website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

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

Creating and populating a SD card image using hdfmonkey

If you extracted sn-complete-WX.YZ.zip into a subdirectory named snWXYZ, and you want to create a 1GB image called NextZXOS.img and you have a "jjjs build" of hdfmonkey, then it's enough to do:

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

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

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

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. A command du -h NextZXOS.img shows the actual amount of disk space used by the image.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single put (or putdir, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip.

Creating and populating a SD card image using other tools

Create a disk image of at least 256 MB. The current complete NextZXOS distro requires at least 130 MB of disk space. This command will create a 256 MB SD card image; change the count value to make the image file as big as you want in megabytes:

dd if=/dev/zero of=NextZXOS.img bs=1M count=256

The rest of the commands in this guide must be run as the root user or using sudo.

You will need to install the dosfstools and parted packages if they are not already installed. Debian and Ubuntu Linux users can install these using this apt command:

apt install dosfstools parted

Mount the SD card image loopback device:

losetup --partscan --show --find NextZXOS.img

Create a FAT32 partition:

parted /dev/loop0 mklabel msdos
parted /dev/loop0 mkpart primary fat32 1MB 100%

Format and mount the partition under /mnt:

mkfs.vfat -F 32 /dev/loop0p1
mount /dev/loop0p1 /mnt

You can now copy all of the files you extracted from sn-complete-WX.YZ.zip into /mnt.

After copying the files, unmount and detach the loopback device (the SD card image):

umount /mnt/
losetup -D

Warning: the resulting image of this method, if the parameters of different steps aren't carefully chosen and matched, could be out of the official FAT specifications and/or the expectations of some of the existing programs or systems.

Mounting SD card images under Linux

Under Linux, you can use losetup to mount SD card images as loop devices. This lets you copy files to and from the image and perform other file management tasks as you would using any other filesystem.

Run the following commands as the root user to mount an image called sn-emulator-22.10a.img under the /mnt directory:

losetup --partscan --show --find cspect-next-2gb.img
mount /dev/loop0p1 /mnt/

After you are finished modifying the SD card image, cd out of /mnt, then unmount and detach the loopback device:

umount /mnt/
losetup -D

MAME Plugins and Scripts

Some MAME plugins and scripts that may be useful 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 due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the Next Developer Discord.

Continuous Integration (CI) builds are available from both the primary MAME repo and holub's GitHub repo. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out 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 release if you have not already done so. Then back up your main binary from its installation location - these are called something like mame.exe or mame. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

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

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as CI (Windows), CI (Linux), or CI (macOS) in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the 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.

MAME:Installing

Contents