🕹️ portable-retro-games

Play retro games instantly — each game is a single standalone HTML file, no install, no server, works offline in any browser forever

🤔 What is this?

portable-retro-games is a collection of Python scripts that package retro game ROMs and disk images into self-contained, offline-playable HTML files.

Each generated HTML file embeds:

✅ A full browser-based emulator (JavaScript / WebAssembly)
✅ The game ROM or disk image (base64-encoded)
✅ Touch-friendly controls with virtual keyboard/gamepad support
✅ Zero external dependencies — works offline, forever

One file. One game. Any browser. Any device. No internet needed.

This means you can take a retro game file — from NES to N64, from Game Boy to Amiga, from Arcade to DOOM — run a single command, and get an HTML file that plays the game in Chrome, Firefox, or Safari — on desktop or mobile — with no server, no installation, no plugins.

Why does this matter?

Retro games are disappearing. Hardware fails. Websites go offline. Flash died. Java applets are gone. portable-retro-games creates permanent, portable, self-contained game archives that will work as long as web browsers exist.

🖥️ Supported Platforms

🌐 Universal Packer — 41 Console, Computer & Arcade Systems

The Universal Packer (packers/universal/pack_game.py) supports 41 retro systems with a single script, zero pip dependencies:

Category	Systems	Count
🎮 Nintendo	NES / Famicom, Super Nintendo, Game Boy, Game Boy Color, Game Boy Advance, Nintendo 64, Nintendo DS, Virtual Boy	8
🎮 Sega	Genesis / Mega Drive, Master System, Game Gear, Sega 32X, Sega CD / Mega CD, Sega Saturn	6
🎮 Atari	2600, 5200, 7800, Lynx, Jaguar	5
🎮 Sony	PlayStation	1
🎮 NEC	PC Engine / TurboGrafx-16, PC-FX	2
🎮 SNK	Neo Geo Pocket / Color	1
🎮 Bandai	WonderSwan / Color	1
🎮 Coleco	ColecoVision	1
💻 Commodore	C64, C128, VIC-20, PET, Plus/4, Amiga	6
💻 Sinclair	ZX Spectrum, ZX81	2
💻 Amstrad	CPC	1
🕹️ Arcade	CPS1, CPS2, FBNeo, MAME 2003+	4
🔫 id Software	DOOM (PrBoom)	1
🎮 Other	3DO Interactive, Philips CD-i	2
	Total	41

Powered by EmulatorJS — cores are auto-downloaded and cached locally. A cores.zip bundle is included for full offline use.

🔧 Platform-Specific Packers — Advanced Features

For these platforms, dedicated packers provide enhanced features like keyboard auto-detection, firmware analysis, and custom virtual keyboards:

Platform	Packer Script	Emulator	Input Formats	Key Features
🍎 Apple II	`pack_apple2_game_html.py`	apple2js	`.dsk`, `.do`, `.po`, `.nib`, `.woz`	Auto keyboard detection, DOS 3.3 catalog parsing, model selection (II/II+/IIe)
💾 Amstrad CPC	`pack_cpc_game_html.py`	RVMPlayer	`.dsk` (DSK/EDSK)	Z80 firmware call analysis, AZERTY→QWERTY mapping, warp-speed loading
🐱 Commodore Amiga	`build_jimmy_willburne.py`	vAmigaWeb	`.adf`	WASM emulation, IndexedDB caching, full asset inlining, virtual joystick
🏴‍☠️ ScummVM	`pack_scummvm_game.py`	ScummVM	Game folders (98 engines)	WASM emulation, auto engine detection, gzipped plugins (~101 MB), mobile SAF path support
🎮 MSX	`pack_msx_game_en.html` (Web)	EmulatorJS (blueMSX)	`.rom`, `.mx1`, `.mx2`, `.dsk`, `.cas`, `.zip`	Auto mapper detection (ASCII8/16, Konami, SCC), multi-disk swap, MSX1/2/2+ selection, sound presets

💡 Note: Amstrad CPC and Commodore Amiga are available in both the universal packer (convenience, one script) and as dedicated packers (superior emulation quality, custom keyboards, firmware analysis). Use the dedicated packers for the best experience.

⚡ Quick Start

