MAME Source Code

Edit on Github | Updated: 11th April 2026

MAME Repository Structure

A guide to every top-level directory and file in this repository.

Glossary of Key Terms

If you are new to MAME’s source tree, this glossary covers the acronyms used throughout the page.

• AsmJIT - A lightweight library for generating machine code at runtime, used for JIT compilation of emulated CPUs directly into host machine instructions.
• BDF - Bitmap Distribution Format. A plain-text font format that stores glyph bitmaps. Used by MAME’s built-in UI renderer to draw on-screen text without depending on host OS font APIs.
• BGFX - A cross-platform rendering abstraction library that sits on top of Direct3D, OpenGL, Metal, and Vulkan. MAME uses it to implement post-processing effects such as scanlines, shadow masks, and bloom in a renderer-agnostic way.
• Catch2 - A header-only C++ unit testing framework. MAME’s tests/ suite is written against it.
• CHD - Compressed Hunks of Data. MAME’s disk image format, designed to efficiently store large hard drive and CD-ROM images with per-hunk compression and SHA1 verification. Managed by the chdman command-line tool.
• Doxygen - A documentation generator that reads specially formatted comments in C/C++ source code and produces browsable HTML or other API reference formats.
• Genie - A Lua-based build system generator, similar to CMake or Premake. MAME uses it to produce platform-specific Makefiles and IDE project files from a single set of Lua scripts kept in scripts/.
• GLSL - OpenGL Shading Language. A C-like language for writing GPU shader programs targeting the OpenGL/Vulkan graphics pipeline.
• HLSL - High Level Shading Language. Microsoft’s shader language for the DirectX/Direct3D graphics pipeline, used by MAME’s legacy Windows renderer.
• JEDEC - A semiconductor industry standard that defines, among other things, the binary format used to store the fuse-map contents of PLD/GAL chips. jedutil converts between JEDEC files and other internal representations.
• JIT - Just-In-Time compilation. A technique where emulated CPU instructions are translated and compiled into host machine code at runtime rather than interpreted one-by-one, giving a large speed boost. MAME uses AsmJIT for this.
• Lua - A lightweight, embeddable scripting language. MAME embeds a Lua interpreter to power its plugin system, the interactive console, and the Genie build system.
• NTSC - National Television System Committee. The analog television broadcast standard used in North America and Japan. MAME’s CRT shaders can simulate NTSC signal artefacts such as colour bleeding and dot crawl for authentic display output.
• OSD - OS-Dependent layer. The abstraction layer in MAME (src/osd/) that isolates all platform-specific code, including windowing, audio output, and input handling, so the rest of the emulator is portable.
• ROM - Read-Only Memory. In the MAME context, a dump of the binary data stored on the chips inside an arcade PCB or console cartridge. MAME loads these dumps to run the original software.
• SDL - Simple DirectMedia Layer. A cross-platform library providing a unified API for window creation, input, audio, and 2D rendering. MAME’s non-Windows OSD backends are largely built on SDL.
• Solenoid - An electromechanical coil that produces a strong linear push when energised. In pinball machines they drive flippers, pop bumpers, slingshots, ball launchers, and the cabinet knocker. Because solenoid sounds come from physical mechanisms rather than audio circuitry, they cannot be reconstructed from circuit simulation, so MAME uses recorded WAV samples for them.
• Sphinx - A Python-based documentation build tool that converts reStructuredText (.rst) source files into HTML, PDF, and other formats. MAME’s docs/ site is built with Sphinx.
• XSLT - Extensible Stylesheet Language Transformations. A language for transforming XML documents into other XML, HTML, or plain-text documents. MAME uses XSLT to render its XML layout files into HTML for the web interface.
• Z80 - The Zilog Z80, an 8-bit CPU from 1976 that powered a huge number of arcade games and home computers. src/zexall/ runs the Z80 Exerciser against MAME’s Z80 core to verify correctness.

Directories

The top-level directories in the MAME source tree are listed below, with a short summary of what each one contains.

Files

The most important top-level files are listed below, along with a short description of their role.

Renderer

Display Effect Artwork (artwork/)

CRT and display effect artwork assets used by the BGFX renderer. Contains PNG texture files for shadow masks, aperture grilles, and scanline overlays, plus a bgfx/ subdirectory for additional BGFX-specific artwork.

BGFX Renderer Assets (bgfx/)

