BizHawk/README.md

BizHawk

A multi-system emulator written in C#. As well as quality-of-life features for casual players, it also has recording/playback and debugging tools, making it the first choice for TASers (Tool-Assisted Speedrunners).

---

Click the "release" button above to grab the latest stable version (changelog at TASVideos).

New users on Windows should click the "prereqs" button too, see Installing for info.

Never mix different versions of BizHawk — Keep each version in its own folder.

Jump to:

• Installing
  • Windows 7/8.1/10
  • GNU+Linux and macOS
• Building
  • Windows 7/8.1/10
  • GNU+Linux and macOS
• Usage
  • TASing
  • Cores
• Support and troubleshooting
• Contributing
  • Testing
• Related projects
• License

Features and systems

The BizHawk common features (across all cores) are:

• format, region, and integrity detection for game images
• 10 save slots with hotkeys and ∞ named savestates
• speed control, including frame stepping and rewinding
• memory view/search/edit in all emulated hardware components
• input recording (making TAS movies)
• screenshotting and recording audio + video to file
• firmware management
• input, framerate, and more in a HUD over the game
• emulated controllers via a comprehensive input mapper
• Lua control over core and frontend (Windows only)
• hotkey bindings to control the UI

Supported consoles and computers:

• Apple II
• Atari 2600
• Atari 7800
• Atari Lynx
• Commodore 64
• ColecoVision
• Game Boy / Color
• Game Boy Advance
• IntelliVision
• N64
• Neo Geo Pocket / Color
• NES
• PC-FX
• Playstation (PSX)
• Sega Game Gear
• Sega Genesis
• Sega Master System
• Sega Pico
• Sega Saturn
• SNES
• TI-83
• TurboGrafx / SuperGrafx
• Virtual Boy
• WonderSwan / Color
• ZX Spectrum
• More coming soon..?

See the Usage sections below for details about specific tools and config menus.

Installing

Windows 7/8.1/10

Released binaries can be found right here on GitHub:

Click BizHawk-<version>.zip to download it. Also note the changelog, the full version of which is here at TASVideos. Don't mix different versions of BizHawk, keep each version in its own folder.

Before you start (by running EmuHawk.exe), you'll need the following Windows-only prerequisites installed. You can get them all at once with this program.

• .NET Framework 4.6.1
• Visual C++ Redists
  • 2010 SP1
  • 2012
  • 2015
• Direct3D 9

BizHawk functions like a "portable" program, you may move or rename the folder containing EmuHawk.exe, even to another drive — as long as you keep all the files together, and the prerequisites are installed when you go to run it.

Win7 is supported from SP1, Win8 is supported from 8.1, and Win10 is supported from 1709 "Redstone 3", following Microsoft's support lifecycle.

A "backport" release, 1.13.2, is available for Windows XP and 32-bit users. Being in the 1.x series, many bugs remain and features are missing.

GNU+Linux and macOS

Install BizHawk with your distro's package manager. The package name is given on each button below, and some buttons are links. For the changelog, see TASVideos here.

If you run EmuHawkMono.sh from a terminal, note that File > Exit (Alt+F4) doesn't terminate the process correctly, you'll need to send SIGINT (^C). The systems that currently work are: Game Boy + GBC (GBHawk), NES (NesHawk), Master System, Atari 7800, Commodore 64, ColecoVision, IntelliVision, TurboGrafx, and ZX Spectrum. See #1430 for progress.

Is your distro not there? Released binaries can be found right here on GitHub (same download as for Windows):

If you download BizHawk this way, don't mix different versions, keep each version in its own folder. Run EmuHawkMono.sh to give Mono the library and executable paths — you can run it from anywhere, so putting it in a .desktop file is fine. If running the script doesn't start EmuHawk, you may need to edit it (if you use a terminal, it will say so in the output).

Linux distros are supported if the distributor is still supporting your version, you're using Linux 4.4/4.9/4.14/4.19 LTS or 4.20 for x86_64/amd64, and there are no updates available in your package manager. Please update and reboot.

macOS is supported from 10.11 "El Capitan" (Darwin 15.6). Apple doesn't seem to care about lifecycles, so we'll go with 6 months from the last security update.

Building

Windows 7/8.1/10

If you have WSL, Git BASH, or similar, clone the repo with:

git clone https://github.com/TASVideos/BizHawk.git BizHawk_master
# or ssh: git clone git@github.com:TASVideos/BizHawk.git BizHawk_master

...or use a Git GUI. Otherwise, you'll have to download an archive from GitHub.

On Windows 10, open a PowerShell window in BizHawk_master (Shift+Mouse2 in File Explorer) and run C:\Windows\Microsoft.NET\Framework\v4.0.30319\msbuild.exe /p:Configuration=Release BizHawk.sln. TODO: didn't work for me. On older versions, a similar Command Prompt script should work.

The best free C# IDE is VS Community 2017, which you'll need to work on the project efficiently. Open BizHawk.sln with VS to start.

