NeoGeo ROM Extractor

A modular, preservation-focused Python extractor for rebuilding verified Neo Geo ROM ZIPs from supported legally owned PC releases.

This project is designed to help users extract ROM data from game releases they already own, then rebuild emulator-ready Neo Geo ROM ZIPs using per-game extraction modules.

This repository is distributed as source code. The extractor is written in Python, with readable JSON data/configuration where required. No compiled binaries are required to inspect, modify, or run the main project.

The extractor is cross-platform and can be run on Windows, macOS, and Linux using Python 3.10 or newer.

Project Status

This project is in active development.

Supported games are added through individual game modules in project_files/game_modules/. Each module defines the source layout, expected file slices, output names, hashes, and any game-specific extraction behaviour required for that title.

Currently Supported Games

The following games are supported (30 in total so far):

• 3 Count Bout
• Alpha Mission II
• Art of Fighting 3
• Crossed Swords
• Ghost Pilots
• King of the Monsters 2
• Kizuna Encounter - Super Tag Battle
• Last Resort
• Magician Lord
• Metal Slug
• Metal Slug 2
• Metal Slug 3 (Now Available thanks to terminatorhex direct contribution, thnxs 😊)
• Metal Slug 4 (see Caution)
• Metal Slug X
• Mutation Nation
• Ninja Commando
• Ninja Master's
• Over Top
• Robo Army
• Samurai Shodown IV
• Sengoku
• Sengoku 2
• Soccer Brawl
• Super Sidekicks
• The King of Fighters 2003 (see Caution)
• The Last Blade
• The Last Blade 2
• The Super Spy
• Top Hunter
• Twinkle Star Sprites

Some listed titles are marked as work in progress or caution where support is incomplete, unusual, or not fully parent-set compatible.

Caution

Metal Slug 4 and The King of Fighters 2003 are not full parent-set extractions. They are rebuilt using a mixture of parent files and clone or set-specific files.

They should work in MAME and FBNeo, possibly with some emulator or ROM-set settings adjusted, but they are best left in the ZIP files produced by this extractor.

Be careful when processing them through a ROM manager such as RomVault. A ROM manager may try to delete, rename, move, rebuild, or merge them into a different set structure.

Features

• Modular per-game extraction system
• General-purpose extraction core
• Game-specific logic kept inside game modules
• Easy-to-use interactive terminal menu for normal use
• Recursive source-folder detection for supported game releases
• Source-file processing using module-defined operations
• Existing source ZIP collection from top-level game folders where neogeo.zip is detected
• Hash-based file verification
• Output ZIP creation for supported Neo Geo titles
• Designed for preservation and personal-use extraction workflows
• No ROMs, BIOS files, or copyrighted game assets included

Supported Sources

This extractor is intended for supported PC releases of Neo Geo games, such as legally purchased storefront releases where the required source data is available locally.

Support varies per game. Each supported title requires a matching game module.

Source Detection and Existing ZIP Collection

When run, the extractor scans the nearby supported game folders for recognised releases.

Game detection is controlled by each game module. A module can define expected folder names, source subfolders, required source files, and minimum source-file sizes.

Once a supported game source is detected, the extractor builds the required ROM files from the detected source files using the operations declared in that game module. Depending on the game, this may include slicing source files, joining slices, choosing slices conditionally, searching for a slice by CRC32, applying byte patches, re-encoding DotEmu SFIX or tile data, decoding Neo Geo 4bpp tile data, assembling chunks, or running a custom converter.

The normal extraction process creates new output ZIPs from the processed and verified files. These generated ZIPs are written to the extracted_neogeo/ folder.

The extractor also has an existing ZIP collection feature. During batch extraction, or when using --collect-existing-zips, it scans the top-level game folders. If a neogeo.zip file is found anywhere under a top-level folder, the extractor copies all .zip files from that folder into the matching extracted_neogeo/ output folder.

Copied existing ZIPs are source or vendor ZIPs. They are not generated by the extractor and are not validated as rebuilt emulator output. This feature is intended to preserve existing ZIP files found alongside the supported game data, not to verify or rebuild them.

This feature is local-only. It does not verify ownership, legality, or redistribution rights for copied ZIP files. Users should not upload, commit, share, or redistribute copied ZIP files unless they have the legal right to do so.

Project Structure

Example folder layout:

Amazon Games/
├── 3 Count Bout/
├── Metal Slug 4/
├── The King of Fighters 2003/
├── other supported game folders...
└── NeoGeo ROM Extractor/
    ├── neogeo_extractor.py
    ├── project_files/
    │   ├── game_modules/
    │   │   ├── __init__.py
    │   │   ├── alpha_mission_ii.py
    │   │   ├── art_of_fighting_3.py
    │   │   ├── crossed_swords.py
    │   │   └── ...
    │   ├── bios/
    │   │   ├── __init__.py
    │   │   └── neogeo_bios.py
    │   └── neogeo/
    │       ├── __init__.py
    │       ├── cmc.py
    │       ├── pcm2.py
    │       └── pvc.py
    ├── README.md
    └── LICENSE