Configuration and shader files for the BGFX-based renderer. Contains post-processing effect chains (chains/), GLSL/HLSL/Metal shaders (shaders/), and screen effect presets (effects/).

DirectX HLSL Shaders (hlsl/)

DirectX HLSL shader files for the Direct3D renderer (Windows). These are the equivalent of the BGFX shaders but for the legacy D3D pipeline. Includes effects for bloom, scanlines, phosphor, NTSC simulation, and more.

Documentation

Documentation Website (docs/)

Source files for the MAME documentation website. Built with Sphinx; contains reStructuredText source (source/), themes, and a Makefile to generate HTML output.

API Reference Generator (doxygen/)

Configuration and templates for generating Doxygen API documentation from the C++ source. Includes doxygen.config, custom HTML header/footer, and a stylesheet.

Games, Software and other Assets

Software Lists (hash/)

XML databases that describe every known software item (cartridges, floppy disks, cassettes, CD-ROMs, etc.) for every system MAME emulates. Licensed under CC0-1.0 (public domain). Contains 759 XML files, 5 legacy .hsi files, and a README - totalling around 141,000 individual software entries.

Purpose

Software lists serve two roles:

• ROM verification - MAME checks loaded media against the CRC32 and SHA1 hashes recorded here to confirm the image is a known-good dump.
• Documentation - Each entry records the title, publisher, year, serial number, region compatibility, PCB type, and other metadata that would otherwise be lost.

File Naming

Each file is named <system>[_<mediatype>].xml. Systems with only one primary media type (e.g. nes.xml, snes.xml, gameboy.xml) have no suffix. Systems that shipped software on multiple media get one file per type:

For example, the Atari 800 has a800.xml (cartridges), a800_flop.xml (floppy disks), and a800_cass.xml (cassettes) as three separate lists.

XML Structure

Each file has a <softwarelist> root element. Every software item is a <software> entry:

<softwarelist name="nes" description="Nintendo Entertainment System cartridges">
  <software name="mario" cloneof="marioeu">
    <description>Mario Bros. (Europe, rev. A)</description>
    <year>1986</year>
    <publisher>Nintendo</publisher>
    <info name="serial" value="NES-MA-EEC"/>
    <part name="cart" interface="nes_cart">
      <feature name="slot" value="nrom"/>
      <feature name="pcb" value="NES-NROM-128"/>
      <dataarea name="prg" size="32768">
        <rom name="pal-ma-0 prg" size="16384" crc="2aec46c2"
             sha1="f5d609720bc60bcb02f434d41149ae68e9f6b899" offset="0"/>
      </dataarea>
    </part>
  </software>
</softwarelist>

Key attributes and elements:

.hsi Files

Five files use an older <hashfile> format instead of <softwarelist>. These are simpler CRC32-keyed lookup tables with no part/dataarea structure, used for the Atari 5200 and a few other systems where only basic hash identification is needed:

<hashfile>
  <hash crc32="4019ecec" name="Astro Chase (Parker Brothers)">
    <year>1982</year>
    <manufacturer>Parker Brothers</manufacturer>
    <extrainfo>A13MIRRORING</extrainfo>
  </hash>
</hashfile>

Scale

The 759 XML files collectively document software for systems ranging from 1970s mainframes and microcomputers through to 2000s consoles, covering arcade conversions, productivity software, games, operating system disks, diagnostic ROMs, and prototype releases. Many entries include multiple regional variants and revisions as cloneof children of a parent entry.

Lua Plugin System (plugins/)

Lua plugins that extend MAME’s functionality at runtime. All code is BSD-3-Clause licensed unless noted per file.

How the plugin system works

When MAME starts, boot.lua is executed first. It reads the pluginspath option, sets up Lua’s package.path, then iterates manager.plugins and calls require(name) followed by plugin.startplugin() for every plugin with "start": "true" in its manifest. Plugins that are off by default must be enabled in plugin.ini or via -plugin <name> on the command line.

plugin.json Manifest

Every entry (plugin or library) declares itself with a JSON manifest validated against plugin.schema. The required fields are:

boot.lua - The plugin system entry point. Sets up internationalisation helpers (_(), N_()), builds package.path from pluginspath, then loads and starts all enabled plugins.

Plugins (type “plugin”)

The built-in plugins are listed below, including whether they start automatically and who maintains them.

Libraries (type “library”)

The shared plugin libraries are listed below.

data/ Plugin Internals