🌐 No Install? Use the Web Packer!

Don't want to install Python? Use the Web GUI directly in your browser:

Drop a ROM, pick your system, click Generate — get a standalone HTML file. No Python, no terminal, no install.

💡 The Web Packer includes a local mirror of all cores, so it works even if the EmulatorJS CDN goes offline. 💡 The ScummVM Web Packer includes gzipped engine plugins served locally for reliable cross-origin loading.

Prerequisites

python --version   # Python 3.12+ (all packers)

🌐 Universal Packer — Any Console Game (41 Systems)

cd packers/universal

# Pack any ROM — system is auto-detected from file extension
python3 pack_game.py SuperMario.nes
python3 pack_game.py Sonic.gen
python3 pack_game.py Pokemon.gba
python3 pack_game.py Mario64.z64
python3 pack_game.py DOOM.wad

# Pack arcade ROM (system must be specified)
python3 pack_game.py streetfighter2.zip --system cps1

# Custom title & output
python3 pack_game.py Zelda.sfc --title "Zelda - A Link to the Past" --output zelda.html

# List all supported systems & file extensions
python3 pack_game.py --list-systems

# Use an alternative core
python3 pack_game.py game.nes --core nestopia

# Check which cores are cached locally
python3 pack_game.py --offline-status

# Download ALL cores at once for full offline use
python3 pack_game.py --prefetch-all

Output: A single .html file — open it in any browser 🎮

💡 The first time you pack a game for a given system, the WASM core is downloaded from the EmulatorJS CDN and cached locally (~/.emulatorjs_cache/). All subsequent games for that system work 100% offline. You can also place cores in a cores/ folder next to the script or unzip the included cores.zip for fully portable offline use.

🍎 Apple II — Pack a Game

cd packers/apple2
pip install beautifulsoup4 requests

# Pack a .dsk disk image into a playable HTML file
python pack_apple2_game_html.py Karateka.dsk

# Specify Apple II model
python pack_apple2_game_html.py --model apple2e "Oregon Trail.dsk"

# The packer auto-detects if the game needs arrow keys, letters, or both
# and generates the appropriate virtual keyboard

Output: Karateka.html — open it in any browser 🎮

💾 Amstrad CPC — Pack a Game

cd packers/cpc
pip install beautifulsoup4 requests

# Pack a CPC DSK file
python pack_cpc_game_html.py Gryzor.dsk

# Enable warp-speed loading (fast-forward through tape/disk loading)
python pack_cpc_game_html.py --warp Gryzor.dsk

# The packer reads the DSK catalog, finds the boot program,
# analyzes BASIC/Z80 code for keyboard usage, and generates
# the perfect virtual keyboard layout

Output: Gryzor.html — 132 French CPC games already converted! 🇫🇷

🏴‍☠️ ScummVM — Pack a Point-and-Click Adventure

cd packers/scummvm

# Pack a ScummVM game folder into a playable HTML file
python3 pack_scummvm_game.py /path/to/monkey_island/

# The packer auto-detects the ScummVM engine from game files
# Supports 98 engines: SCUMM, AGI, SCI, Kyra, Lure, Sword, and many more

# Custom title & language
python3 pack_scummvm_game.py /path/to/game/ --title "Monkey Island" --lang en

Output: A single .html file — open it in any browser 🎮

💡 The packer downloads the ScummVM WASM core (~37 MB) and the appropriate engine plugin automatically. Engine plugins are gzip-compressed for efficient storage (~101 MB total for all 95 engines).

🐱 Amiga — Build a Game

cd packers/amiga

# Build a standalone HTML from an ADF disk image
python build_jimmy_willburne.py

# Build with IndexedDB caching (faster reload)
python build_jimmy_willburne_cached.py

# The builder inlines EVERYTHING: WASM emulator, Kickstart ROM,
# game disks, JS, CSS, images, SVG sprites, and sounds

Output: A complete Amiga experience in a single HTML file 🚀

🎮 Live Demos — Try It Now!

No install needed — click and play directly in your browser:

Game	Platform	Link
🐱 Jimmy Willburne	Amiga	▶️ Play Now
🐱 Short Grey	Amiga	▶️ Play Now
🍎 Softporn Adventure VF	Apple II	▶️ Play Now
🍎 Le Dragon Gardien	Apple II	▶️ Play Now
🍎 Mystery House VF	Apple II	▶️ Play Now
💾 1815	Amstrad CPC	▶️ Play Now
🌐 Web Packer	All 41 systems	🇬🇧 English · 🇫🇷 Français
🏴‍☠️ ScummVM Web Packer	98 point-and-click engines	🇬🇧 English · 🇫🇷 Français
🎮 MSX Web Packer	MSX / MSX2 / MSX2+	🇬🇧 English · 🇫🇷 Français

💡 These are real examples generated by the packers in this repo — each is a single self-contained HTML file hosted on Netlify.

📱 Mobile Experience

Each packed game includes responsive controls optimized for touch:

Packer	Virtual Controls
Universal (EmulatorJS)	Built-in virtual gamepad, D-pad, ABXY buttons, responsive viewport
Apple II	Arrow keys, letter grid, digit row, special keys (ESC, RETURN, SPACE)
Amstrad CPC	Context-detected keys, AZERTY layout, joystick option
Amiga	Virtual joystick with fire button, touch-anywhere controls
ScummVM	Touch-to-click point-and-click interface, responsive viewport, Android SAF path support
MSX	Built-in EmulatorJS virtual gamepad, responsive viewport, multi-disk swap buttons

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     portable-retro-games                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌──────────┐    ┌──────────────┐    ┌───────────────────┐    │
│   │ Game ROM  │───▶│ Packer Script│───▶│ Self-Contained    │    │
│   │ or Disk   │    │  (Python)    │    │  HTML File        │    │
│   │  Image    │    │              │    │                   │    │
│   │ .nes .sfc │    │ • Detect sys │    │ ┌───────────────┐│    │
│   │ .gb .gba  │    │ • Fetch core │    │ │  Emulator JS  ││    │
│   │ .gen .z64 │    │ • Embed all  │    │ │  + WASM Core  ││    │
│   │ .dsk .adf │    │ • Optimize   │    │ ├───────────────┤│    │
│   │ .woz .nib │    │ • Build HTML │    │ │  Game Data    ││    │
│   │ .wad .zip │    │              │    │ │  (base64)     ││    │
│   └──────────┘    └──────────────┘    │ ├───────────────┤│    │
│                                        │ │  Virtual      ││    │
│                                        │ │  Controls     ││    │
│                                        │ │  (HTML/CSS/JS)││    │
│                                        │ ├───────────────┤│    │
│                                        │ │  Boot Logic   ││    │
│                                        │ │  & Helpers    ││    │
│                                        │ └───────────────┘│    │
│                                        └───────────────────┘    │
│                                                                 │
│   Packers:                                                      │
│   ────────                                                      │
│   • Universal  → EmulatorJS + WASM cores (41 systems)           │
│   • Apple II   → apple2js (keyboard auto-detection)             │
│   • CPC        → RVMPlayer (Z80 firmware analysis)              │
│   • Amiga      → vAmigaWeb (full asset inlining)                │
│   • ScummVM    → ScummVM WASM (98 engines, gzipped plugins)     │
│   • MSX        → EmulatorJS blueMSX (mapper auto-detect, multi-disk) │
│                                                                 │
│   Common Techniques:                                            │
│   ─────────────────                                             │
│   • Base64 encoding for binary data embedding                   │
│   • Blob URLs & Data URIs for asset serving                     │
│   • 3-layer interception (EJS_paths + MutationObserver + fetch)  │
│   • AudioContext resume on first gesture (Chrome mobile)        │
│   • Dynamic viewport (100dvh) with safe area insets             │
│   • Anti-zoom CSS for mobile viewport                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

How It Works (Step by Step)

