README.md (view raw)
1medusa
2======
3
4medusa is an emulator for running Nintendo DS, Game Boy Advance and Game Boy games. It aims to be faster and more accurate than many existing Nintendo DS and Game Boy Advance emulators, as well as adding features that other emulators lack. It also supports Game Boy and Game Boy Color games.
5
6Up-to-date news and downloads can be found at [mgba.io](https://mgba.io/).
7
8[](https://travis-ci.org/mgba-emu/mgba)
9
10Features
11--------
12
13- Highly accurate Game Boy Advance hardware support[<sup>[1]</sup>](#missing).
14- Partial DS hardware support[<sup>[1]</sup>](#missing).
15- Game Boy/Game Boy Color hardware support.
16- Fast emulation for Game Boy and Game Boy Advance. Known to run at full speed even on low end hardware, such as netbooks[<sup>[2]</sup>](#dscaveat).
17- Qt and SDL ports for a heavy-weight and a light-weight frontend.
18- Local (same computer) link cable support.
19- Save type detection, even for flash memory size[<sup>[3]</sup>](#flashdetect).
20- Support for cartridges with motion sensors and rumble (only usable with game controllers)[<sup>[2]</sup>](#dscaveat).
21- Real-time clock support, even without configuration.
22- Solar sensor support for Boktai games.
23- Game Boy Camera and Game Boy Printer support.
24- A built-in GBA BIOS implementation, and ability to load external BIOS files. DS currently requires BIOS and firmware dumps[<sup>[2]</sup>](#dscaveat).
25- Turbo/fast-forward support by holding Tab.
26- Rewind by holding Backquote.
27- Frameskip, configurable up to 10.
28- Screenshot support.
29- Cheat code support[<sup>[2]</sup>](#dscaveat).
30- 9 savestate slots. Savestates are also viewable as screenshots[<sup>[2]</sup>](#dscaveat).
31- Video, GIF, WebP, and APNG recording.
32- e-Reader support.
33- Remappable controls for both keyboards and gamepads.
34- Loading from ZIP and 7z files.
35- IPS, UPS and BPS patch support.
36- Game debugging via a command-line interface and GDB remote support, compatible with IDA Pro.
37- Configurable emulation rewinding.
38- Support for loading and exporting GameShark and Action Replay snapshots.
39- Cores available for RetroArch/Libretro and OpenEmu.
40- Many, many smaller things.
41
42#### Game Boy mappers
43
44The following mappers are fully supported:
45
46- MBC1
47- MBC1M
48- MBC2
49- MBC3
50- MBC3+RTC
51- MBC5
52- MBC5+Rumble
53- MBC7
54- Wisdom Tree (unlicensed)
55- Pokémon Jade/Diamond (unlicensed)
56
57The following mappers are partially supported:
58
59- MBC6
60- MMM01
61- Pocket Cam
62- TAMA5
63- HuC-1
64- HuC-3
65
66### Planned features
67
68- Networked multiplayer link cable support.
69- Dolphin/JOY bus link cable support.
70- M4A audio mixing, for higher quality sound than hardware.
71- Re-recording support for tool-assist runs.
72- Lua support for scripting.
73- A comprehensive debug suite.
74- Wireless adapter support.
75- OpenGL renderer.
76- HLE support for DS BIOS and DS ARM7 processor.
77- Synthesizing a customizable DS firmware to avoid needing a dump.
78
79Supported Platforms
80-------------------
81
82- Windows Vista or newer
83- OS X 10.7 (Lion)[<sup>[4]</sup>](#osxver) or newer
84- Linux
85- FreeBSD
86
87The following platforms are supported for everything except DS:
88
89- Nintendo 3DS
90- Wii
91- PlayStation Vita
92
93Other Unix-like platforms, such as OpenBSD, are known to work as well, but are untested and not fully supported.
94
95### System requirements
96
97Requirements are minimal[<sup>[2]</sup>](#dscaveat). Any computer that can run Windows Vista or newer should be able to handle emulation. Support for OpenGL 1.1 or newer is also required, with OpenGL 3.2 or newer for shaders and advanced features.
98
99Downloads
100---------
101
102Downloads can be found on the official website, in the [Downloads][downloads] section. The source code can be found on [GitHub][source].
103
104Controls
105--------
106
107Controls are configurable in the settings menu. Many game controllers should be automatically mapped by default. The default keyboard controls are as follows for GB and GBA:
108
109- **A**: X
110- **B**: Z
111- **L**: A
112- **R**: S
113- **Start**: Enter
114- **Select**: Backspace
115
116DS default controls are slightly different:
117
118- **A**: X
119- **B**: Z
120- **X**: S
121- **Y**: A
122- **L**: Q
123- **R**: W
124- **Start**: Enter
125- **Select**: Backspace
126
127Compiling
128---------
129
130Compiling requires using CMake 3.1 or newer. GCC and Clang are both known to work to compile medusa, but Visual Studio 2013 and older are known not to work. Support for Visual Studio 2015 and newer is coming soon.
131
132#### Docker building
133
134The recommended way to build for most platforms is to use Docker. Several Docker images are provided that contain the requisite toolchain and dependencies for building mGBA across several platforms.
135
136To use a Docker image to build mGBA, simply run the following command while in the root of an mGBA checkout:
137
138 docker run --rm -t -v $PWD:/home/mgba/src mgba/windows:w32
139
140This will produce a `build-win32` directory with the build products. Replace `mgba/windows:w32` with another Docker image for other platforms, which will produce a corresponding other directory. The following Docker images available on Docker Hub:
141
142- mgba/3ds
143- mgba/switch
144- mgba/ubuntu:xenial
145- mgba/ubuntu:bionic
146- mgba/ubuntu:cosmic
147- mgba/ubuntu:disco
148- mgba/ubuntu:eoan
149- mgba/ubuntu:focal
150- mgba/vita
151- mgba/wii
152- mgba/windows:w32
153- mgba/windows:w64
154
155#### *nix building
156
157To use CMake to build on a Unix-based system, the recommended commands are as follows:
158
159 mkdir build
160 cd build
161 cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
162 make
163 sudo make install
164
165This will build and install medusa into `/usr/bin` and `/usr/lib`. Dependencies that are installed will be automatically detected, and features that are disabled if the dependencies are not found will be shown after running the `cmake` command after warnings about being unable to find them.
166
167If you are on macOS, the steps are a little different. Assuming you are using the homebrew package manager, the recommended commands to obtain the dependencies and build are:
168
169 brew install cmake ffmpeg libzip qt5 sdl2 libedit pkg-config
170 mkdir build
171 cd build
172 cmake -DCMAKE_PREFIX_PATH=`brew --prefix qt5` ..
173 make
174
175Note that you should not do a `make install` on macOS, as it will not work properly.
176
177#### Windows developer building
178
179##### MSYS2
180
181To build on Windows for development, using MSYS2 is recommended. Follow the installation steps found on their [website](https://msys2.github.io). Make sure you're running the 32-bit version ("MSYS2 MinGW 32-bit") (or the 64-bit version "MSYS2 MinGW 64-bit" if you want to build for x86_64) and run this additional command (including the braces) to install the needed dependencies (please note that this involves downloading over 1100MiB of packages, so it will take a long time):
182
183For x86 (32 bit) builds:
184
185 pacman -Sy --needed base-devel git mingw-w64-i686-{cmake,ffmpeg,gcc,gdb,libelf,libepoxy,libzip,pkg-config,qt5,SDL2,ntldd-git}
186
187For x86_64 (64 bit) builds:
188
189 pacman -Sy --needed base-devel git mingw-w64-x86_64-{cmake,ffmpeg,gcc,gdb,libelf,libepoxy,libzip,pkg-config,qt5,SDL2,ntldd-git}
190
191Check out the source code by running this command:
192
193 git clone https://github.com/mgba-emu/mgba.git -b medusa medusa
194
195Then finally build it by running these commands:
196
197 cd medusa
198 mkdir build
199 cd build
200 cmake .. -G "MSYS Makefiles"
201 make
202
203Please note that this build of medusa for Windows is not suitable for distribution, due to the scattering of DLLs it needs to run, but is perfect for development. However, if distributing such a build is desired (e.g. for testing on machines that don't have the MSYS2 environment installed), running `cpack -G ZIP` will prepare a zip file with all of the necessary DLLs.
204
205##### Visual Studio
206
207To build using Visual Studio is a similarly complicated setup. To begin you will need to install [vcpkg](https://github.com/Microsoft/vcpkg). After installing vcpkg you will need to install several additional packages:
208
209 vcpkg install ffmpeg[vpx,x264] libepoxy libpng libzip sdl2 sqlite3
210
211Note that this installation won't support hardware accelerated video encoding on Nvidia hardware. If you care about this, you'll need to install CUDA beforehand, and then substitute `ffmpeg[vpx,x264,nvcodec]` into the previous command.
212
213You will also need to install Qt. Unfortunately due to Qt being owned and run by an ailing company as opposed to a reasonable organization there is no longer an offline open source edition installer for the latest version, so you'll need to either fall back to an [old version installer](https://download.qt.io/official_releases/qt/5.12/5.12.9/qt-opensource-windows-x86-5.12.9.exe) (which wants you to create an otherwise-useless account, but you can bypass temporarily setting an invalid proxy or otherwise disabling networking), use the online installer (which requires an account regardless), or use vcpkg to build it (slowly). None of these are great options. For the installer you'll want to install the applicable MSVC versions. Note that the offline installers do not support MSVC 2019. For vcpkg you'll want to install it as such, which will take quite a while, especially on quad core or less computers:
214
215 vcpkg install qt5-base qt5-multimedia
216
217Next, open Visual Studio, select Clone Repository, and enter `https://github.com/mgba-emu/mgba.git`. When Visual Studio is done cloning, go to File > CMake and open the CMakeLists.txt file at the root of the checked out repository. From there, mGBA can be developed in Visual Studio similarly to other Visual Studio CMake projects.
218
219#### Toolchain building
220
221If you have devkitARM (for 3DS), devkitPPC (for Wii), devkitA64 (for Switch), or vitasdk (for PS Vita), you can use the following commands for building:
222
223 mkdir build
224 cd build
225 cmake -DCMAKE_TOOLCHAIN_FILE=../src/platform/3ds/CMakeToolchain.txt ..
226 make
227
228Replace the `-DCMAKE_TOOLCHAIN_FILE` parameter for the following platforms:
229
230- 3DS: `../src/platform/3ds/CMakeToolchain.txt`
231- Switch: `../src/platform/switch/CMakeToolchain.txt`
232- Vita: `../src/platform/psp2/CMakeToolchain.vitasdk`
233- Wii: `../src/platform/wii/CMakeToolchain.txt`
234
235### Dependencies
236
237medusa has no hard dependencies, however, the following optional dependencies are required for specific features. The features will be disabled if the dependencies can't be found.
238
239- Qt 5: for the GUI frontend. Qt Multimedia or SDL are required for audio.
240- SDL: for a more basic frontend and gamepad support in the Qt frontend. SDL 2 is recommended, but 1.2 is supported.
241- zlib and libpng: for screenshot support and savestate-in-PNG support.
242- libedit: for command-line debugger support.
243- ffmpeg or libav: for video, GIF, WebP, and APNG recording.
244- libzip or zlib: for loading ROMs stored in zip files.
245- SQLite3: for game databases.
246- libelf: for ELF loading.
247
248SQLite3, libpng, and zlib are included with the emulator, so they do not need to be externally compiled first.
249
250Footnotes
251---------
252
253<a name="missing">[1]</a> Currently missing features on GBA are
254
255- OBJ window for modes 3, 4 and 5 ([Bug #5](http://mgba.io/b/5))
256
257Missing features on DS are
258
259- Audio:
260 - Master audio settings
261 - Sound output capture
262 - Microphone
263- Graphics:
264 - Edge marking/wireframe
265 - Highlight shading
266 - Fog
267 - Anti-aliasing
268 - Alpha test
269 - Position test
270 - Vector test
271 - Bitmap rear plane
272 - Large bitmap mode 6
273 - 1-dot depth clipping
274 - Vector matrix memory mapping
275 - Polygon/vertex RAM entry count memory mapping
276 - Rendered line count memory mapping
277 - Horizontal scrolling on 3D background
278 - Some bitmap OBJ mappings
279 - DMA FIFO backgrounds
280- Other:
281 - Cache emulation/estimation
282 - Slot-2 access/RAM/rumble
283 - BIOS protection
284 - Display start DMAs
285 - Most of Wi-Fi
286 - RTC interrupts
287 - Manual IPC sync IRQs
288 - Lid switch
289 - Power management
290 - Touchscreen temperature/pressure support
291 - Various MMIO registers
292 - DSi cart protections
293
294<a name="dscaveat">[2]</a> Many feature are still missing on the DS, including savestates, cheats, rumble, HLE BIOS, and more.
295
296<a name="flashdetect">[3]</a> Flash memory size detection does not work in some cases. These can be configured at runtime, but filing a bug is recommended if such a case is encountered.
297
298<a name="osxver">[3]</a> 10.7 is only needed for the Qt port. The SDL port is known to work on 10.5, and may work on older.
299
300[downloads]: http://mgba.io/downloads.html
301[source]: https://github.com/mgba-emu/mgba/
302
303Copyright
304---------
305
306medusa is Copyright © 2013 – 2020 Jeffrey Pfau. It is distributed under the [Mozilla Public License version 2.0](https://www.mozilla.org/MPL/2.0/). A copy of the license is available in the distributed LICENSE file.
307
308medusa contains the following third-party libraries:
309
310- [inih](https://github.com/benhoyt/inih), which is copyright © 2009 – 2020 Ben Hoyt and used under a BSD 3-clause license.
311- [blip-buf](https://code.google.com/archive/p/blip-buf), which is copyright © 2003 – 2009 Shay Green and used under a Lesser GNU Public License.
312- [LZMA SDK](http://www.7-zip.org/sdk.html), which is public domain.
313- [MurmurHash3](https://github.com/aappleby/smhasher) implementation by Austin Appleby, which is public domain.
314- [getopt for MSVC](https://github.com/skandhurkat/Getopt-for-Visual-Studio/), which is public domain.
315- [SQLite3](https://www.sqlite.org), which is public domain.
316
317If you are a game publisher and wish to license medusa for commercial usage, please email [licensing@mgba.io](mailto:licensing@mgba.io) for more information.