The data plugin is the most complex. It ships with sub-scripts for each data source:

Each sub-script exposes a check(setname) function that returns a heading if it supports that machine, and a get() function that returns the content. database.lua and load_dat.lua provide shared .dat file parsing utilities.

ROM Storage (roms/)

The default location MAME looks for ROM sets and hard disk images at runtime. The directory ships with a single file:

dir.txt - a plain-text placeholder (Place ROM directories here) whose only purpose is to ensure the empty directory is tracked by git, since git does not version-track empty directories.

No actual ROM files are included in the repository - distributing them would violate copyright.

How MAME resolves ROMs

When you run a machine, MAME searches every directory listed in rompath (default: roms) for a match. It accepts two layouts inside each path:

• ZIP archive - roms/<machinename>.zip containing the individual ROM chip dump files.
• Subdirectory - roms/<machinename>/ containing the same files unpacked.

CHD disk images (.chd) follow the same pattern but are typically stored in a subdirectory named after the machine: roms/<machinename>/<diskname>.chd.

Configuring additional paths

The rompath option accepts multiple semicolon-separated directories, so you can keep ROMs spread across different locations without moving them:

mame <machine> -rompath /path/to/roms;/another/romset

The option also has the aliases -rp, -biospath, and -bp for historical compatibility. The default value (roms) is relative to the directory MAME is launched from, so the repo’s roms/ folder is used automatically when running a development build from the repo root.

Parent/clone sets

Many arcade games share ROM chips with a parent set (e.g. regional variants or revisions). MAME searches rompath for both the clone’s ZIP and the parent’s ZIP, merging them as needed. You do not need to duplicate shared files.

Audio Samples (samples/)

Real-world audio recordings used by MAME to reproduce mechanical sounds for hardware that is impractical to emulate synthetically. Licensed under CC0-1.0 (public domain - recorded by team members and contributors from real hardware).

Like roms/, this directory ships with a dir.txt placeholder (Place samples directories here) so git tracks the otherwise-empty directory. No additional sample sets are bundled beyond floppy/.

Why samples exist

Some sounds - motor whirr, head seek clicks, mechanical latches - are produced by physical mechanisms rather than audio circuitry, making them impossible to reconstruct from the circuit simulation alone. Drivers that need them declare a list of required sample names; if the files are absent MAME mutes that sound channel silently rather than erroring out.

floppy/ - The only sample set shipped in the repo. Contains 22 WAV files (44100 Hz, mono) recorded from two real drives:

• 3.5” samples - recorded from a Sony MPF420-1 drive.
• 5.25” samples - recorded from a Chinon FZ502 drive.

The files are split into three categories:

The prefix 35_ denotes 3.5” and 525_ denotes 5.25”. Floppy sound is opt-in per driver - a driver must call enable_sound(true) on its floppy_sound_device; if the sample files are missing the device silently disables itself.

Configuring additional paths

Like rompath, the samplepath option (alias -sp) accepts semicolon-separated directories and defaults to samples relative to the MAME launch directory:

mame <machine> -samplepath /path/to/samples;/another/samples

Additional community sample packs (covering gun sounds, pinball solenoids, coin mechs, etc.) can be dropped into any directory on this path and MAME will find them automatically.

Main C++ Source Code (src/)

All MAME C++ source code, split across eight subdirectories.

src/emu/

The core emulation engine - the lowest-level layer that everything else builds on. Key areas:

Device System

device.cpp/h defines the base class for every piece of emulated hardware. All chips, boards, and peripherals inherit from it. The di*.cpp/h files are device interfaces - optional capability mixins a device can inherit to declare what it can do:

Memory Subsystem

emumem*.cpp/h - A heavily templated system for mapping address spaces. Split across many files for read/write handlers at 8/16/32/64-bit widths. Supports mirroring, banking, RAM/ROM overlays, and per-access-width handlers.

Scheduler

schedule.cpp - Co-operative timeslicing of all CPU cores and timed devices. Every device schedules callbacks at precise attotime timestamps (attosecond resolution).

Rendering

render.cpp, rendlay.cpp - The display composition engine. rendlay.cpp parses .LAY artwork layout XML files and composites game screens, bezels, and overlays into a final output image.

Input

ioport.cpp, input.cpp, inputdev.cpp - The I/O port system maps physical inputs (keyboard, joystick, mouse) through configurable bindings to emulated inputs (DIP switches, coin slots, joystick directions, buttons).

