sodcalculator

10 Tech How-To

WebAssembly & WebGL: Wii Games in Browser

Guide 10-47832 · Updated · Step by step

This guide explains how WebAssembly and WebGL work together to make Wii games playable in a browser. You’ll learn the core concepts—from emulation and graphics translation to audio and input handling—and get a practical step-by-step process for setting up a browser-based Wii emulator. No prior experience with emulation is required, but basic familiarity with JavaScript and web development will help.

What You’ll Need

  • A modern web browser (Chrome, Firefox, Edge, or Safari) with WebAssembly and WebGL support.
  • A text editor or IDE for writing code.
  • Basic knowledge of JavaScript, HTML, and CSS.
  • Familiarity with the command line (for installing dependencies).
  • A legal copy of a Wii game ROM (you must own the game).
  • Optional: A gamepad for better input handling.

Step-by-Step

  1. Understand the architecture. A Wii emulator (like Dolphin) is written in C++. To run it in a browser, you compile it to WebAssembly (Wasm) using Emscripten. WebAssembly runs at near-native speed in the browser. WebGL is used to render the Wii’s graphics (which are based on the ATI Hollywood GPU) by translating the emulator’s OpenGL calls to WebGL.
  2. Set up your development environment. Install Emscripten SDK. On Linux/macOS, run git clone https://github.com/emscripten-core/emsdk.git, then cd emsdk, ./emsdk install latest, ./emsdk activate latest, and source ./emsdk_env.sh. On Windows, use the emsdk PowerShell commands.
  3. Get the emulator source code. Clone the Dolphin emulator repository: git clone https://github.com/dolphin-emu/dolphin.git. Note that Dolphin is a complex project; for a simpler starting point, consider a lighter emulator like wii-js (a JavaScript-based Wii emulator) or dolphin-emu-wasm (a community fork).
  4. Configure the build for WebAssembly. Create a build directory and run CMake with Emscripten. For Dolphin, you’ll need to disable certain features that don’t work in a browser (like JIT compilation, which is replaced by Wasm’s native execution). Example: emcmake cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_HEADLESS=ON -DENABLE_QT=OFF.
  5. Compile to WebAssembly. Run emmake make -j4. This will produce a .wasm file and a JavaScript glue file. The build may take a while and require tweaking flags to reduce memory usage.
  6. Set up the HTML shell. Create an HTML page that loads the generated JavaScript and WebAssembly. Include a canvas element for WebGL rendering. Emscripten provides a template; you can customize it.
  7. Initialize WebGL. In your JavaScript, get the WebGL context from the canvas: const canvas = document.getElementById('canvas'); const gl = canvas.getContext('webgl2');. The emulator will use this context for rendering.
  8. Load the Wii ROM. Add a file input or drag-and-drop area. Read the ROM file as an ArrayBuffer and pass it to the emulator’s memory. In Dolphin, you’d call a function like Dolphin.loadROM(buffer).
  9. Handle input. Map keyboard and gamepad events to Wii Remote buttons. Use the Gamepad API to read controller input. For example, the A button on the Wii Remote maps to a key or gamepad button.
  10. Manage audio. The Wii uses 5.1 surround sound. In the browser, you can use the Web Audio API to create an AudioContext and feed the emulator’s audio output. Emscripten can handle this via SDL or OpenAL, but you may need to write custom glue code.
  11. Test and debug. Run a local server (e.g., python -m http.server) and open the page. Check the browser console for errors. Use the browser’s performance tools to monitor frame rate and memory usage.
  12. Optimize performance. Reduce the internal resolution of the emulator to improve speed. Use WebGL2 for better shader support. Consider using SharedArrayBuffer for multi-threading (requires cross-origin isolation headers).

Common Mistakes

  • Not setting cross-origin isolation. If you use threads or SharedArrayBuffer, you must send headers Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Without them, the emulator may crash.
  • Ignoring WebGL context loss. The browser can lose the WebGL context (e.g., when switching tabs). You must handle the webglcontextlost event and prevent default to allow restoration.
  • Using too much memory. Wii games can use up to 1GB of RAM. Browsers have memory limits; you may need to reduce the emulator’s cache or use a lower resolution.
  • Forgetting to load the ROM correctly. The ROM must be in a format the emulator supports (ISO or WBFS). Also, the file must be loaded as a binary ArrayBuffer, not as a text string.
  • Assuming all games work. Many Wii games have compatibility issues. Check the Dolphin compatibility list for known issues.

Tips

  • Start with a simple homebrew game or a tech demo before trying a full commercial game.
  • Use the --preload-file option in Emscripten to preload game files into the virtual filesystem.
  • Enable hardware acceleration in your browser settings for better WebGL performance.
  • For input, use the navigator.getGamepads() API and poll in a requestAnimationFrame loop.
  • Profile with Chrome DevTools’ Performance tab to find bottlenecks.

Troubleshooting

If the emulator doesn’t start: Check the console for errors. Common issues include missing WebAssembly support (update your browser), incorrect MIME types for .wasm files (ensure your server serves application/wasm), or a CORS error (use a local server).

If the game runs slowly: Reduce the internal resolution (e.g., from 1080p to 480p), disable anti-aliasing, and close other browser tabs. Also, try disabling audio emulation temporarily, as it can be CPU-intensive.

If the graphics are glitchy: Update your graphics drivers. In the emulator settings, try switching between OpenGL and Vulkan backends (if supported). Also, ensure WebGL is not blocked by your browser’s hardware acceleration settings.

If the game crashes: This often happens due to memory limits. Try a smaller ROM or reduce the emulator’s cache size. Also, check if the game is listed as ‘playable’ on the compatibility list.

If audio is distorted: Increase the audio buffer size in the emulator settings. If using Web Audio API, ensure the AudioContext is resumed after user interaction (browsers block autoplay).

Frequently Asked Questions

Is it legal to play Wii games in a browser?

It’s legal only if you own a physical copy of the game and are using the ROM for personal backup. Downloading ROMs from the internet is copyright infringement.

Do I need a powerful computer?

Yes, Wii emulation is demanding. A mid-range CPU with at least 4 cores and a GPU that supports WebGL2 is recommended. Browsers add overhead, so you may need a faster machine than for native emulation.

Can I use a real Wii Remote?

Yes, but it requires Bluetooth. You can use the Web Bluetooth API to connect a Wii Remote, though support is limited. A standard gamepad is easier and works well.

Why does the game say ‘Cannot read disc’?

This usually means the ROM file is corrupted or not in a supported format. Re-dump your game using a tool like CleanRip, and ensure the file extension is .iso or .wbfs.

Can I play GameCube games too?

Yes, Dolphin supports GameCube games. The process is the same, but you’ll need GameCube ROMs (which are smaller, around 1.4GB).

How can I save my progress?

The emulator creates save files in the browser’s IndexedDB. You can export them by downloading the save file from the emulator’s menu, and import them later.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →