GB-EMU (WebAssembly Edition) 🎮

A Game Boy (DMG) emulator written from scratch in C++17, specifically compiled for the Web using Emscripten (WebAssembly - WASM).

⚠️ WORK IN PROGRESS: This project is under active development. It is incomplete and intended for educational and testing purposes only.

---

📂 Project Structure

GB-EMU/
├── core/               # Emulator logic (CPU, MMU, Cartridge, Mappers)
├── emc_main.cpp        # Main entry point for the Web version
├── CMakeLists.txt      # Build configuration
├── build.sh            # Automated build helper script
└── roms/               # (Not included) User-provided ROM files

📌 Note: This repository does NOT include ROM files. You must provide your own.

---

⚙️ Configuration (CRITICAL STEP)

Because this project runs inside a browser sandbox, ROMs must be manually injected into Emscripten’s virtual file system at build time.

---

🧱 Step 1: Prepare your ROM

1. Create a folder named roms in the project root (if it doesn’t exist).
2. Place your Game Boy ROM file inside it.

Example:

roms/
└── your_game.gb

---

🗺️ Step 2: Modify CMakeLists.txt (Virtual Path Mapping)

You must tell Emscripten:

• Where the ROMs are located on your real machine
• Where they should appear inside the browser

Open CMakeLists.txt and locate the target_link_options section. Modify the preload line:

"SHELL:--preload-file /YOUR/REAL/PATH/TO/roms@/roms"

Explanation:

• Left side (before @) → Absolute path on your computer Example:

  /home/user/GB-EMU/roms
  

• Right side (after @) → Virtual path inside the browser 👉 Keep this as /roms

---

🎮 Step 3: Modify emc_main.cpp (ROM Loading)

Update the ROM path so it matches the filename inside the virtual file system:

// Change "your_game.gb" to the actual ROM filename
std::string romPath = "roms/your_game.gb";

---

🚀 Build Instructions

🔧 Requirements

• Emscripten SDK (emsdk) installed and activated in your terminal.

---

✅ Option A: Automated Build (Recommended)

The project includes a helper script that:

• Cleans previous builds
• Configures CMake with Emscripten
• Compiles the project
• Optionally launches a local web server

# 1. Give execution permissions (only once)
chmod +x build.sh

# 2. Run the script
./build.sh

At the end of the process, the script will ask whether you want to start the web server automatically.

---

🛠️ Option B: Manual Compilation

If you prefer running each step manually:

# 1. Create a clean build directory
rm -rf build_web
mkdir -p build_web && cd build_web

# 2. Configure with Emscripten
emcmake cmake ..

# 3. Compile
emmake make -j$(nproc)

---

▶️ Running the Emulator

⚠️ Do NOT open the generated HTML file directly. You must use a local web server due to WASM/CORS security restrictions.

---

🔹 Via Script

If you used ./build.sh, simply type:

s + Enter

when prompted.

---

🔹 Manual

Using emrun (Recommended)

emrun --no_browser --port 8888 gb-emu.html

Using Python

python3 -m http.server 8888

---

🌐 Access

Open your browser at:

http://localhost:8888/gb-emu.html

---

🧩 Project Status

• ROM loading via Virtual File System
• Basic emulator architecture
• WebAssembly compilation pipeline
• Complete CPU instruction set — In progress
• PPU (Graphics & Rendering)
• Timers & Interrupts
• Joypad input handling — In progress
• IMBC — In progress
• Users can put their own ROMs in the UI.

---

📚 Project Goals

This project aims to:

• Learn Game Boy (DMG) architecture
• Explore low-level emulation concepts
• Experiment with C++ + WebAssembly
• Build a full emulator from scratch, without external emulation libraries

---

Example

Grabacion.2026-02-09.192647.mp4

💡 Issues, pull requests, and feedback are welcome.

⚖️ Legal Disclaimer

This project is an independent, unofficial emulator developed for educational purposes only.

• This repository does NOT include any copyrighted ROMs, BIOS files, or proprietary assets.
• Users must provide their own legally obtained Game Boy ROMs.
• Any ROM filenames shown in examples (e.g. your_game.gb) are placeholders only.
• This project is not affiliated with, endorsed by, or associated with Nintendo.

All trademarks and registered trademarks are the property of their respective owners.