Audio

sound.cpp, speaker.cpp - Mixes all sound streams from all active sound devices into the final output buffer. speaker.cpp defines the speaker device that anchors streams to screen positions.

Save States

save.cpp - Serialises the complete machine state to a file by registering every stateful variable at startup.

ROM Loading

romload.cpp - Finds, loads, CRC-verifies, and maps ROM regions from the rompath into the address space.

Graphics

tilemap.cpp, drawgfx.cpp - Generic tile-map engine and sprite/tile pixel-drawing primitives used by hundreds of drivers.

Subdirectories

The main subdirectories under src/emu/ are listed below.

• debug/ - The integrated debugger: CPU stepping, breakpoints (dvbpoints), watchpoints (dvwpoints), expression evaluator (express), memory viewer (dvmemory), disassembly viewer (dvdisasm), register viewer (dvstate).
• ui/ - The in-game overlay UI (the interface you reach by pressing Tab): main menu, game selection, input mapping, options screens, audio effects, file manager, cheat options, system info, and more (~80 source files).
• video/ - Video support utilities: generic.cpp for common video patterns, resnet.cpp for resistor-network colour decoding, rgbutil.cpp for fast SIMD colour math.
• audio_effects/ - DSP audio effects pipeline: compressor, EQ, filters, reverb.
• layout/ - Built-in .lay artwork layout files compiled directly into the binary.
• drivers/ - Stub that #includes the full driver list.

src/devices/

Every piece of emulated hardware, each in its own file. Split into six subdirectories:

cpu/ (211 CPU families)

Every CPU core MAME emulates, one subdirectory per architecture. Includes: z80, m68000, arm/arm7, mips, x86, 6502, avr8, powerpc, sparc, sh, v60, tms9900, pdp1, and over 200 more. Each core implements the diexec and distate interfaces and optionally didisasm.

sound/ (371 chips)

Individual sound chip implementations: ay8910, ym2151, ym2612, pokey, sn76496, okim6242, c140, qsound, aica, and hundreds more - covering every era from 1970s beeper chips to 1990s wavetable synthesisers.

machine/ (~1,120 files)

Support logic chips: timers (6522via, 8253pit), UARTs (ins8250, z80scc), FDC controllers (wd1770, upd765), DMA (am9517a), interrupt controllers, memory mappers, custom ASICs, and miscellaneous glue logic.

video/ (330 files)

Dedicated video chips: PPUs, VDPs, sprite generators, palette chips, and line buffers. Examples: 315_5124 (Sega Master System VDP), ppu2c0x (NES PPU), tms9928a, mc6845 (CRTC), k052109 (Konami tile layer).

bus/ (184 expansion bus families)

Cartridge slots, expansion port connectors, and I/O buses. Each subdirectory models a specific bus standard and the cards/cartridges that plug into it: a2bus (Apple II), nes (NES cartridge), megadrive, snes, amiga, isa, pci, and many more.

imagedev/

Media image devices: floppy (with the floppy sound system), cassette, cartrom, harddriv, cdromimg, magtape, memcard, midiin/midiout, printer, snapquik (snapshot/quickload), picture, and others.

src/frontend/mame/

The MAME-specific application shell that sits on top of the engine. It owns the command-line interface, the Lua scripting engine, and the full game-selection UI.

Core Files

The main frontend files are listed below.

• mame.cpp/h - The top-level mame_machine_manager object; application entry point.
• clifront.cpp - Processes all command-line operations: -listxml, -verifyroms, -romident, -createconfig, etc.
• mameopts.cpp - Registers all MAME-specific command-line options on top of the base engine options.
• audit.cpp - ROM set auditing: scans rompath and reports missing, wrong-size, or bad-CRC files.
• cheat.cpp - The runtime cheat engine (separate from the cheat Lua plugin).
• infoxml.cpp - Generates the full -listxml machine database output.
• media_ident.cpp - Identifies unknown ROM files by CRC/SHA1 against the driver database.

Lua Engine

luaengine*.cpp - Embeds a Lua interpreter and exposes MAME internals as a Lua API, split across five files:

• luaengine.cpp - Core setup, plugin loading, emu.* table.
• luaengine_debug.cpp - Debugger bindings (breakpoints, watchpoints, expression evaluation).
• luaengine_input.cpp - Input port and device bindings.
• luaengine_mem.cpp - Memory space read/write bindings.
• luaengine_render.cpp - Render target and screen bindings.