Universal Packer (Console Games)

   ROM File                  pack_game.py                     Browser
  ┌──────────┐              ┌──────────────┐              ┌──────────────┐
  │          │   1. Read    │              │   4. Output  │              │
  │  .nes    │─────────────▶│  Auto-detect │─────────────▶│  Open HTML   │
  │  .sfc    │              │  system from │              │  in browser  │
  │  .gba    │              │  extension   │              │              │
  │  .z64    │              │              │              │  5. EmulatorJS│
  │  .wad    │              │  2. Load or  │              │  intercepts  │
  └──────────┘              │  download    │              │  fetch calls │
                            │  WASM core   │              │  → serves    │
  WASM Core                 │              │              │  embedded    │
  ┌──────────┐              │  3. Encode   │              │  data        │
  │          │   3. Embed   │  ROM + core  │              │              │
  │ cores/   │─────────────▶│  as base64   │              │  6. Game     │
  │ or cache │   (offline   │  in HTML     │              │  boots! 🎮   │
  │ or CDN   │    first)    │              │              │              │
  └──────────┘              └──────────────┘              └──────────────┘

Platform-Specific Packers (Apple II, CPC, Amiga)

   Disk Image                 Python Packer                    Browser
  ┌──────────┐              ┌──────────────┐              ┌──────────────┐
  │          │   1. Read    │              │   4. Output  │              │
  │  .dsk    │─────────────▶│  Parse disk  │─────────────▶│  Open HTML   │
  │  .adf    │              │  catalog     │              │  in browser  │
  │  .woz    │              │              │              │              │
  └──────────┘              │  2. Analyze  │              │  5. Emulator │
                            │  content for │              │  boots game  │
  Emulator                  │  keyboard    │              │  from        │
  ┌──────────┐              │  detection   │              │  embedded    │
  │          │   3. Fetch   │              │              │  data        │
  │  JS/WASM │─────────────▶│  Embed all   │              │              │
  │  assets  │   & cache    │  into single │              │  6. Virtual  │
  │          │              │  HTML file   │              │  keyboard    │
  └──────────┘              └──────────────┘              │  appears     │
                                                          └──────────────┘

🌟 Possibilities This Opens

🏛️ Digital Preservation

Package entire game libraries into portable HTML files. No more worrying about emulator websites going offline, plugin deprecation, or server shutdowns. Your games survive forever.

🎓 Education

Teachers can distribute retro computing experiences as simple HTML files. Students open them in any browser — no installation, no configuration, no IT department approval needed.

📚 Personal Collections

Build your own curated retro game library. Each game is a single file you can organize in folders, back up to cloud storage, or carry on a USB drive.

📱 Mobile Retro Gaming

Play NES, SNES, Game Boy, Genesis, N64, Arcade, Apple II, CPC, Amiga and more on your phone or tablet. Touch controls are built right in.

🏛️ Museums & Exhibitions

Interactive exhibits that run on any tablet or kiosk. No internet connection required. No maintenance. Just open the HTML file.

🌐 Offline Access

Perfect for situations with limited or no internet: airplanes, remote areas, schools with restricted networks, archival storage.

📤 Easy Sharing

Share a game with anyone by sending a single file. No instructions needed — just "open this in your browser." Works on Windows, Mac, Linux, iOS, Android, ChromeOS.

📖 Documentation

Document	Description
Universal Packer	Complete guide to the Universal Packer: 41 systems, offline mode, all options
Apple II Packer	Complete guide to the Apple II packer: disk formats, key detection, virtual keyboard
CPC Packer	Complete guide to the Amstrad CPC packer: DSK parsing, Z80 analysis, AZERTY mapping
Amiga Packer	Complete guide to the Amiga packer: WASM embedding, asset inlining, caching
ScummVM Packer	Complete guide to the ScummVM packer: 98 engines, WASM emulation, gzipped plugins, mobile support
MSX Packer	Web-only MSX packer: ROM/DSK/CAS support, auto mapper detection (ASCII8/16, Konami, SCC), multi-disk swap, MSX1/2/2+
Architecture	Technical deep-dive: embedding strategies, mobile patterns, emulator integration
Future Enhancements	Roadmap: save states, PWA support, more platforms, compression, batch processing
Supported Platforms Roadmap	🗺️ 40+ retro platforms feasibility analysis, priority ranking & universal packer vision

🔧 Technical Highlights

Universal System Detection 🔍

The universal packer auto-detects the target system from file extensions:

.nes → NES (FCEUmm)             .sfc/.smc → SNES (Snes9x)
.gb → Game Boy (Gambatte)        .gbc → Game Boy Color (Gambatte)
.gba → GBA (mGBA)               .gen/.md → Genesis (Genesis Plus GX)
.z64/.n64/.v64 → N64 (Mupen64)  .nds → Nintendo DS (melonDS)
.a26 → Atari 2600 (Stella)      .a52 → Atari 5200 (a5200)
.a78 → Atari 7800 (ProSystem)   .lnx → Atari Lynx (Handy)
.j64/.jag → Atari Jaguar        .gg → Game Gear (Genesis Plus GX)
.sms → Master System (SMSPlus)  .32x → Sega 32X (PicoDrive)
.pce → PC Engine (Mednafen)     .col → ColecoVision (GearColeco)
.ngp → Neo Geo Pocket (Mednafen) .ws/.wsc → WonderSwan (Mednafen)
.vb → Virtual Boy (Beetle VB)   .d64/.prg → C64 (VICE x64sc)
.adf → Amiga (PUAE)             .dsk → Amstrad CPC (cap32)
.wad → DOOM (PrBoom)            .zip → Arcade (CPS1/CPS2/FBNeo/MAME)
.iso/.bin/.cue/.chd → 3DO (Opera)  .chd/.iso → Philips CD-i (same_cdi)
.bin/.cue/.iso/.chd → Sega Saturn (Yabause)
...and more — run --list-systems for the full list

Offline-First Architecture 📡

The universal packer resolves assets in this order:

cores/ directory — portable offline bundle next to the script
~/.emulatorjs_cache/ — persistent local cache
EmulatorJS CDN — only if not cached (first use per system)

# Pre-download everything for full offline use
python3 pack_game.py --prefetch-all    # All 41 systems, 92 core files (46 × 2: normal + legacy)

# Or unzip the included cores bundle
unzip cores.zip                        # Included in the repo

# Check what's cached
python3 pack_game.py --offline-status

Keyboard Auto-Detection 🎹

Platform-specific packers analyze the game content to determine which keys the player will need:

Apple II: Reads DOS 3.3 catalog entries — text adventures get a full letter grid; arcade games get arrow keys and a few action buttons
CPC: Parses BASIC source for INKEY$, JOY() patterns and scans Z80 binaries for firmware calls (BB09h, BB1Bh) to detect keyboard vs. joystick input
Amiga: Configures virtual joystick + fire button (most Amiga games are joystick-based)

Emulator Asset Management 📦

Each packer manages its own cache:

~/.emulatorjs_cache/        # Universal packer — WASM cores + EmulatorJS
~/.apple2js_cache/          # Apple II emulator JS + ROM files
~/.cpc_emulator_cache/      # RVMPlayer emulator resources
./vAmigaWeb/                # vAmiga WASM + support files

Mobile-First Design 📱

Dynamic viewport height (100dvh) with safe area insets for notched devices
Touch event handling with proper preventDefault() to avoid scroll/zoom
AudioContext resume on first user gesture (required by Chrome/Safari)
Viewport locking with user-scalable=no and touch-action CSS
Responsive layouts that adapt to screen orientation
WebGL with 2D Canvas fallback for older devices

Single-File Philosophy 📄

Everything is embedded. The generated HTML files contain:

Content	Encoding	Typical Size
Emulator engine (JS)	Inline `<script>`	200KB – 2MB
Emulator engine (WASM)	Base64 in `<script>`	1MB – 5MB
Game ROM / disk image	Base64 in `<script>`	140KB – 50MB
Kickstart ROM (Amiga)	Base64 in `<script>`	512KB
Virtual keyboard/controls	Inline HTML/CSS/JS	10KB – 30KB
Fetch/XHR interceptors	Inline `<script>`	2KB – 5KB
Help overlay	Inline HTML/CSS	5KB
Images/SVG/sounds	Base64 Data URIs	Variable

🎮 Game Library

🌐 Universal Packer — 41 Systems Supported

The universal packer supports 41 retro systems with a single Python script. Most systems work out of the box; some may require specific ROM formats or BIOS files for optimal results.

