# metal-slug-3-recomp ## A word from the author Hey everyone, real human here! Keep in mind that this was vibe coded, so it may have some errors. This started as a personal project just to play MSX on my PS Vita, lol (which is still on my to-do list), but I figured it could be a step forward for Metal Slug ports. I have no prior coding experience, nor do I intend to learn, so feel free to use this however you like. I asked Claude to add some things I wanted that I think could be useful. If you find any bugs, please report them and I'll ask Claude to fix them c: Enjoy! --- A native Windows port of **Metal Slug 3** (Neo Geo MVS, 2000), built by statically recompiling the game's 68000 program to C and reimplementing the Neo Geo hardware around it. It follows the method of [metal-slug-x-recomp](https://github.com/AlmazProud/metal-slug-x-recomp), whose runtime and frontend it shares. **Bring your own copy.** This repository and its releases contain no part of the game: no code, graphics, sound or BIOS. The port reads them at run time from a copy you own. > Metal Slug 3 is © SNK CORPORATION. This is an unofficial fan project, not affiliated with or > endorsed by SNK. Please buy the game. ## Quick start 1. Download the latest zip from [Releases](https://github.com/AlmazProud/metal-slug-3-recomp/releases) and unzip it anywhere. 2. Have a copy of the game. Any of these works: | Copy | What the port needs | |---|---| | **GOG** or **Steam** (the PC release) | Nothing: if it is installed, the port finds it on its own. Or copy its install folder into `game\`. | | **Arcade board dump** (MAME set) | `mslug3.zip` and `neogeo.zip` (or their files) in `game\` | 3. Run `mslug3.exe`. If it cannot find the game, drop the game's folder or zip on the window, or press ENTER to choose a folder. It remembers the choice. The game files are recognized by their hashes, not by their names. - **The GOG release** is the verified one. It holds the arcade `mslug3` set, byte for byte. - **Steam's PC release** uses the same layout; the search was checked with a simulated install, but no Steam copy was available. - **The arcade dump** (MAME's `mslug3`, the NEO-SMA "green" board) is encrypted; the port decrypts it on load (about a second) to the same bytes as the GOG files. ## Features - **Arcade-exact game:** the same game logic as the original board, verified frame by frame against MAME (see *How it was verified*). - **Modern frontend** with remastered menus in English and Spanish, usable with keyboard, gamepad or mouse: - start screen with **Continue** (the game is autosaved every minute and on quit); - pause menu; - 9 save-state slots; - settings for video, audio, game, controls and system. - **Game modes:** - **Arcade:** a whole game with the original rules, 0, 1, 3, 5 or infinite continues, and a results page; - **Mission:** start at any mission you have reached; - **Boss Rush:** the seven main bosses in a row with one credit (unlocked by finishing the game in Arcade or Mission mode). - **Records:** best time and score per mission, Arcade's best score, Boss Rush's best time. - **Boss health bar** (optional) with the boss's name. - **Video:** - 4:3 or square pixels, integer scaling up to 8K; - sharp, smooth or raw pixel filters; - scanlines and fullscreen; - a CRT effect (arcade monitor, TV or soft): scanlines, phosphor mask, glow and an optional curved screen; - V-sync that keeps audio in step on 60 Hz and high-refresh monitors. - **Controls:** - keyboard and gamepad for two players, remappable; - autofire per player; - gamepad rumble driven by the game's sound effects. - **Run-ahead** (optional, off by default): the game's reaction to a button is shown a frame sooner by emulating ahead, without changing the game. - **Quality of life:** fast boot (skips the BIOS screen), fast forward, pause when the window is not active, PNG screenshots. - **Slowdown:** optional removal of the original slowdown (68000 at 2x or 4x speed). - **Red blood:** the game's own hidden BLOOD option. - **Music and sounds menu:** every track, effect and voice of the game, with names and per-sound rumble. - **The developers' own debug tools:** the hidden developer menu (stage select, debug switches such as invincibility and hit boxes). - **Cheats:** start mission, weapons, bombs, lives, soldier, forms (fat, mummy, zombie...), spawning vehicles. - **Debug panel (F3):** FPS, game logic rate, 68000 load, sprite and palette viewers. ## Controls | Neo Geo | Player 1 keyboard | Player 2 keyboard | Gamepad | |---|---|---|---| | Joystick | Arrow keys | I J K L | D-pad | | A (shoot) | Z | A | X / Square | | B (jump) | X | S | A / Cross | | C (grenade) | C | D | B / Circle | | D | V | F | Y / Triangle | | Start | 1 | 2 | Start | | Coin | 5 | 6 | Back / Select | | Autofire | B | G | RB / R1 | | Key | Action | |---|---| | Esc (gamepad: Guide, or Back + Start) | Menu | | F5 / F9 | Save / load state | | F7 / F8 | Previous / next save slot | | P | Pause | | Tab (gamepad: right trigger) | Fast forward (held) | | F11 or Alt+Enter | Fullscreen | | F12 (gamepad: Share) | Screenshot | | F2 | Board test button (service menu: difficulty, lives...) | | F3 | Debug panel | | F4 | Developers' menu (with developer mode on, during a mission) | Every control and shortcut can be changed in **Settings > Keyboard** and **Settings > Gamepad**: a list with each action's key or button and a picture of the keyboard or gamepad showing what each one does. Select a row and press the new key or button; one already in use swaps places. The triggers and the sticks' directions count as buttons (arcade sticks whose lever is a stick work too). Each player picks which gamepad they use, its type (Xbox, PlayStation, Nintendo or arcade stick, for the names and the picture) and one of four gamepad profiles; a profile chosen with a gamepad connected loads by itself when that gamepad connects again. Back + Start always opens the menu. Settings, saves, records and screenshots are kept in `%APPDATA%\ProjectoDecompile\mslug3\`. If you create a folder named `save` next to the executable, they are kept there instead, so the port is portable (for example on a USB drive). ## How it works 1. **Analysis.** The game's 68000 program was mapped with a recursive disassembler and with execution traces from MAME, including the NEO-SMA protection chip's banked program. 2. **Recompilation.** Every instruction is translated to C. The translation keeps the 68000's exact cycle counts and interrupt timing. 3. **Runtime.** The Neo Geo hardware is a native runtime written for this project: - memory map and the cartridge's NEO-SMA chip (program banking); - the LSPC video chip (sprites, fix layer, line timing and interrupts); - the real-time clock and the watchdog; - the Z80 sound CPU and the YM2610 sound chip. 4. **Loader.** The GOG / Steam files are read as they are; MAME's encrypted set is decrypted with a compact description of the NEO-SMA and CMC42 schemes, learned from MAME as a black box with synthetic patterns (no MAME code was read or copied). The released executable cannot contain the recompiled C code, because that code is derived from the game. It runs the game's 68000 program through a cycle-exact interpreter instead, at about 7 times real time on a modern PC. If you build from source with your own copy, you also get the recompiled program, which is used when your copy matches the one it was generated from. ## How it was verified MAME 0.289 was used as the reference, never as a source of code. - **The comparison:** the port and MAME run the same inputs from the same state. Every frame's image, the RAM and palette at every vertical blank, and the audio sample by sample must be identical. - **Runs:** power-on and attract demo (10,007 frames); a game with a bot (9,001 frames); a 16.8-minute game recorded by hand (Missions 1 and 2 and the start of 3); scripted runs of Missions 2 to 5; every boss section reached through the developers' stage select. All of these are identical in image and audio, both with the recompiled program and with the interpreter alone. In RAM, a few vertical blanks differ only in the stack, where MAME takes the interrupt one instruction apart; each one is listed and checked byte by byte. **Known difference:** in the final boss's fight (Rootmars), which uses the raster interrupt about 130 times a frame, MAME sees about 0.5 % of those interrupts a couple of cycles earlier or later than the port. The game's time-sliced work then ends one step apart: RAM differs from that point and 18 of 8,996 images in that run. It does not change how the game plays; it comes from how MAME schedules its CPUs. Details in `docs/BOSS_RUSH.md`. ## Building from source (Windows) 1. Clone the repository into a folder, for example `C:\Projecto Decompile\MS3_Port\repo`. 2. Run `repo\setup\INSTALL.bat`. It downloads every tool into `tools\` from its official source, checks its hash, and needs no administrator rights. The tools are CMake, Ninja, llvm-mingw, SDL3, Python, MAME and Ghidra. MAME and Ghidra are only needed for the analysis and verification tools. 3. Activate the environment in PowerShell (`. .\env.ps1`) and build: ``` cmake -S repo -B repo\build-dist -G Ninja -DCMAKE_BUILD_TYPE=Release -DPD_RECOMPILED=OFF cmake --build repo\build-dist ``` That is the distributable build: it needs no game files. A personal build with the recompiled program needs your copy in `roms\` (`INSTALL.bat` offers to copy it from GOG) and the analysis listings. `CLAUDE.md` and the `docs/` folder describe every phase of the project. The same sources also build `mslugx.exe`, Metal Slug X, as a regression target for the shared runtime; it is not part of the releases. ## Repository layout | Path | Contents | |---|---| | `src/cpu` | dispatcher, interpreter glue, cycle tables | | `src/neogeo` | hardware runtime and the copy loader | | `src/games` | one folder per game: ROM catalog, decryption, game profile, sound names | | `src/port` | the SDL3 frontend | | `tools/` | analysis, recompiler (`recomp68k/`), MAME scripts and comparison tools | | `tests/` | differential, lockstep and loader tests | | `external/` | Musashi, ymfm, the Z80 core, stb_truetype and the menu fonts (`THIRD_PARTY.md`) | | `docs/` | per-phase documentation | ## License The port's code is MIT licensed (`LICENSE`). Third-party code keeps its own license (`THIRD_PARTY.md`): Musashi (MIT), ymfm (BSD-3-Clause), floooh/chips z80.h (zlib), stb_truetype (MIT / public domain), SDL3 (zlib), and the fonts Black Ops One and Chakra Petch (SIL Open Font License 1.1).