7d1685f7f5 | ||
---|---|---|
higan | ||
hiro | ||
icarus | ||
libco | ||
nall | ||
ruby | ||
shaders | ||
.gitignore | ||
.gitlab-ci.yml | ||
README.md |
README.md
higan, the multi-system emulator
higan emulates a number of classic videogame consoles of the 1980s and 1990s, allowing you to play classic games on a modern general-purpose computer.
As of v102, higan has top-tier support for the following consoles:
- Nintendo Super Famicom/Super Nintendo Entertainment System,
including addon hardware:
- Super Game Boy
- Sufami Turbo
- Nintendo Game Boy Advance
It also includes some level of support for these consoles:
- BS-X Satellaview addon for the Super Famicom
- Nintendo Famicom/Nintendo Entertainment System
- Nintendo Game Boy
- Nintendo Game Boy Color
- Sega Master System
- Sega Game Gear
- Sega Megadrive/Genesis
- NEC PC Engine/TurboGrafx 16 (but not the CD-ROM² System/TurboGrafx-CD)
- NEC SuperGrafx
- Bandai Wonderswan
- Bandai Wonderswan Color
higan is actively supported on FreeBSD 10 and above, and Microsoft Windows 7 and above. It also includes some level of support for GNU/Linux and macOS.
higan is officially spelled with a lowercase "h", not a capital.
About this document
This is the unofficial higan README, a community-maintained introduction and reference. It may be out of date by the time you read this, and it may contain errors or omissions. If you find something that's wrong, or you have a suggestion, see "Unofficial higan resources" below.
Official higan resources
Unofficial higan resources
- Source code repository archives official higan releases and WIP snapshots since approximately v067r21.
- Quark shader repository collects shaders that higan can use to add special effects like TV scanlines to its video output, or smarter algorithms for scaling up to modern PC resolutions. See Installing custom shaders below for details.
- Mercurial Magic is a tool for converting MSU-1 games and mods into a format higan can use. See Importing MSU-1 games below for details.
There are also other projects based on current or older versions of higan, in whole or in part, that you might want to check out.
- Mednafen is another multi-system emulator. Its SNES emulation is based on bsnes v059, from the time before bsnes was renamed to higan.
- BizHawk is another multi-system emulator, specialising in the creation of tool-assisted speedruns. Its SNES emulation is based on bsnes v087.
- nSide is a fork of higan that greatly enhances its NES emulation support, and adds minor features to the other cores too. It also restores the "balanced" SNES emulation core that was removed from higan in v099, which is less CPU intensive than the current accuracy-focussed core.
- bsnes-plus is a fork of bsnes v073 that adds improved support for debugging SNES software.
Installing and uninstalling higan
The best way to install higan depends on what platform you're using, as well as whether you want to use official binaries or compile the source-code from scratch.
Installing an official release on Windows
Official higan releases are distributed in 7-zip archives. You will need to install 7-zip, or another compatible archiving tool, to install higan.
Once you have a suitable archiving tool, extract the contents of the higan archive into a new directory.
When you're done,
the new directory should contain higan.exe
and icarus.exe
along with other assorted files and directories
that describe the systems higan emulates.
You may put that directory wherever you like.
To run higan, open the higan.exe
file.
Before you can actually play games, you'll need to [import them][#importing-games] and [configure higan][#configuring-higan].
Uninstalling an official release on Windows
Delete the directory containing higan.exe
and the other associated data from the original archive.
To remove higan's configuration:
- Press Win+R to open the Run dialog
- Type
%LOCALAPPDATA%
and press Enter to open the folder where higan's configuration data lives - Delete the subdirectories named
icarus
andhigan
if they exist.
You might also want to remove the games imported into higan's library (including in-game saves and save-states):
- Press Win+R to open the Run dialog
- Type
%USERPROFILE%
and press Enter to open the folder where higan keeps its game library - Delete the subdirectory named
Emulation
if it exists
Compiling from source on Windows
You will need a copy of the higan source-code. If you download an official release from the higan homepage, you will need 7-zip or a compatible tool to extract it. Alternatively, you may obtain higan source code from the unofficial git repo using the Git source-code management tool, or by clicking the download button on the right-hand side of the web-page and choosing an archive format.
You will need a C++ compiler to compile higan. We recommend installing TDM64-GCC, preferably the latest version but anything newer than 4.9 should be fine. higan does not support building with clang++ (Clang is still not quite there yet for Windows) nor Microsoft Visual C++ (last we checked, it didn't support all the C++ features higan uses).
Note: Make sure you get TDM64-GCC, not TDM-GCC. When compiled in x86 (32-bit) mode, higan may crash at startup because gcc targeting x86 does not support Windows' structured exception handling (SEH). Also, historically in x86 mode gcc has miscompiled a part of the NES emulation core. See the higan forum for details.
Once you've installed mingw-w64,
open a command-prompt window,
type g++ --version
then press Enter
to check it's installed correctly.
You should see a message like
g++ 1.2.3 20010101
Copyright (C) 2001 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
...except it should mention the version of mingw that you installed
and the corresponding dates.
If you see an error message like "command not found"
or "bad command or filename",
you may need to add mingw's "bin" directory
to your computer's %PATH%
.
See the mingw documentation for help with that.
Once mingw is installed and available from the command prompt:
- Put the higan source code in some convenient location,
like
C:\higan-src
- Open the command-prompt
- Type
cd C:\higan-src
(or wherever you put the higan source) and press Enter - Type
mingw32-make -C icarus compiler=g++
and press Enter to build the icarus import tool - Type
mingw32-make -C higan compiler=g++
and press Enter to build the main higan executable
Installing a compiled build on Windows
- In Windows Explorer, create the directory where you want higan to live
- Assuming you built higan in
C:\higan-src
, copyC:\higan-src\icarus\out\icarus.exe
into the new directory - Copy
C:\higan-src\icarus\Database
and its contents into the new directory - Copy
C:\higan-src\higan\out\higan.exe
into the new directory - Copy all the
*.sys
directories inC:\higan-src\higan\systems
into the new directory
The new directory should now contain
icarus.exe
,
higan.exe
,
a directory named Database
,
and half a dozen directories named after the systems higan emulates
with .sys
at the end.
This is what you would get by downloading an official build,
as described under
Installing an official release on Windows
above.
Before you can actually play games, you'll need to [import them][#importing-games] and [configure higan][#configuring-higan].
Uninstalling a compiled build on Windows
The process is the same as Uninstalling an official release on Windows above. You may also wish to delete the higan source directory.
Compiling from source on Linux
You will need a copy of the higan source-code. If you download an official release from the higan homepage, you will need 7-zip or a compatible tool to extract it. Alternatively, you may obtain higan source code from the unofficial git repo using the Git source-code management tool, or by clicking the download button on the right-hand side of the web-page and choosing an archive format.
You will also need GCC 4.9 or higher, including the C and C++ compiler, GNU Make, and development files (headers, etc.) for the following libraries:
- GTK 2.x
- PulseAudio
- Mesa
- gtksourceview 2.x
- Cairo
- SDL 1.2
- libXv
- libAO
- OpenAL
- udev
On a Debian-derived Linux distribution, you can install everything you need with a command like:
sudo apt-get install build-essential libgtk2.0-dev libpulse-dev \
mesa-common-dev libgtksourceview2.0-dev libcairo2-dev libsdl1.2-dev \
libxv-dev libao-dev libopenal-dev libudev-dev
Once you have all the dependencies installed:
- Put the higan source code in some convenient location,
like
~/higan-src
- Open a terminal window
- Type
cd ~/higan-src
(or wherever you put the higan source) and press Enter - Type
make -C icarus compiler=g++
and press Enter to build the icarus import tool - Type
make -C higan compiler=g++
and press Enter to build the main higan executable
Installing a compiled build on Linux
Assuming you have successfully compiled higan as described in the previous section:
- Open a terminal window
- Type
cd ~/higan-src
(or wherever you put the higan source) and press Enter - Type
make -C icarus install
and press Enter to install icarus and its game database - Type
make -C higan install
and press Enter to install higan and its supporting files
This installs higan and its associated data files
into the ~/.local
directory hierarchy.
To confirm higan is installed correctly,
type higan
in a terminal and press Enter.
If the higan window appears,
everything is working.
On the other hand,
if you get an error message like "command not found",
you should double-check that the directory ~/.local/bin
is included in your $PATH
environment variable
by running the following command in a terminal:
echo "$PATH" | tr ':' '\n' | grep ~/.local/bin
If the above command prints the full path of ~/.local/bin
(for example: /home/yourname/.local/bin
)
then you should be good.
If it prints nothing,
you need to add the following line to ~/.profile
:
export PATH=~/.local/bin:$PATH
(this line must be in ~/.profile
because
most GUIs do not read any other files at login)
If you also have a ~/.bash_profile
,
make sure it reads the contents of ~/.profile
with a line like this:
source ~/.profile
You will need to log out and log back in
for changes to ~/.profile
or ~/.bash_profile
to take effect.
Before you can actually play games, you'll need to [import them][#importing-games] and [configure higan][#configuring-higan].
Uninstalling a compiled build on Linux
To uninstall higan, as installed by the above instructions:
- Open a terminal window
- Type
cd ~/higan-src
(or wherever you put the higan source) and press Enter - Type
make -C icarus uninstall
and press Enter - Type
make -C higan uninstall
and press Enter
To remove higan's configuration,
delete the directory ~/.config/higan
as well.
To remove the games imported into higan's library
(including in-game saves and save-states),
delete the directory ~/Emulation
.
You may also wish to delete the higan source directory.
Installing the GBA BIOS
Importing games
What's a game folder?
Importing regular games
Importing games with co-processor firmware
Importing BS-X games
Importing Sufami Turbo games
Importing Super Game Boy games
Importing MSU-1 games
Configuring higan
Drivers
Installing custom shaders
Controls
- mapping PC inputs to emulated controllers
- configuring which emulated controllers are connected to the emulated system
Notes on specific emulation cores
The WonderSwan rotates!
Shaders look weird on SNES because of interlace/hi-res
GBA in-game saves are Difficult
PSG volume for the Mega Drive (see https://board.byuu.org/viewtopic.php?p=42158#p42158 for info)
Frequently Asked Questions
where is the vsync option?
exclusive full-screen?
phones and tablets