Automated toolset for compiling MAME to WebAssembly with high stability and optimization. While optimized for AmpleWeb, this repository serves as a general-purpose build factory for any MAME-to-WASM needs.
.
├── 🛠️ Build Scripts
│ ├── setup.ps1 ← Initialization (Run first)
│ ├── build.ps1 ← Main build script (Windows)
│ └── build-linux.ps1 ← Main build script (Linux)
│
├── 🎯 Custom Targets
│ └── custom_targets/ ← LUA/LST definitions (supracan, ample)
│
├── 🌐 Web & Testing
│ ├── test_mamewasm.html ← Advanced multi-ROM loader
│ ├── test_emularity.html ← Emularity test page (Robby Roto)
│ └── server.py ← Local test server
│
├── 📦 Core Components
│ ├── mame/ ← MAME source tree
│ ├── emsdk/ ← Emscripten SDK
│ └── bin/ ← Build tools & native MAME
│
└── 💾 ROMs & Data
├── roms/ ← Your ROM files
└── analyze_roms_v3.py ← Dependency analyzer
# Run as Administrator
PowerShell -ExecutionPolicy Bypass -File ./setup.ps1
# Start Building
PowerShell -ExecutionPolicy Bypass -File ./build.ps1- setup.ps1: Installs EMSDK, build tools (Ninja/Make), and clones MAME source.
- build.ps1: Interactive UI to choose TARGET, SUBTARGET, and Optimization mode.
- Test: Run
python server.pyand opentest_mamewasm.html.
When building via build.ps1, you can choose Production mode, which enables:
- Extreme Optimization (-Oz): Aggressive size reduction.
- LTO (Link-Time Optimization): Cross-module optimization for better performance.
- Memory Stability: Sets
INITIAL_MEMORYto 1GB andMAXIMUM_MEMORYto 4GB. - No Exceptions: Further reduces size and improves speed for release builds.
This repository includes a highly advanced and custom memory access mechanism designed to allow external JavaScript files to query the emulator's memory space directly, completely bypassing unstable heap scanning heuristics.
The build automatically exports two custom C++ functions from MAME's running_machine structure into WebAssembly/JavaScript:
-
Single Byte Read:
uint8_t emscripten_read_ram(uint32_t addr)JS Call:Module._ZN15running_machine19emscripten_read_ramEj(addr)Description: Directly queries the:maincpuaddress space program memory for the given address. -
Bulk Buffer Read:
uint32_t emscripten_read_ram_bulk(uint32_t start_addr, uint32_t length, uint8_t *out_buf)JS Call:Module._ZN15running_machine24emscripten_read_ram_bulkEjjPh(start_addr, length, ptr)Description: Contiguously reads a memory block from the 6502 CPU space into an allocated WebAssembly pointer (ptr), enabling high-performance block memory reading (e.g. text screens).
To avoid file locking and linker issues on Windows, use the containerized environment:
# Start build via Docker Compose
docker-compose run mame-build mame-build TARGET=mame SUBTARGET=ampleThis ensures a stable Linux-based build environment for the best results.
If you prefer not to use Docker, you can build directly on Linux/WSL.
sudo apt update && sudo apt install -y build-essential git python3- Setup EMSDK:
git clone https://github.com/emscripten-core/emsdk.git - Activate:
cd emsdk && ./emsdk install latest && ./emsdk activate latest && source ./emsdk_env.sh - Build:
PowerShell -File ./build-linux.ps1(or use manualemmake make)
| SUBTARGET | Description | Size | Recommended Mode |
|---|---|---|---|
tiny ⭐ |
Recommended for testing | 30-50MB | Debug (Fast) |
ample 🚀 |
Optimized for AmpleWeb | 45-60MB | Production (Oz + LTO) |
supracan |
Super A'Can custom target | ~40MB | Production |
mame |
Full version (40k drivers) | ~210MB | Docker (Recommended) |
You can use the -Sources parameter to build specific machines:
- Apple IIe:
PowerShell -File ./build.ps1 -Subtarget tiny -Sources apple2e - Pac-Man:
PowerShell -File ./build.ps1 -Subtarget tiny -Sources pacman - Arcade Multi-pack (Multiple drivers):
PowerShell -File ./build.ps1 -Subtarget tiny -Sources pacman,robby,dkong - Custom Target (Super A'Can):
PowerShell -File ./build.ps1 -Subtarget supracan -Optimization Production(Note: Production mode enables Oz and LTO for the smallest and fastest WASM binary.)
This project includes a premium, local-friendly test page for rapid verification of your WASM builds.
- WASM JS: The filename of your build output (e.g.,
mamesupracan.jsormametiny.js). - Driver: The MAME machine name (e.g.,
supracanorapple2e). - Extra Args: Additional MAME CLI arguments.
- Example: Use
-cart /roms/game.zipto mount a cartridge.
- Example: Use
- ROM File Selection: Click to select all required ZIP files.
- Configure: Enter the WASM JS and Driver name first.
- Add Args: If mounting a cartridge, enter the path in Extra Args (must start with
/roms/). - Select Files: Click "Select Files" and select ALL required ZIPs simultaneously (e.g.,
supracan.zip+umc6650.zip+game.zip). - Run: Click Load & Run. The page remembers your settings and reloads to start MAME.
- Reset: If you get stuck, click the red Clear Settings button to reset the UI.
MAME's architecture is complex. For machines requiring specific cores (like supracan), a simple -Sources flag might not suffice.
- You can create a
.lstand a.luadefinition incustom_targets/. - AI-Powered Workflow: Ask an AI (Claude/Antigravity) to "Write a MAME Genie LUA definition for target X" and place it in
custom_targets.
- Subsequent builds take only 1-5 minutes as long as you don't switch SUBTARGET.
- If you modify
custom_targets/*.lst, we recommend runningbuild.ps1again.
- Fix: The machine needs more memory. Rebuild using
build.ps1which sets memory to 1GB.
- Fix: Conflict between MAME and Emscripten. Rename
PAGE_SIZEincmi.cppormsxdos2.cpp.
- Fix: The script auto-patches
dasm.ninja. If it persists, try deleting thebuild/directory and restarting.
- Independence: 100% self-contained toolchain. No external dependencies required.
- Path Limits: Folder paths MUST NOT contain Chinese characters or spaces.
- RAM Requirements: At least 16GB RAM is recommended for full
mametarget builds.
Last Updated: 2026-08-02 Version: 0.289