A GUI toolkit for preserving Project EGG retro PC game downloads.
Project EGG is a Japanese digital distribution service run by D4 Enterprise that sells classic retro PC games for systems including PC-8801, PC-9801, MSX, MSX2, X1, FM-7, Mega Drive, PC Engine, and others. Games are sold as .bin container files hosted on the service's CDN and can be purchased and downloaded through a free registered account.
This toolkit automates the full preservation workflow: fetching the raw files, packaging them into named archives, extracting their contents into usable game folders, maintaining a romanization CSV, and generating No-Intro-compatible DAT files.
- Python 3.10 or newer — https://www.python.org
- requests and pytz — required for the Download tab only:
pip install requests pytz - QuickBMS — required for the Extract tab only. Included, or download from: http://aluigi.altervista.org/papers.htm#quickbms
- project_egg_extract_bins_working.bms — the QuickBMS script for the Project EGG
.binformat. Included in this repository. - 7-Zip ZS (optional) — required only if your ZIP archives use ZStandard compression (method 93). Standard deflate/store ZIPs do not need it. Download from https://github.com/mcmilk/7-Zip-zstd
- A Project EGG account — free registration at https://www.amusement-center.com — required for downloading. No paid membership is needed.
python Eggmans_Project_EGG_Tools.py
The application opens as a tabbed window with six tabs: Download, Package, Extract, Romanize, DAT, and About.
All field values are saved automatically to Eggmans_Project_EGG_Tools_config.json in the same folder as the script whenever the application is closed. They are restored on the next launch, so you do not need to re-enter paths between sessions.
- Save Config button (toolbar) — saves immediately on demand at any time.
- Clear Tab button (toolbar) — resets all fields on the currently active tab to their defaults.
- Passwords are intentionally excluded from the config file for security.
Downloads the raw .bin game files directly from the Project EGG CDN.
- Logs in to the Project EGG API using your credentials and fetches the complete list of available content as a metadata JSON file (
data_YYYYMMDDHHMMSS.json). - Builds a list of every
.binfile referenced in that metadata. - Downloads each file to your specified download folder, skipping files that are already present and up to date (checked via HTTP
Last-Modifiedheader). - If an existing file has been updated on the server, the old copy is moved to a dated subfolder before the new version is downloaded.
- Saves HTTP response headers alongside each
.binas<filename>_headers.txt. These serve as timestamped proof of download and are not required for any other operation.
| Field | Description |
|---|---|
| Username | Your Project EGG account username |
| Password | Your Project EGG account password (not saved to config) |
| Download folder | Where the .bin files and headers will be saved |
| Use existing JSON | Tick this to skip server login and reuse a previously downloaded metadata JSON. Credentials are not required in this mode, but the metadata may be out of date. |
- A full download of all available content takes upwards of 10 hours. The tool deliberately downloads slowly to avoid overloading the server. This is by design. Slow is steady, steady is fast.
- You can stop at any time with the Cancel button. Re-running with the same download folder and JSON will resume from where you left off, skipping already-downloaded files.
- As of 2026-04-02 there are 2,654 files available.
- It is recommended to use a VPN.
- The metadata JSON is saved as UTF-8-BOM so Japanese characters display correctly in Windows applications.
Groups downloaded .bin files into named ZIP archives using store compression (no recompression — the .bin files are already compressed internally where applicable).
-
Reads the metadata JSON to determine which
.binfiles belong to each game entry (game filea, manualm, and musicd). -
For each entry that has at least one
.binfile present in the download folder, creates a ZIP archive in the output folder. -
The ZIP filename is constructed from the game's metadata:
Title (Year) (Region) (Platform) [ProductId] [bin].zipExample:
ロストパワー (1986) (Japan) (PC-8801) [24] [bin].zipThe
[bin]tag distinguishes these archives from extracted-content ZIPs if both sets are stored in the same location. -
If some but not all expected files are present, the archive is created from what is available and tagged
[incomplete]in the filename. -
If no files for an entry are on disk, the entry is recorded in the end-of-log missing list.
-
Already-packaged ZIPs are skipped on re-runs — safe to run incrementally as new downloads arrive.
| Field | Description |
|---|---|
| Download folder | The folder containing your downloaded .bin files (read only — never modified) |
| Metadata JSON | Path to the data_*.json file produced during download |
| Output folder | Where the ZIP archives will be written — must be different from the download folder |
- No metadata — JSON entries that list no filenames at all (shows productId and title)
- Missing from disk — entries whose files are not in the download folder, with the would-be ZIP name
- Unprocessed .bin files —
.binfiles on disk that were not matched to any JSON entry
Some entries in the metadata have a year value of 複数 (meaning "multiple") or contain a /. These are written as multi-year in the archive filename.
Extracts the contents of .bin files into named game folders using QuickBMS.
-
Reads the metadata JSON to group each game's
.binfiles. -
For each game, creates a named subfolder in the output folder:
Title (Year) (Region) (Platform) [ProductId] [ext]The
[ext]tag distinguishes these folders from Package ZIPs when both sets are stored together. -
Runs QuickBMS on each
.binfile, extracting its contents into that game folder. All files from multiple.binparts (game, manual, music) go into the same folder, preserving the internal subdirectory structure from the archive. -
After extraction, automatically renames all mojibake filenames to their correct Japanese names (see below).
-
Skips game folders that already exist and contain files — safe to re-run.
| Field | Description |
|---|---|
| QuickBMS executable | Path to quickbms.exe |
| BMS script | Path to project_egg_extract_bins_working.bms |
| Download folder | The folder containing your downloaded .bin files (read only) |
| Metadata JSON | Path to the data_*.json file produced during download |
| Output folder | Where the extracted game folders will be written |
The Preview .bin filenames… button lets you select one or more .bin files and see the correct Japanese filenames stored inside their headers without extracting anything. Useful for verifying expected content before a full run, and for identifying the correct target name of a mojibake file.
Project EGG .bin files store filenames in Shift-JIS (Japanese encoding). On a Western Windows system, QuickBMS passes those raw bytes to the Windows file system via the cp1252 ANSI codepage. This produces garbled (mojibake) filenames like:
ƒGƒŒƒx[ƒ^[ƒAƒNƒVƒ‡ƒ".exe → エレベーターアクション.exe
The tool corrects these automatically after each extraction:
- Parses the correct filenames and exact decompressed sizes from the
.binheaders and from QuickBMS stdout output. - Matches each mojibake disk file to its correct name using
(file extension, exact file size)— these properties survive encoding damage intact. - As a tiebreaker for files with the same extension and size, the ASCII prefix of the filename stem (e.g.
5_from5_プリンセス・アン.wav) is used, since ASCII characters are unaffected by the encoding mismatch. - Moves each file to its correct name and location. Some Shift-JIS characters have
0x5C(backslash) as their second byte, which Windows interprets as a path separator, accidentally splitting filenames across new subdirectories. The tool detects and corrects this, removing any empty accidental directories afterward.
A small number of files cannot be automatically matched because two or more files in the same archive share an identical extension and file size with no ASCII prefix to distinguish them. These appear in the log as:
[INFO] Cannot uniquely match 'filename' — skipped
Use the Preview button alongside the log to identify the correct target names, then rename manually. The following are the known affected games:
| ProductId | Title | Files requiring manual rename |
|---|---|---|
| 639 | エレベータアクション＆ジャイロダイン／タイトーＭＳＸコレクション１ | PTIT0003\エレベーターアクション.exe, PTIT0003\ジャイロダイン.exe |
| 640 | スクランブルフォーメーション＆フロントライン／タイトーＭＳＸコレクション２ | PTIT0004\スクランブルフォーメーション.exe, PTIT0004\フロントライン.exe |
| 643 | ラスタンサーガ＆雀フレンド／タイトーＭＳＸコレクション３ | PTIT0005\ラスタンサーガ.exe, PTIT0005\雀フレンド.exe |
These three games each have exactly two .exe files with identical sizes. No automatic disambiguation is possible without further reverse engineering of the archive structure.
Maintains the romanization CSV that maps Japanese game titles to their English romanized equivalents. These romanized titles feed into the DAT generator.
- Loads the existing
romanizations.csv(if one is provided). - Compares it against the metadata JSON and adds any entries not yet in the CSV, with the Japanese title in the
titlecolumn and a blankromanizedcolumn ready to be filled in. - Sorts the full list by
productIdascending. - Saves the result as a new timestamped file:
romanizations_YYYYMMDDHHMMSS.csv
Entries without a romanization will use the Japanese title in all DAT output until a romanization is added and a new CSV is generated.
| Field | Description |
|---|---|
| Metadata JSON | Path to the data_*.json file produced during download |
| Existing romanizations CSV | Path to your current romanizations.csv (optional — leave blank to build from scratch) |
| Output folder | Where the updated CSV will be saved (recommended: a docs/ subfolder of your script folder) |
The CSV uses UTF-8-BOM encoding. The safest way to edit it while preserving Japanese characters is to open it in Google Sheets (File → Import), fill in the romanized column, then download as CSV. Excel can mishandle the encoding on save.
Generates No-Intro-compatible DAT files for use with RomVault or other DAT-based ROM management tools. Three DAT types can be generated independently or all at once in a single run.
For each enabled DAT type, the generator:
- Scans the relevant folder for ZIP files.
- Hashes the contents of each ZIP (CRC32 + SHA1).
- Builds
<game>entries using the romanized title where available, falling back to the Japanese title. - Writes the
<description>field using the original Japanese title. - Saves the DAT with a date-stamped filename.
Project EGG Collection - Downloads (bin) (YYYY-MM-DD_RomVault).dat
Each raw .bin file is wrapped in its own individual ZIP (one .bin per ZIP), and the DAT hashes the .bin file inside. Game entries are named by the .bin stem (e.g. AGL0001a).
If the Downloads ZIPs folder does not yet contain ZIPs when you run the DAT generator, the tool will offer to create them automatically using store compression (no recompression of the original .bin data).
Project EGG Collection - Games (bin) (YYYY-MM-DD_RomVault).dat
Reads the ZIPs produced by the Package tab. Each ZIP contains the .bin files for one game entry. The DAT hashes each .bin file inside the ZIP. Game entries are named using the full metadata title format with [bin] suffix.
Project EGG Collection - Games (extracted) (YYYY-MM-DD_RomVault).dat
Reads ZIPs containing the extracted game file contents. Each ZIP should contain the extracted folder for one game entry (created by zipping up the output of the Extract tab). Internal file paths are preserved with forward-slash separators. Game entries are named using the full metadata title format with [ext] suffix.
| Field | Description |
|---|---|
| Metadata JSON | Path to the data_*.json file produced during download |
| Romanizations CSV | Path to the romanizations CSV (optional — Japanese titles used if omitted) |
| Output folder | Where the DAT files will be written |
| Author | Your name, written into the DAT header (default: Eggman) |
| 7-Zip ZS executable | Path to 7z.exe from 7-Zip ZS — only needed if your ZIPs use ZStandard compression |
| Downloads (bin) checkbox | Enable/disable the Downloads (bin) DAT |
| Download folder | Folder containing the raw .bin files |
| Downloads ZIPs folder | Folder where per-file .bin ZIPs are stored or will be created |
| Games (bin) checkbox + folder | Enable/disable + folder containing Package tab ZIPs |
| Games (extracted) checkbox + folder | Enable/disable + folder containing extracted-content ZIPs |
If your ZIP archives use ZStandard compression (method 93), Python's built-in ZIP handling cannot read them. The tool automatically falls back to 7-Zip ZS for those files if you have provided the path to its executable. ZIPs using standard deflate or store compression do not require 7-Zip.
All tabs share a single log window at the bottom of the application. The log scrolls automatically and persists until cleared.
- Save Log — saves the full log as a UTF-8-BOM
.txtfile with a timestamped name. The prefix reflects the active tab:egg_download_log_...,egg_packager_log_...,egg_extract_log_...,egg_romanize_log_..., oregg_dat_log_... - Clear Log — clears the log window.
1. Download tab → fetch .bin files + metadata JSON to your download folder
2. Romanize tab → merge any new entries into romanizations.csv; fill in titles
3. Package tab → ZIP the .bin files into [bin]-tagged named archives
4. Extract tab → extract game contents into [ext]-tagged named folders
5. DAT tab → generate DAT files for RomVault / archival verification
The download folder is treated as read-only by all other tabs. Original .bin files are never modified or moved. All operations are safe to re-run — existing output is detected and skipped.
All output filenames follow the same pattern:
Title (Year) (Region) (Platform) [ProductId] [type]
Where:
- Title — romanized title from the CSV if available; otherwise the Japanese title from the metadata
- Year — release year, or
multi-yearif the metadata lists multiple years (複数or contains/) - Region —
Japanfor region 0,Worldfor region 1 - Platform — system name; Japanese platform names are translated:
アーケード→Arcadeメガドライブ→Mega DrivePCエンジン→PC Engineその他→Other
- [ProductId] — the numeric product ID from the metadata
- [bin] — appended to Package tab ZIPs
- [ext] — appended to Extract tab output folders
- [incomplete] — appended when expected files are missing from disk
These files no longer exist on the server and cannot be downloaded.
| Filename | ProductId | Title |
|---|---|---|
| BOT3008a.bin | 765 | T.N.T. |
| COM5032a.bin / COM5032m.bin | 1264, 1265 | Jino-Brodiaea's Wander Number; After Devil Force Gaiden |
| COM5033a.bin / COM5033m.bin | 1266 | Gensei Haiyuuki |
| COM5034a.bin / COM5034m.bin | 1267 | DEVIL FORCE III: Ken to Hanataba |
| COM5035a.bin / COM5035m.bin | 1268 | After Devil Force - Kyou-ou no Koukeisha |
| COM5036a.bin / COM5036m.bin | 1269 | Geo Conflict 3 - Hell's Gate Crusaders |
| COM5038a.bin / COM5038m.bin | 1270 | Daikaisen |
| COM5039a.bin / COM5039m.bin | 1271 | Quiz Tsunahiki Champ |
| COM5040a.bin / COM5040m.bin | 1272 | Poly Poly! Speed Daisakusen |
| HAM1010a.bin | 2095 | Fireball |
| SKP0011m.bin | 1044 | Ironclad |
| STW1003a.bin | 173 | Shiro to Kuro no Densetsu - Hyakki-hen (Ongaku Data nomi) |
| XTA0047a.bin / XTA0047m.bin | 2094 | Crimson II: The Revenge of the Evil God |
These metadata entries exist but have no downloadable files. They may be delisted or unreleased titles.
| Title | ProductId | Platform |
|---|---|---|
| 1chipMSXテストデータ_act (2004) | 509 | MSX |
Two files have incorrect filenames in the metadata that differ from what the CDN actually serves. These are corrected automatically across all tabs.
| Metadata Filename | Actual CDN Filename |
|---|---|
| ECOM3005a.bin | COM3005a.bin |
| COM3008.bin | COM3008a.bin |
For reference, the known count of available downloads at various points in time:
| Date | Count |
|---|---|
| 2023-07-28 | 2,456 |
| 2024-05-18 | 2,547 |
| 2025-08-02 | 2,631 |
| 2026-04-02 | 2,654 |
Original source code, scripts, tooling, and hand-authored documentation and metadata in this repository are licensed under the MIT License.
Archived game data, binaries, firmware, media assets, and other third-party materials are not covered by the MIT License and remain the property of their respective copyright holders.
See the LICENSE and NOTICE files for full details and scope clarification.
This GUI was built by Eggman, extending and wrapping the original deviled-eggs command-line tools with a full graphical interface, automated download handling, ZIP packaging, QuickBMS-based extraction with automatic mojibake correction, romanization CSV management, and DAT file generation.
Original deviled-eggs project credits:
| Name | Contribution |
|---|---|
| Eintei | All original reverse engineering and format documentation |
| obskyr | Original data.json download script |
| Bestest | Coordination, leadership, reverse engineering |
| Hiccup | Datting support and advice |
| proffrink | Scraping, research |
| Shadów | Reverse engineering |
| Icyelut | Original script, romanization |
