wasmboy

<!--- Badges -->

<!--- Short Description-->

🎮👾🕹️ Gameboy Emulator Library written in Web Assembly using AssemblyScript, Demos in Preact and Svelte 🎮👾🕹️

Project is still < 1.0.0. Most games are playable, but the emulator is still not very accurate. Expect bugs.

Core/Lib Documentation

Talk given at WebAssembly SF March 28th, 2019

<!-- Header Images -->

<!-- Generated with: https://github.com/ekalinin/github-markdown-toc -->

Table of Contents

• Features
• Usage
  • Supported Platforms
• In-Game Screenshots
  • Gameboy Support
  • Gameboy Color Support
• Demo Applications
  • Debugger
  • Benchmark
  • Iframe Embed
• Tests
  • Blarrg
  • Mooneye
    • Timing
    • Halt
• Contributing
  • Installation
  • CLI Commands / Npm Scripts
• Notable Projects
• Special Thanks
• Resources

Features

• Emulates the Gameboy / Gameboy Color 🎮👾🕹️
• Outputs graphics to a scalable / responsive HTML5 canvas 🖼️, and audio through the Web Audio API 🔊
• Support for In-game saves, and save states 💾
• Configurable options to increase performance for low(er) end devices 🔥
• Importable into other projects as a dependency ♻️
• Built with Web Assembly 🕸️
• Uses Web Workers for parallelized rendering 🛠️
• Keyboard and gamepad input support using responsive gamepad ⌨️ 🎮
• Debugger with a value table (I/O map), Tile Data visualizer, and Background Map with Scroll Indicators 🐛
• Runs in both Browser and Node 🌐

Usage

Project is still < 1.0.0. Most games are playable, but the emulator is still not very accurate. Expect bugs.

1.0 Roadmap Tracking Issue

Simply install through npm:

npm install --save wasmboy

Documentation for the project can be found on the WasmBoy Wiki.

Supported Platforms

Try to test and aim for support on all major browsers (Chrome, Firefox, and Safari). Also, Node support works with the headless option in the WasmBoy config, and using the Worker Threads --experimental-worker flag.

In-Game Screenshots

Gameboy Support

Gameboy Color Support

Demo Applications

Debugger

Application Link

A full debugger meant for analyzing the internals of the gameboy. Great for HomeBrew Gameboy Development, or using as a reference point for building your own GameBoy emulator. See the gif at the top of the README for an example.

Features

• Support of all Gameboy Components: CPU, PPU (Graphics), APU (Audio), Memory, Interrupts, and Timers. 🎮
• Per cycle state of each Game Boy components data, internal registers, and relevant memory addresses. 🌐
• Loaded ROM Information and parsing of the Cartridge Header. 💾
• CPU Control options. Stepping per opcode, and breakpoints. 🧠
• Graphics Background Map, with border for current "camera" location with respect to scroll registers. 🖼️
• Graphics Tile Data, to display the loaded tiles currently loaded across all VRAM Banks. 🎨
• WasmBoy Control options. Play, Pause, Save State, and Load State. ⏯️ 📚
• Ability to log the entire WasmBoy Library Object and Memory to the DevTools Console. 🖥️
• Highly productive "Docker" layout, with snapping of widgets onto sections of the screen and tab support. ⚓
• Saved Layouts between sessions. 💠
• Help widget with tips on how to be effective in the debugger. 🙋

Mobile Demo

For UI/UX reasons, on mobile the debugger is simply a web app for testing the lib. This is useful for testing a ROM on the go. For playing games, I would suggest VaporBoy. Below is an example of the mobile demo:

Anaytics / Privacy

Analytics Wrapper Service

Analytics is used on this application simply for performance monitoring, and tracking popularity of the applications. The following events are sent, with nothing more than the event name. The analytics provider used is Google Analytics.

• Whenever a new ROM is loaded, and played for the first time.
• Whether attempting to load a ROM was successful.
• Whenever a state is saved.
• Whenever a state is loaded.
• Whenever custom WasmBoy options are applied.
• Whenever the Google Drive option is selected.
• Whenever the mobile demo is manually reloaded.

Benchmark

Application Link

Medium Article

Since WasmBoy is built in AssemblyScript, it can also run it's core through the Typescript compiler if we mock out some of the WebAssembly interface. The benchmarking tool was built as a way to compare WebAssembly performance to Javascript / ES6 performance, after compiling the core to both WebAssembly and Javascript. It includes detailed stats, live running output, and multiple graphs. Also great for comparing the performance of devices that run WasmBoy.

Example

Anaytics / Privacy

Analytics is used on this application simply for performance monitoring, and tracking popularity of the application. The following events are sent, with nothing more than the event name. The analytics provider used is Google Analytics.

• Whenever a new ROM is loaded from the particular source.
• Whenever the benchmark is ran.
• Whenever results are rendered for the benchmark.

Iframe Embed

An Iframe embeddable version of WasmBoy. Simply provide information through URL Query Params, and embed a ROM on your website! Great for embedding your HomeBrew Game Boy / Game Boy Color games on your website, (WordPress) blog, and game hosting services such as itch.io.

Example

Example Tobu Tobu Girl, Homebrew Hub Iframe

Usage

Add an iframe to your website like the following:

<iframe title="WasmBoy Iframe Embed" width="160" height="144" allowfullscreen="true" src="https://wasmboy.app/iframe/?[QUERY_PARAMS_GO_HERE]"> </iframe>

The iframe is configured by adding URL Query Params. The configuration params are:

• rom-url - (Required) The URL to the .gb or .gbc ROM that will be loaded, fetched, and played.
• rom-name - The name of the ROM being played.
• play-poster - The URL to the image shown at the intial "click to play", play poster.

Please ensure all assets that are being loaded by the iframe embed, such as ROMs and images, will work with CORS. The WasmBoy Iframe Embed will take the full width and height (100%) of it's iframe container. Thus, it will be up to your styling to ensure the iframe preserves the GameBoy 160x144 resolution.

Anaytics / Privacy

Analytics is used on this application simply for performance monitoring, and tracking popularity of the application. The analytics provider used is Google Analytics. Only basic user visit data is recorded / used.

Tests

These are all currently known passing tests (by me), there may be more test roms out there that pass. Some tests may not pass, and that can either be because of the component it is testing is actually incorrect, or another component that the test is testing is not yet implemented, or is incorrect (e.g a lot of mooneye tests rely on Serial Inter