A web-based Game Boy (GB), Game Boy Color (GBC), and Game Boy Advance (GBA) emulator built with React, Vite, and mGBA (via WebAssembly). This emulator allows you to load and play .gb, .gbc, .gba, and .zip ROMs directly in your web browser.
- Multi-System Emulation: Powered by the mGBA core for accurate Game Boy (GB), Game Boy Color (GBC), and Game Boy Advance (GBA) emulation.
- Wide Format Support: Load
.gb,.gbc,.gba, and.zipROMs seamlessly. - Speed & Timing Controls: Fast forward speed controls (1x to 5x), frame skipping (0, 1, 2 frames), and auto-mute.
- Advanced Video Shaders: Built-in AMD FSR 2.0, HQ Crisp/Smooth/Vibrant/Soft, Bilinear, and CRT subpixel grid filters.
- Save Management: Support for exporting and importing in-game saves (
.sav) and save states (.ss1) with automatic IndexedDB synchronization. - Touch & Keyboard Controls: On-screen touch overlay for mobile and full keybinding customization for desktop.
Before starting, ensure you have the following installed on your machine:
- Node.js (v18.x or higher recommended)
- npm (v9.x or higher)
Follow these steps to run the application locally:
-
Clone or copy the repository files:
cd mgba-web -
Install the project dependencies:
npm install
-
Start the local development server:
npm run dev
Alternatively, you can run the server directly using:
node node_modules/vite/bin/vite.js --host
-
Open your browser and navigate to:
http://localhost:3000
To test with native Node.js SSL locally (useful for hosting over a local network with HTTPS), generate self-signed certificates in the project root directory:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -sha256 -days 365 -nodesOnce Vite detects key.pem and cert.pem in the project root, it will automatically serve the development server over HTTPS.
To build the static files for production hosting:
npm run buildThis will compile the application and output the static assets into the dist/ directory.
Important
To optimize server space and bundle delivery, the build process is configured to only keep the compressed .gz files for assets (JavaScript, CSS, WebAssembly) and delete the original uncompressed files.
Ensure your web server/hosting provider is configured to support pre-compressed assets. For instance, in Nginx, you must enable gzip_static on; (as shown in the configuration example below).
Since the application compiles into static HTML, CSS, and JS files, it can be hosted on any static hosting provider or virtual machine (VM).
To allow the mGBA emulator core's multithreading and shared memory feature (SharedArrayBuffer) to function, your hosting provider must serve the following HTTP headers:
Cross-Origin-Opener-Policy: same-originCross-Origin-Embedder-Policy: require-corp
If these headers are not present, the emulator will fail to load in the browser.
Upload the contents of the dist/ directory or connect your Git repository. Ensure you configure custom headers in the configuration file of your provider:
- Netlify (
netlify.toml):[[headers]] for = "/*" [headers.values] Cross-Origin-Opener-Policy = "same-origin" Cross-Origin-Embedder-Policy = "require-corp"
- Vercel (
vercel.json):{ "headers": [ { "source": "/(.*)", "headers": [ { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" }, { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" } ] } ] }
If you host on a VM (such as Ubuntu or Windows Server), install Nginx and configure it to point to your build dist/ folder.
Add the headers in your Nginx server configuration block:
server {
listen 80;
listen [::]:80;
server_name your_domain_or_ip;
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name your_domain_or_ip;
ssl_certificate /etc/letsencrypt/live/your_domain_or_ip/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your_domain_or_ip/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
root /path/to/mgba-web/dist;
index index.html;
# Serve pre-compressed static assets (.gz)
gzip_static on;
# Disable caching for HTML files (index.html SPA entry point)
location ~* \.(?:html|htm)$ {
add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;
}
# Cache compiled assets forever because they contain unique hashes
location /assets/ {
expires 1y;
add_header Cache-Control "public, max-age=31536000, immutable";
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;
}
location / {
try_files $uri $uri/ /index.html;
}
# Crucial headers for WebAssembly (SharedArrayBuffer)
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;
}Ensure the paths for certificates and root directory match your setup path.
If you are hosting on a Linux VM, you can obtain a free SSL certificate using Certbot:
- Install Certbot:
- For Ubuntu/Debian:
sudo apt install certbot python3-certbot-nginx -y - For RHEL/Rocky Linux:
sudo dnf install certbot python3-certbot-nginx -y
- For Ubuntu/Debian:
- Run Certbot to generate the certificates and automatically configure Nginx:
sudo certbot --nginx -d your_domain
src/- Contains the React components, styles, and logic.src/components/- Emulator and UI components.src/index.css- Global and layout styling.
public/- Static assets served directly (e.g., favicon.svg).dist/- Production build outputs.
- mGBA: The underlying Game Boy, Game Boy Color, and Game Boy Advance emulator core.
- @thenick775/mgba-wasm: WebAssembly build of mGBA used to run the emulator core in the browser.
- React and Vite: The frontend library and build tool powering the application.
Alliance-Sky
This project is licensed under the MIT License.