ui/ (~80 source files)

The complete in-game UI: game/software selection browser (selgame, selsoft), main menu, input mapping, audio effects UI, options menus, file manager, floppy/tape/cartridge controls, state save/load, cheat options, plugin options, system info, barcode reader, and more.

Internal utility libraries (src/lib/)

Internal utility libraries used across the rest of the codebase.

Foundational utilities (src/lib/util/)

Foundational utilities with no dependency on the emulation engine. Includes: CHD read/write (chd.cpp), AVI I/O (aviio.cpp), PNG (png.cpp), FLAC (flac.cpp), XML parser (xmlfile.cpp), ZIP/7z decompression (unzip.cpp, un7z.cpp), Unicode handling (unicode.cpp), SHA1/MD5/CRC hashing (hashing.cpp, hash.cpp), palette management (palette.cpp), options parser (options.cpp), HTTP/WebSocket client and server (via asio headers), PLA/JEDEC file parsing (plaparse.cpp, jedparse.cpp), and many more.

Disk Image Format Parsers (src/lib/formats/) - 445 files

Parsers and writers for disk and tape media image formats. Each file handles a specific format used by imagedev/floppy and imagedev/cassette to translate image files into the internal track/sector model.

Infrastructure

Shared base code used by multiple format implementations - not formats themselves.

Filesystem Implementations

The table below lists the filesystem backends used by the format layer.

Audio File Formats

The table below lists the audio-backed image formats handled here.

Generic / Cross-Platform Disk Containers

The table below lists container formats that can hold media from many different systems.

Apple Family

The table below lists the Apple-family image formats.

Atari Family

The table below lists the Atari-family image formats.

Commodore Family

The table below lists the Commodore-family image formats.

Acorn / BBC Micro Family

The table below lists the Acorn and BBC Micro image formats.

Sinclair / ZX Spectrum Family

The table below lists the Sinclair and ZX Spectrum image formats.

TRS-80 / CoCo / Dragon Family

The table below lists the TRS-80, CoCo, and Dragon image formats.

Japanese Computers

The table below lists the Japanese computer image formats.

Soviet / Eastern European Computers

The table below lists the Soviet and Eastern European computer image formats.

DEC and HP Systems

The table below lists the DEC and HP image formats.

Luxor ABC (Swedish)

The table below lists the Luxor ABC image formats.

Thomson (French)

The table below lists the Thomson image formats.

Oric

The table below lists the Oric image formats.

Ensoniq / Music Synthesizers

The table below lists the Ensoniq and other synthesizer image formats.

Other Home Computers

The table below lists the remaining home-computer image formats.

Analog Circuit Simulator (src/lib/netlist/)

A full analog circuit simulator. Parses netlist descriptions of discrete circuits (resistors, capacitors, transistors, logic gates) and solves them in real time using numerical integration. Used to accurately emulate the discrete audio circuits found in early arcade games (e.g. Pong, Gun Fight) rather than substituting recorded samples.

OSD - OS-Dependent layer (src/osd/)

The OSD layer contains all platform-specific code. The rest of MAME calls abstract interfaces defined here; the platform backends implement them.

interface/

Abstract C++ interfaces (inputman.h, audio.h, midiport.h, uievents.h, etc.) that each platform backend must implement.

modules/

Platform-agnostic module implementations shared across backends, covering: debugger integration, file I/O, font rendering, input handling, MIDI, network devices, OpenGL, audio output, render pipeline, and window management.

Platform Backends

The platform backends are listed below.

src/tools/

Standalone command-line utilities that use MAME’s internal libraries but are built as separate binaries.

src/mame/

Driver source code, organised into 359 manufacturer subdirectories. Each subdirectory contains the .cpp and .h files that define the machine configurations, memory maps, I/O port bindings, and video/audio wiring for every system that manufacturer made. Examples: apple/, atari/, capcom/, nintendo/, sega/, snk/, taito/, konami/.

Each driver calls GAME(...) or CONS(...) or COMP(...) macros to register itself in the global driver list, declaring the machine name, parent, year, manufacturer, and the function that builds its machine_config.

ZEXALL - Z80 instruction set exerciser (src/zexall/)

A minimal self-contained MAME build target whose only purpose is to run ZEXALL - the Z80 instruction set exerciser originally written by Frank D. Cringle in 1994, adapted for MAME’s Z80 core by Kevin Horton. It is the definitive regression test for MAME’s Z80 CPU implementation.