Status	Systems
✅ Fully tested	NES, SNES, Game Boy, GBC, GBA, N64, NDS, Genesis, Master System, Game Gear, 32X, Atari 2600, 5200, 7800, Lynx, ColecoVision, Neo Geo Pocket, Virtual Boy, WonderSwan, PC Engine, C64, ZX Spectrum
🟡 Supported — may need tuning	PSX (needs BIOS), Sega CD (large CD images), Jaguar, C128, VIC-20, PET, Plus/4, Amiga, CPC, ZX81, PC-FX
🕹️ Arcade / DOOM	CPS1, CPS2, FBNeo, MAME 2003+, DOOM (require `--system` flag + correct ROM sets)

💡 Systems marked "may need tuning" boot correctly via EmulatorJS but may require specific ROM formats, firmware files, or configuration depending on the game. Contributions and testing feedback are welcome!

Amstrad CPC — 132 French Games Ready 🇫🇷

The CPC packer has been battle-tested with a library of 132 classic French CPC games, all successfully converted to offline HTML. These include:

Action/Arcade: Gryzor, Rick Dangerous, Renegade, Barbarian
Adventure: Sorcery, L'Aigle d'Or, Sapiens
Sports: Kick Off, Match Day II, Track & Field
Puzzle: Tetris, Boulder Dash, Sokoban
RPG: Donjons et Dragons, Sram, L'Anneau de Doigts

Apple II — Classic Titles

Karateka, Prince of Persia, Oregon Trail
Zork, Ultima, Lode Runner, Choplifter

Amiga — Custom Builds

Individually crafted builds with game-specific optimizations
Full Amiga experience: ECS Agnus, 2MB Chip RAM, 2MB Fast RAM

🤝 Credits & Acknowledgments

This project stands on the shoulders of incredible open-source emulator projects:

Emulator	Author	Platform	Technology
EmulatorJS	EmulatorJS contributors	41 console/computer/arcade systems	WebAssembly (RetroArch cores)
apple2js	Will Scullin	Apple II	JavaScript
RVMPlayer	—	Amstrad CPC	JavaScript
vAmigaWeb	Dirk W. Hoffmann & contributors	Commodore Amiga	WebAssembly (Emscripten)
ScummVM	ScummVM Team	98 point-and-click adventure engines	WebAssembly
EmulatorJS (blueMSX)	EmulatorJS contributors	MSX / MSX2 / MSX2+	WebAssembly (RetroArch blueMSX core)

Special thanks to all the retro computing communities keeping these platforms alive:

Archive.org for preserving software history
CPCWiki for Amstrad CPC documentation
Apple II Documentation Project
English Amiga Board for Amiga preservation efforts
EmulatorJS for making RetroArch cores accessible in the browser

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Game disk images and ROMs are NOT included in this repository. You must own or have legal access to the games you package. This tool is intended for personal archival and preservation purposes.

🛠️ Contributing

Contributions are welcome! Here are some ways you can help:

Add support for new platforms (more computers, handhelds…)
Improve key detection algorithms for platform-specific packers
Optimize file sizes (compression, lazy loading)
Test on more devices and browsers
Translate the virtual keyboard overlays
Add save state support to the universal packer

Please open an issue first to discuss major changes.

📊 Project Stats

46 platforms supported (41 universal + 5 platform-specific with advanced features, including ScummVM with 98 engines and MSX with mapper auto-detection)
132+ games tested and converted (CPC library)
22 systems fully validated with real ROM testing, 41 total supported
0 pip dependencies for the universal packer (Python stdlib only)
0 runtime dependencies in generated HTML files
100% offline — no server, no CDN, no internet
Mobile-ready with touch-optimized virtual controls

🏷️ Keywords

retro gaming · emulator · offline · HTML5 · ScummVM · MSX · MSX2 · blueMSX · point-and-click · NES · SNES · Game Boy · GBA · N64 · Nintendo DS · Sega Genesis · Master System · PlayStation · Atari · Atari Jaguar · Apple II · Amstrad CPC · Commodore Amiga · Commodore 64 · Commodore 128 · VIC-20 · ZX Spectrum · ZX81 · Arcade · CPS1 · CPS2 · MAME · FBNeo · DOOM · game preservation · browser emulator · single-file · self-contained · EmulatorJS · RetroArch · WASM · WebAssembly · JavaScript emulator · ROM packer · offline gaming · preservation tools · mobile gaming

🇫🇷 Résumé en Français