The top-level folder does not need to be named Amazon Games. It could also be a Steam, GOG, or custom game folder. The important part is that the NeoGeo ROM Extractor folder sits alongside the supported game folders.

The extractor may create working/output folders such as temp/, extracted_neogeo/, backups/, failed/, and batch_logs/ when it runs. These are generated locally and are not part of the source release.

Requirements

• Python 3.10 or newer recommended
• A legally obtained supported game release
• Local access to the required source files for that game

Installing Python

Python 3.10 or newer is recommended for this project.

Check whether Python is already installed:

python3 --version

On Windows, use:

python --version

or:

py --version

If the version shown is Python 3.10 or newer, Python is ready for this extractor.

Windows

Install Python from the official Python website:

• https://www.python.org/downloads/

During installation, enable Add python.exe to PATH if the installer offers that option.

After installation, open PowerShell and check:

python --version

If that does not work, try:

py --version

To run the extractor on Windows:

python neogeo_extractor.py

If your system uses the Python Launcher, this may also work:

py neogeo_extractor.py

macOS

Install Python from the official Python website:

• https://www.python.org/downloads/macos/

After installation, open Terminal and check:

python3 --version

To run the extractor on macOS:

python3 neogeo_extractor.py

Linux

Many Linux distributions already include Python 3. Check first:

python3 --version

If Python 3 is not installed, install it using your distribution package manager.

On Ubuntu, Debian, Linux Mint, or similar:

sudo apt update
sudo apt install python3

On Fedora:

sudo dnf install python3

On Arch Linux or Manjaro:

sudo pacman -S python

To run the extractor on Linux:

python3 neogeo_extractor.py

Notes

This project currently uses Python's standard library and does not require installing extra Python packages with pip.

If both python and python3 are available on your system, prefer python3 on macOS and Linux.

Basic Usage

Place the NeoGeo ROM Extractor folder inside the same folder that contains your supported game folders, such as an Amazon Games, Steam, GOG, or custom game folder.

Run the extractor from the command line:

python3 neogeo_extractor.py

On Windows, use:

python neogeo_extractor.py

By default, the script opens an interactive terminal menu. This is the recommended way to use the extractor.

From the menu, you can choose:

[1] Extract one game
[2] Extract all detected games
[3] Dry run / detect available games only
[4] List installed game modules
[5] Show paths
[6] Collect existing ZIPs from all folders
[Q] Quit

The menu is intended for normal use. The command-line options below are mainly useful for testing, automation, troubleshooting, or batch workflows.

Useful command-line options:

python3 neogeo_extractor.py --dry-run
python3 neogeo_extractor.py --list-modules
python3 neogeo_extractor.py --show-paths
python3 neogeo_extractor.py --all
python3 neogeo_extractor.py --game GAME_ID
python3 neogeo_extractor.py --collect-existing-zips

On Windows, use python instead of python3 if that is how Python is installed:

python neogeo_extractor.py --dry-run
python neogeo_extractor.py --list-modules
python neogeo_extractor.py --show-paths
python neogeo_extractor.py --all
python neogeo_extractor.py --game GAME_ID
python neogeo_extractor.py --collect-existing-zips

Game Modules

Game modules are stored in:

project_files/game_modules/

Game-specific information belongs in the relevant module, not in the core extractor.

Examples of game-specific data include:

• source filenames
• ROM slice offsets
• expected CRC32 values
• expected SHA1 values
• output ROM names
• patch rules
• game-specific quirks
• notes about unusual source layouts

The main extractor should remain as generic as possible.

Output

The extractor creates rebuilt ROM ZIPs for supported games when the source files match the expected data.

Output files are generated locally and are not included in this repository.

Generated output may contain copyrighted ROM or BIOS data extracted from the user's local source files. Generated files are for the user's own lawful local use and must not be committed to this repository or redistributed unless the user has the legal right to do so.

Verification

This project is verification-focused.

Where possible, extracted files are checked against expected hashes before final ZIP creation. If source files do not match the expected data, the extractor should fail rather than silently creating incorrect output.

What This Project Does Not Include

This repository does not include:

• Neo Geo ROMs
• Neo Geo BIOS files
• MAME ROM sets
• game executables
• Steam, GOG, or Amazon game data
• copyrighted assets
• decryption keys
• tools for downloading games
• instructions for piracy

Third-Party Tools

Some modules may support or reference external tools for specialised Neo Geo processing.

This repository does not include third-party binaries unless their licence clearly permits redistribution. Users are responsible for obtaining or building any optional external tools from lawful sources.

Do not submit third-party binaries unless their redistribution licence is clear and compatible with this project.

Credits and Acknowledgements

This project was informed by, adapted from, or cross-checked against earlier Neo Geo extraction, conversion, preservation, and emulation work.

Some sources were used as direct implementation references. Others were used for research, comparison, testing, or validation only. Inclusion here does not necessarily mean that code or data from that source is included in this repository, except where direct reuse is specifically stated below.

Projects and code references

The following projects were useful while developing this extractor:

• NGPrimeClaim by Lx32
• mslug-rom-extractor by terminatorhex
• goNCommand by Lionel Cordesses — important reference for several extraction workflows, including Kizuna Encounter, Metal Slug 4, and The King of Fighters 2003.

Where code, logic, offsets, extraction layouts, patch behaviour, conversion behaviour, or command-line workflows have been adapted from these projects, credit should also remain in the relevant source files or game modules.

Research notes and discussions

The following public notes, blog posts, scripts, and discussions were also used for research, comparison, or cross-checking:

• goNCommand issue #13
• alhumbra’s notes: https://milkchoco.info/archives/8695
• scrap-a’s notes: http://blog.livedoor.jp/scrap_a/archives/37910430.html
• Tomasz Bednarz’s related work and notes, 2023
• Lionel Cordesses’ KOF 2003 extraction/build script work, 2025

These references were especially useful for understanding The King of Fighters 2003, CMC-related processing, encrypted Neo Geo content, and ROM-set reconstruction.

Special thanks to terminatorhex

Special thanks to terminatorhex for the mslug-rom-extractor project, for your help understanding your code a little better, for working on Metal Slug 3 with me, and for the Metal Slug X JSON patch data reused in this project.

The Metal Slug X JSON patch data in this repository is directly reused from mslug-rom-extractor, with the file renamed for this project and credited here.

If it wasn't for your work this project wouldn't exist

• mslug-rom-extractor: https://github.com/terminatorhex/mslug-rom-extractor

Tools, algorithms, data, and reimplemented processing

Some extraction steps were researched, compared against, directly reused, adapted from, or independently reimplemented after studying earlier tools, scripts, data files, or commercial release workflows.

This does not necessarily mean that every referenced file, tool, script, or data file is included in this repository, used directly, or copied as-is. Where external code, data, logic, offsets, patch rules, or workflows have been directly reused or adapted, credit is given in this README.

• The Kizuna Encounter, Metal Slug 4, and The King of Fighters 2003 extraction modules were informed by goNCommand by Lionel Cordesses.
• neo-cmc was used as a reference point for CMC-related Neo Geo processing.
• tileswap logic was used as a reference point for graphics/tile data rearrangement where required.
• tiles2crom logic was used as a reference point for converting tile data into Neo Geo C-ROM-compatible output where required.
• unswizzle behaviour was studied from NGPrimeClaim and independently adapted for this project.
• For Metal Slug 3, parts of the Python implementation were developed by studying the observable behaviour of the original prog.exe workflow from the legally obtained release, then replacing that workflow with independently written Python code.

Where behaviour has been independently reimplemented in this repository, the relevant source files should also include local credit comments explaining which external project, tool, script, data file, or workflow informed that implementation.

This project does not redistribute neo-cmc, prog.exe, commercial game executables, third-party scripts, ROMs, BIOS files, encryption keys, or copyrighted game assets.

Emulator and validation references

Extracted files are checked against known emulator-compatible ROM layouts, names, sizes, and hashes where possible. Thanks are due to the contributors and maintainers of:

• MAME
• FBNeo

Their ROM definitions, naming conventions, hash records, and long-term hardware documentation work are important validation references for this project.

Affiliation disclaimer

This repository is not affiliated with, endorsed by, or maintained by SNK, Amazon, GOG, Steam, DotEmu, Code Mystics, MAME, FBNeo, Lx32, terminatorhex, Lionel Cordesses, Shigeshigeru, alhumbra, scrap-a, Tomasz Bednarz, or any other referenced project, contributor, publisher, distributor, or rights holder.

Use of a source as a reference does not necessarily mean this repository contains code from that source. Some sources were used only for comparison, verification, or background research.

Any mistakes, omissions, or project-specific implementation choices in this repository are my own.

Disclaimer

This project is provided for lawful personal preservation, backup, research, and interoperability purposes.

The author is not responsible for how users obtain, use, distribute, or handle copyrighted material. Users are responsible for complying with all applicable laws in their own country or region.

Contributing

Contributions may be considered once the project structure has stabilised.

Useful contributions include:

• new game modules
• hash verification improvements
• clearer error messages
• documentation improvements
• testing against legally owned releases

Do not submit ROMs, BIOS files, copyrighted game data, or proprietary assets.

Legal Notice

This project does not include, distribute, download, or provide access to ROMs, BIOS files, game executables, game data, or any other copyrighted assets.

You must provide your own legally obtained source files.

This tool is intended for users who own the relevant games and want to extract their own local copies for personal use, preservation, backup, or emulator compatibility.

Do not use this project to obtain, distribute, or share copyrighted game data that you do not have the legal right to use.

The author does not endorse piracy or copyright infringement.

License

This project is released under the GNU General Public License v3.0 or later.

See the LICENSE file for the full license text.

The source files use the SPDX identifier:

GPL-3.0-or-later

You may use, modify, and redistribute this extractor under the terms of the GPLv3 or any later version of the GPL.

If you redistribute this project or modified versions of it, you must preserve the license terms and provide the corresponding source code.