Files

The ZEXALL target is split across the files below.

How It Works

Each test group exercises one instruction or a family of related instructions by systematically cycling through a large set of machine states. For each state:

• Registers - The registers (IY, IX, HL, DE, BC, AF, SP) and a 2-byte memory operand are set to specific values.
• Instruction - The instruction under test executes.
• CRC update - The resulting machine state is fed into a running 32-bit CRC.

At the end of a test group the computed CRC is compared against an expected value measured empirically on real Z80 hardware. A mismatch means MAME’s Z80 core produces different results to the silicon.

The test space is controlled by two vectors per instruction:

• Increment vector - bits set here are cycled as a binary counter (e.g. if the accumulator byte is 0xFF, all 256 accumulator values are tested).
• Shift vector - bits set here are inverted one at a time across separate test runs.

The total test case count is the product of 2^(increment bits) × (shift bits). Some groups run millions of combinations; others only dozens.

The output mechanism

The original ZEXALL was designed for CP/M, which uses BDOS calls (CALL 5) to print strings. Kevin Horton’s interface stub intercepts these calls and redirects them to three memory-mapped ports at the top of the 64 KB address space:

zexall.cpp polls these ports each emulated cycle and prints each received character to the console via osd_printf_info. The driver watches for the string "Tests complete" and calls machine().schedule_exit() to terminate cleanly.

Running It

Because main.cpp builds a standalone MAME binary containing only the zexall driver (no other machines, no UI), it runs as:

./zexall

Output is printed directly to the terminal. A passing run ends with Tests complete. Any line containing ERROR indicates a CRC mismatch on a specific instruction group - meaning MAME’s Z80 core produced a different flag or register result than real hardware.

Why It Matters

The Z80 has many edge cases - undefined flag behaviour, the R register increments, block instruction flag interactions, undocumented IXH/IXL half-registers - that are easy to get subtly wrong. ZEXALL catches all of these by running on real silicon first and recording the expected CRCs. Any Z80 core change that alters observed behaviour will cause a ZEXALL failure, making it an unambiguous correctness gate.

Testing and Performance

Unit Tests (tests/)

Unit tests for the emulation core and libraries, using the Catch2 framework. Mirrors the src/emu/ and src/lib/ structure.

Regression Tests (regtests/)

Regression test suite. Contains test definitions for chdman (CHD file tool) and jedutil (JEDEC file tool), along with a regtests.mak makefile to run them.

Performance Benchmarks (benchmarks/)

Micro-benchmarks for testing performance of core MAME components. Contains standalone C++ benchmark programs.

Configuration

Controller Configurations (ctrlr/)

Controller configuration files (.cfg) that remap MAME’s input system for specific third-party arcade control panels. Loaded at runtime with the -ctrlr <name> flag (omit the .cfg extension).

Files Included

The controller configuration files shipped with the repo are listed below.

File format

Each file is XML with a <mameconfig version="10"> root element containing one or more <system> blocks:

• <system name="default"> - applies to every machine.
• <system name="neogeo"> (or any other driver name) - overrides the default for that specific machine only. xarcade.cfg and slikstik.cfg both use this to remap buttons to match the Neo Geo’s A/B/C/D layout, and slikstik.cfg additionally has per-game overrides for asteroid, missile, and tempest.

Inside each <system> block there are two types of entry:

Low-level scancode remaps

Redirect one raw key to another before any port binding is evaluated:

<remap origcode="KEYCODE_UP" newcode="KEYCODE_8PAD" />

All five panels use this to route the arrow keys through the numpad (which is how their joysticks report to the OS).

Port bindings

Assign one or more inputs to a named MAME input port:

<port type="P1_BUTTON1">
    <newseq type="standard">KEYCODE_LCONTROL OR JOYCODE_1_BUTTON1 OR MOUSECODE_1_BUTTON1</newseq>
</port>

Input sequence syntax:

• OR - any of the listed inputs triggers the action.
• Space-separated codes - a chord; all must be held simultaneously (used for menu combos like coin+start).
• NONE - explicitly disables an input that would otherwise be inherited.

Input source prefixes: KEYCODE_* (keyboard), JOYCODE_<player>_* (joystick/gamepad), MOUSECODE_<player>_* (mouse buttons).

Usage

To load one of these controller profiles, pass its base name to the -ctrlr flag:

mame <machine> -ctrlr xarcade

Configuration Presets (ini/)

Ready-to-use INI snippet files for MAME’s Direct3D post-processing pipeline. All files use the standard MAME INI format: one key value pair per line, # for comments. They are not loaded automatically - you copy the settings you want into your own mame.ini or a per-machine INI file.

The directory is split into two subdirectories by purpose presets and examples.

presets/

Complete post-processing configurations for a specific display technology. Drop the contents of one of these into your INI to get an appropriate visual style for a whole category of hardware.

examples/

Single-purpose colour space snippets. Each file sets only the chroma_* parameters that control how MAME maps the emulated system’s native colour space to your monitor. Intended to be mixed into a preset rather than used standalone.

Phosphor Colour Examples

The phosphor presets below cover common CRT and display technologies.

Broadcast Colour Space Examples

The broadcast colour-space presets below map common video standards to their intended use.

Keyboard Layout Remaps (keymaps/)

Keyboard mapping files (.map) that remap non-QWERTY host keyboards so that MAME’s input system receives the correct key identifiers. Licensed under CC0-1.0 (public domain).

Why they exist

MAME’s internal key identifiers (ITEM_ID_Q, ITEM_ID_A, etc.) are defined relative to a standard US QWERTY layout. On a French AZERTY keyboard the physical key in the QWERTY-Q position produces A, so without a keymap MAME would interpret it incorrectly. Keymap files describe only the keys that differ from QWERTY - anything not listed passes through unchanged.

File naming

Each file follows the pattern km_<locale>_<OS>.map:

File format

Each file is an INI-style text file with a [SDL2] section header (all keymaps target the SDL2 backend). Each non-comment line has three columns:

ITEM_ID_<key>    SDL_SCANCODE_<scancode>    <display_char>

• Column 1 - MAME’s internal key identifier, named after the QWERTY key in that physical position (e.g. ITEM_ID_Q).
• Column 2 - The SDL2 scancode that the host OS reports for that physical key (e.g. SDL_SCANCODE_A on a French keyboard where the QWERTY-Q physical position sends A).
• Column 3 - The visible character, included as a human-readable label only.

Example - the Y↔Z swap on a German QWERTZ keyboard:

ITEM_ID_Y    SDL_SCANCODE_Z    Y
ITEM_ID_Z    SDL_SCANCODE_Y    Z

Known issues

Several files (km_fr_LINUX.map, km_fr_OSX.map) contain a FIXME comment noting that they produce parse errors and need updating.

UI Translations (language/)

Translation files for MAME’s UI strings. Each subdirectory is a locale (e.g. Chinese_Simplified, French, German) containing the translated string catalogue.

Misc

Web Server Interface (web/)

Assets for MAME’s built-in web server interface. Licensed under BSD-3-Clause. Contains two distinct pieces:

layout.xsl

An XSLT stylesheet that transforms MAME’s .LAY XML layout files into live, interactive HTML pages served by MAME’s built-in HTTP server. The transformation:

