Game Boy / Game Boy Color Emulator written for Web Assembly using AssemblyScript. ๐Ÿš€Shell/Debugger in Preact. โš›๏ธ
Clone or download
torch2424 Minimal Serial Implementation & Coincidence Fix (#229)
Shout out to @binji for the help! ๐ŸŽ‰ ๐Ÿ˜„ 

This gets a minimal serial implementation to get more games working (AlleyWay), and fixes the LYC Coincidence at LY 153 for Perhistorik man ๐Ÿ˜„ 

<img width="866" alt="screen shot 2019-01-13 at 12 54 10 am" src="https://user-images.githubusercontent.com/1448289/51083386-4ba9bd00-16ce-11e9-9cf6-6539c527e18d.png">

![alleywayserial](https://user-images.githubusercontent.com/1448289/51083388-52383480-16ce-11e9-935e-919dc7196aed.gif)
Latest commit 8a11d05 Jan 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
core Minimal Serial Implementation & Coincidence Fix (#229) Jan 13, 2019
demo Minimal Serial Implementation & Coincidence Fix (#229) Jan 13, 2019
dist/core Minimal Serial Implementation & Coincidence Fix (#229) Jan 13, 2019
docs Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
lib Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
test 1.0 phase 2 (#201) Nov 19, 2018
.gitattributes 1.0 phase 1 (#200) Nov 15, 2018
.gitignore Started working on a fix for mirrored tiles in tile rendering and cacโ€ฆ Apr 17, 2018
.prettierrc Added a prettierrc May 1, 2018
.travis.yml Fixed Sound for TS Builds, and FireFox JS Benchmarking (#218) Dec 22, 2018
LICENSE Initial commit Jan 24, 2018
README.md Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
package-lock.json Minimal Serial Implementation & Coincidence Fix (#229) Jan 13, 2019
package.json Minimal Serial Implementation & Coincidence Fix (#229) Jan 13, 2019
rollup.amp.js Open Sourced WasmBoy Amp-script Demo / Experiment (#202) Dec 2, 2018
rollup.benchmark.js Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
rollup.config.js Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
rollup.core.js Added support for esnext TS Core output Dec 2, 2018
rollup.debugger.js Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
rollup.getcore.js Finished up the benchmarking app (#205) Dec 3, 2018
rollup.lib.js Rebuilt WasmBoy Debugger on top of PhosphorJS (#228) Jan 10, 2019
rollup.worker.js ๐Ÿ”ฅCompiled WasmBoy using the Typescript Compiler, Built a Cool Benchmaโ€ฆ Nov 4, 2018

README.md

wasmboy

Build Status npm version npm bundle size (minified) npm GitHub

๐ŸŽฎ๐Ÿ‘พ๐Ÿ•น๏ธ Gameboy Emulator Library written in Web Assembly using AssemblyScript, Debugger/Shell in Preact ๐ŸŽฎ๐Ÿ‘พ๐Ÿ•น๏ธ

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

Core/Lib Documentation

Pokemon Crystal Wasmboy Debugger Demo

Table of Contents

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

Is that a demo in your pocket Megaman 2 Pokemon Blue tetris tobu tobu girl

Gameboy Color Support

Links Awakening L s d j Megaman extreme 2 Pokemon Silver Pokemon Yellow back to color demo

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. ๐Ÿ™‹

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.

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:

Pokemon Crystal Wasmboy Mobile Demo

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.

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.

Example

WasmBoy Benchmark Runner Section on Safari

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 Interrupts, which this emulator has yet to implement). Feel free to open an issue or PR to add any more passing tests to this list ๐Ÿ˜„ . The test names are listed from left to right, top to bottom.

Blarrg

Repo with all blargg's tests and source

cpu_instrs, instr_timing, mem_timing, mem_timing-2, halt_bug

Cpu Instructions all tests passing Instruction timing all tests passing Memory timing all tests passing Memory timing 2 all tests passing halt bug all tests passing

Mooneye

Mooneye GB Emulator / Tests

Timing

div_write, rapid_toggle, tim00, tim00_div_trigger, tim01, tim01_div_trigger, tim10, tim10_div_trigger, tim11, tim11_div_trigger, tima_reload, tima_write_reloading, tma_write_reloading

div write test passing rapid toggle test passing tim00 test passing tim00 div trigger test passing tim01 test passing tim01 div trigger test passing tim10 test passing tim10 div trigger test passing tim11 test passing tim11 div trigger test passing tima reload test passing tima write reloading test passing tma write reloading test passing

Halt

halt_ime0_ei, halt_ime0_nointr_timing, halt_ime1_timing

halt_ime0_ei test passing halt_ime0_nointr_timing test passing halt_ime1_timing test passing

Contributing

Feel free to fork and submit PRs! Opening an issue is reccomended before starting any development, as a discussion would be nice on the idea / feature before writing code. Any help is much appreciated, and would be a ton of fun!

Installation

Just your standard node app. Install Node with nvm, git clone the project, and npm install, and you should be good to go!

CLI Commands / Npm Scripts

The project contains three different elements.

  • The core or wasm which is the web assembly module for wasmboy written in AssemblyScript.
  • The lib which is the importable library of wasmboy that can be used in other projects, that adds a top level API to the core.
  • The demo, which is a collection of different apps that are used for demoing purposes of the lib and core.

Most of the build process in this project is done using Rollup.js. Each element / component of the project is configured in its own rollup.*.js file, and are then all used within the standard rollup.config.js file by the rollup CLI. Also, The core wasm uses the AssemblyScript compiler CLI tool.

Commands for each part of the project will be prepended with their element name and a colon, e.g debugger:[command here].

Common command parts are:

  • dev / watch - How the project should be served and developed with tools like reloading.
  • build - Make production builds of the component / element of the project.

Commands not prepended with a colon are meant for easily building on all of the different parts as a whole.

Not all commands are documented, only ones relevant to making changes to the library for contributions. * represents the category of commands, and is not an actual command.

# Command to serve the project, and watch the debugger, wasm, and lib for changes
# Uses concurrently: https://github.com/kimmobrunfeldt/concurrently
# Concurrently helps cleanup the output and organizes watchers on commands that require concurrent tools

# Serve the general project for development (Watches the core, lib, and debugger)
npm run start

# Same as npm start
npm run dev

# Same as npm start
npm run watch

# Build everything to be ready to be pushed to npm or released
npm run build

# Linting commands used during precommit an tests
npm run prettier:*

# Commands for building/serving the core, offers commands for building with the Assemblyscript Compiler (WASM) or Typescript (JS)
npm run core:*

# Commands for building/serving the JS lib
npm run lib:*

# Run tests in `test/accuracy/test.js`
npm run test

# Run tests in `test/performance/test.js`
npm run test:performance

# All commands for testing, and are test related
npm run test:*

# Commands for the building / serving the debugger
npm run debugger:*

# Commands for building / serving the benchmark tool
npm run benchmark:*

# Commands for building / serving all available apps in wasmboy
npm run demo:*

Using the gh-pages for debugger/demo deployment onto gh-pages.

Notable Projects

  • VaporBoy - PWA for playing ROMs with WasmBoy!

  • wasmboy-rs - Wasmboy Compiled to Rust, for native executables and additional cool features!

  • wasmboy.py - Wasmboy running in Python!

Special Thanks

Resources