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 and GIF recording.
32- Remappable controls for both keyboards and gamepads.
33- Loading from ZIP and 7z files.
34- IPS, UPS and BPS patch support.
35- Game debugging via a command-line interface and GDB remote support, compatible with IDA Pro.
36- Configurable emulation rewinding.
37- Support for loading and exporting GameShark and Action Replay snapshots.
38- Cores available for RetroArch/Libretro and OpenEmu.
39- Many, many smaller things.
40
41#### Game Boy mappers
42
43The following mappers are fully supported:
44
45- MBC1
46- MBC1M
47- MBC2
48- MBC3
49- MBC3+RTC
50- MBC5
51- MBC5+Rumble
52- MBC7
53
54The following mappers are partially supported:
55
56- MBC6
57- MMM01
58- Pocket Cam
59- TAMA5
60- HuC-1
61- HuC-3
62
63### Planned features
64
65- Networked multiplayer link cable support.
66- Dolphin/JOY bus link cable support.
67- M4A audio mixing, for higher quality sound than hardware.
68- Re-recording support for tool-assist runs.
69- Lua support for scripting.
70- A comprehensive debug suite.
71- e-Reader support.
72- Wireless adapter support.
73- OpenGL renderer.
74- HLE support for DS BIOS and DS ARM7 processor.
75- Synthesizing a customizable DS firmware to avoid needing a dump.
76
77Supported Platforms
78-------------------
79
80- Windows Vista or newer
81- OS X 10.7 (Lion)[<sup>[4]</sup>](#osxver) or newer
82- Linux
83- FreeBSD
84
85The following platforms are supported for everything except DS:
86
87- Nintendo 3DS
88- Wii
89- PlayStation Vita
90
91Other Unix-like platforms, such as OpenBSD, are known to work as well, but are untested and not fully supported.
92
93### System requirements
94
95Requirements 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.
96
97Downloads
98---------
99
100Downloads can be found on the official website, in the [Downloads][downloads] section. The source code can be found on [GitHub][source].
101
102Controls
103--------
104
105Controls 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:
106
107- **A**: X
108- **B**: Z
109- **L**: A
110- **R**: S
111- **Start**: Enter
112- **Select**: Backspace
113
114DS default controls are slightly different:
115
116- **A**: X
117- **B**: Z
118- **X**: S
119- **Y**: A
120- **L**: Q
121- **R**: W
122- **Start**: Enter
123- **Select**: Backspace
124
125Compiling
126---------
127
128Compiling requires using CMake 2.8.11 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. To use CMake to build on a Unix-based system, the recommended commands are as follows:
129
130 mkdir build
131 cd build
132 cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
133 make
134 sudo make install
135
136This 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.
137
138If 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:
139
140 brew install cmake ffmpeg imagemagick libzip qt5 sdl2 libedit pkg-config
141 mkdir build
142 cd build
143 cmake -DCMAKE_PREFIX_PATH=`brew --prefix qt5` ..
144 make
145
146Note that you should not do a `make install` on macOS, as it will not work properly.
147
148#### Windows developer building
149
150To 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):
151
152For x86 (32 bit) builds:
153
154 pacman -Sy base-devel git mingw-w64-i686-{cmake,ffmpeg,gcc,gdb,imagemagick,libelf,libepoxy,libzip,pkg-config,qt5,SDL2,ntldd-git}
155
156For x86_64 (64 bit) builds:
157
158 pacman -Sy base-devel git mingw-w64-x86_64-{cmake,ffmpeg,gcc,gdb,imagemagick,libelf,libepoxy,libzip,pkg-config,qt5,SDL2,ntldd-git}
159
160Check out the source code by running this command:
161
162 git clone https://github.com/mgba-emu/mgba.git -b medusa medusa
163
164Then finally build it by running these commands:
165
166 cd medusa
167 mkdir build
168 cd build
169 cmake .. -G "MSYS Makefiles"
170 make
171
172Please 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.
173
174### Dependencies
175
176medusa 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.
177
178- Qt 5: for the GUI frontend. Qt Multimedia or SDL are required for audio.
179- SDL: for a more basic frontend and gamepad support in the Qt frontend. SDL 2 is recommended, but 1.2 is supported.
180- zlib and libpng: for screenshot support and savestate-in-PNG support.
181- libedit: for command-line debugger support.
182- ffmpeg or libav: for video recording.
183- libzip or zlib: for loading ROMs stored in zip files.
184- ImageMagick: for GIF recording.
185- SQLite3: for game databases.
186- libelf: for ELF loading.
187
188SQLite3, libpng, and zlib are included with the emulator, so they do not need to be externally compiled first.
189
190Footnotes
191---------
192
193<a name="missing">[1]</a> Currently missing features on GBA are
194
195- OBJ window for modes 3, 4 and 5 ([Bug #5](http://mgba.io/b/5))
196- Mosaic for transformed OBJs ([Bug #9](http://mgba.io/b/9))
197
198Missing features on DS are
199
200- Audio:
201 - Master audio settings
202 - Sound output capture
203 - Microphone
204- Graphics:
205 - Edge marking/wireframe
206 - Highlight shading
207 - Fog
208 - Anti-aliasing
209 - Alpha test
210 - Position test
211 - Vector test
212 - Bitmap rear plane
213 - Large bitmap mode 6
214 - 1-dot depth clipping
215 - Vector matrix memory mapping
216 - Polygon/vertex RAM entry count memory mapping
217 - Rendered line count memory mapping
218 - Horizontal scrolling on 3D background
219 - Some bitmap OBJ mappings
220 - DMA FIFO backgrounds
221- Other:
222 - Cache emulation/estimation
223 - Slot-2 access/RAM/rumble
224 - BIOS protection
225 - Display start DMAs
226 - Most of Wi-Fi
227 - RTC interrupts
228 - Manual IPC sync IRQs
229 - Lid switch
230 - Power management
231 - Touchscreen temperature/pressure support
232 - Various MMIO registers
233 - DSi cart protections
234
235<a name="dscaveat">[2]</a> Many feature are still missing on the DS, including savestates, cheats, rumble, HLE BIOS, and more.
236
237<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.
238
239<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.
240
241[downloads]: http://mgba.io/downloads.html
242[source]: https://github.com/mgba-emu/mgba/
243
244Copyright
245---------
246
247medusa is Copyright © 2013 – 2019 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.
248
249medusa contains the following third-party libraries:
250
251- [inih](https://github.com/benhoyt/inih), which is copyright © 2009 Ben Hoyt and used under a BSD 3-clause license.
252- [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.
253- [LZMA SDK](http://www.7-zip.org/sdk.html), which is public domain.
254- [MurmurHash3](https://github.com/aappleby/smhasher) implementation by Austin Appleby, which is public domain.
255- [getopt for MSVC](https://github.com/skandhurkat/Getopt-for-Visual-Studio/), which is public domain.
256- [SQLite3](https://www.sqlite.org), which is public domain.
257
258If 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.