GNU+Linux and macOS

Compiling requires MSBuild and running requires Mono and WINE, but BizHawk does not run under WINE — only the bundled libraries are required.

If you use GNU+Linux, there might be a bizhawk-git package or similar in the same repo as the main package. If it's available, installing it will automate the build process.

Building is as easy as:

git clone https://github.com/TASVideos/BizHawk.git BizHawk_master && cd BizHawk_master
# or ssh: git clone git@github.com:TASVideos/BizHawk.git BizHawk_master && cd BizHawk_master
msbuild /p:Configuration=Release BizHawk.sln

Remove the /p:... flag from MSBuild if you want debugging symbols.

If your distro isn't listed under Installing above, libblip_buf probably isn't in your package repos. You can easily build it yourself.

Once built, see the Installing section, substituting the repo's output folder for the download.

Again, if your distro isn't listed there, you might get an "Unknown distro" warning in the terminal, and BizHawk may not open or may show the missing dependencies dialog. You may need to add your distro to the case statement in the script, setting libpath to the location of d3dx9_43.dll.so (please do share if you get it working).

Usage

TODO

TASing

This section refers to BizHawk specifically. For resources on TASing in general, see Welcome to TASVideos.

TODO

Commandline

CompactDiscInfoDump

Rerecording

TAS movie file format

Cores

A core is what we call the smaller bits of software that emulate just one system or family of systems, e.g. NES/Famicom. For the most part, there's a "best" core for each system, based on accuracy, but there's currently a bit of overlap in the cores BizHawk uses as noted below.

System	Core	Alt. Core	Special Core
Amstrad CPC	CPCHawk†
Apple II	Virtu
Atari 2600	Atari2600Hawk
Atari 7800	A7800Hawk
Atari Lynx	Handy
Commodore 64	C64Hawk
ColecoVision	ColecoHawk
Game Boy / Color	GBHawk	Gambatte	SameBoy (on SNES with SGB)
Game Boy Advance	mGBA/VBA-Next	mGBA/VBA-Next
IntelliVision	IntelliHawk
Magnavox Odyssey²	O2Em†
N64	Mupen64Plus
Neo Geo Pocket / Color	NeoPop		Dual NeoPop (dual instance)
NES	NesHawk	QuickNes
PC-FX	T.S.T.
Playstation (PSX)	Octoshock
PSP	PPSSPP†
Sega Game Gear	SMSHawk
Sega Genesis	Genplus-gx
Sega Master System	SMSHawk
Sega Saturn	Saturnus
Sega Pico	PicoDrive
SNES	BSNES/Snes9x	BSNES/Snes9x
TI-83	TI83Hawk
TurboGrafx / SuperGrafx	PCEHawk
Uzebox	Uzem†
Virtual Boy	Virtual Boyee
WonderSwan / Color	Cygne
ZX Spectrum	ZXHawk

† core is in development and unreleased

Support and troubleshooting

A short FAQ is provided on the BizHawk wiki. If your problem is one of the many not answered there, and you can't find it in the issue tracker search, check the BizHawk forum at TASVideos, or ask on IRC:

If there's no easy solution, what you've got is a bug. Or maybe a feature request. Either way, open a new issue (you'll need a GitHub account, signup is very fast).

Contributing

BizHawk is Open Source Software, so you're free to modify it however you please, and if you do, we invite you to share! Under the MIT license, this is optional, just be careful with reusing cores as some have copyleft licenses.

If you'd like to fix bugs, check the issue tracker here on GitHub:

It's a good idea to check if anyone is already working on an issue by asking on IRC (see Support above).

If you'd like to add a feature, first search the issue tracker for it. If it's a new idea, make your own feature request issue before you start coding.

Past contrbutors to the frontend and custom-built cores are listed here. See a core's docs for its authors.

Testing

Dev builds are automated with AppVeyor, every green checkmark in the commit history is a successful build and clicking the check takes you straight there. The full list is here, in future use the "dev builds" button at the top of this readme.

Once you're on the build page, click "Artifacts" and download BizHawk_Developer-<datetime>-#<long hexadecimal>.zip.

Related projects

• DeSmuME for DS/Lite — cross-platform
• Dolphin for GameCube and (original) Wii — cross-platform
• FCEUX for NES/Famicom — TASing is Windows-only, but it should run on Unix
• libTAS for Linux ELF — GNU+Linux-only, also emulates other emulators
• lsnes for GB and SNES — cross-platform
• openMSX for MSX — cross-platform

License

From the full text:

This repository contains original work chiefly in c# by the BizHawk team (which is all provided under the MIT License), embedded submodules from other authors with their own licenses clearly provided, other embedded submodules from other authors WITHOUT their own licenses clearly provided, customizations by the BizHawk team to many of those submodules (which is provided under the MIT license), and compiled binary executable modules from other authors without their licenses OR their origins clearly indicated.

In short, the frontend is MIT (Expat), beyond that you're on your own.