• Converts .LAY elements (rect, text, disk, led7seg) into equivalent SVG shapes, positioned and coloured to match the original layout.
• Injects JavaScript that opens a WebSocket connection back to MAME (ws://localhost:8080/socket).
• Sends button press/release events to MAME over WebSocket when the user clicks SVG elements.
• Receives display-state updates from MAME (e.g. which segments of a 7-segment LED are lit) and updates the SVG in real time.

esqpanel/vfx/

A hand-crafted browser front panel for the Ensoniq VFX family of synthesiser keyboards. Consists of:

• FrontPanel.html - The page shell. On load it opens a WebSocket to MAME and instantiates the panel object from FrontPanel.js, showing a “Waiting to connect…” message on the display until the connection is established.
• FrontPanel.js - A self-contained JavaScript module (fp) that models the physical controls of the VFX, VFX-SD, SD-1, and SD-1/32 keyboards. It renders buttons, indicator lights (off / on / blinking), rotary knobs, and multi-character segment displays as DOM elements. User interactions are sent to MAME over the same WebSocket, and incoming messages update the display and light states accordingly.

Running the Web Server

The HTTP server is off by default. Three command-line flags control it:

Basic usage - start MAME with the server enabled:

mame <machine> -http

Then open http://localhost:8080 in a browser. MAME serves everything under web/ as static files, so layout.xsl and esqpanel/ are immediately accessible.

Custom port and root:

mame apple2 -http -http_port 6502 -http_root /path/to/custom/web

The WebSocket endpoint used by both layout.xsl and the Ensoniq front panel is always at ws://<host>:<port>/socket.

Archived Research Files (attic/)

Archived source files that are no longer part of the active build but are kept as historical documentation and research references. Every file here is either a standalone tool that was superseded, a stub/skeleton left over from in-progress work, or extended notes on reverse-engineered hardware protection. The directory contains seven files:

fd1094dp.cpp - A standalone C++ program (not compiled into MAME) by Charles MacDonald and Nicola Salmoria. It reads 128 MB of raw data extracted from a physical FD1094 encrypted Sega CPU and produces the 8 KB keyfile that MAME’s fd1094.cpp driver uses to decrypt ROM data. Superseded once the key derivation was fully understood and built into the main emulator.

fddebug.cpp / fddebug.h - A retired debugging module by Aaron Giles for interactively cracking FD1094 encryption keys at runtime. The bulk of the implementation is wrapped in #if 0 and compiled out; only a hollow stub of fd1094_init_debugging() remains. The commented-out body contains extensive notes on known M68000 instruction sequences found in Sega System 16B games, which were used as known-plaintext anchors when brute-forcing unknown keys.

jalmah.x68 - Motorola 68000 assembly source (.x68 format, assembled with the Human68k cross-assembler) by Angelo Salese. Contains simulation snippets for the MCU protection routines in Jaleco mahjong arcade games, written while reverse-engineering the hardware.

jrcrypt.cpp - A GPL-licensed standalone C++ program by David Caldwell (1997) documenting the XOR/lookup-table encryption scheme used by Jr. Pac-Man ROMs. Self-described as a documentation artifact; the actual decryption is handled inside the live MAME driver.

opwolf_cchip.txt - A detailed plain-text research document describing the Taito TC0030CMD “C-Chip” copy-protection microcontroller used in Operation Wolf. Records the original software simulation that MAME used before an actual EPROM dump of the chip became available, explains the chip’s co-operative threading model (32 thread slots, one per enemy), and catalogues the differences between the original and bootleg versions of the game. Kept purely as documentation now that real C-Chip emulation has replaced the simulation.

unkfr.cpp - A driver skeleton by David Haywood acting as a holding area for unidentified fruit machine ROMs that have not yet been matched to a known platform. Most of the driver body is wrapped in #if 0. The file’s own comment instructs contributors to remove confirmed-bad ROMs and migrate anything positively identified to the correct driver.

Third-Party Libraries (3rdparty/)

Third-party libraries vendored into the repo. Includes cryptography (aes256cbc), networking (asio), JIT compilation (AsmJIT), rendering (BGFX, bimg, bx), compression (flac), XML parsing (expat), image decoding (libjpeg), Lua scripting (lua), SQLite (lsqlite3), benchmarking (benchmark), testing (Catch2), and the Genie build system used to generate project files.

Building

Build System Scripts (scripts/)

Build system scripts. Contains Lua scripts for Genie (genie.lua, toolchain.lua, extlib.lua), subdirectories for per-target and per-source build rules (src/, target/), font generation (font/), XSLT transforms (xslt/), a ROM management utility (minimaws/), and build resource files (resources/).

Android Build Project (android-project/)

Gradle project files for building MAME as an Android application. Contains the standard Android project structure (app/, build.gradle, gradle.properties, etc.).

Build System Project Metadata (projects/)

A working area for external MAME-based projects. The directory ships with only a README.md and a .gitignore that ignores everything except those two files - any project you clone here is intentionally untracked by the main repo.

How It Works

When you run make PROJECT=<name>, the build system sets TARGET to the project name and appends the project’s own Genie Lua build script to the build:

projects/<name>/scripts/target/<name>/<subtarget>.lua

So a project cloned as projects/foo/ must provide that script path to be buildable.

What You’d Put Here

Typical projects that belong here are listed below.

• A custom operator build targeting only specific hardware (e.g. a stripped binary containing only CPS2 or Neo Geo drivers)
• A platform-specific distribution - this is how older standalone MESS builds worked before MESS merged into MAME
• A third-party fork that adds proprietary drivers, a custom UI, or different default options, built on top of MAME’s core without modifying the main tree

Build Output (build/)

Output directory created during compilation. Contains generated build system files (generated/), compiled object files and binaries, and IDE project files (projects/). Not tracked by git.