README for CrabEmu 0.2.0:
What is CrabEmu?
----------------
CrabEmu is a Sega Master System, Sega Game Gear, SG-1000, ColecoVision, and NES
emulator for Mac OS X (10.3 and newer), Linux/BSD/etc., and Sega Dreamcast.
Note that CrabEmu focuses mainly on the first few consoles up there (the Sega
ones). ColecoVision support seems to work pretty well, but NES support is
nowhere near complete.
How to I use CrabEmu?
---------------------
Controls in CrabEmu are mapped to the following keys on the keyboard
(on Mac OS X and Linux):
Master System Button Player 1 Player 2
1 (Start) ; v
2 ' b
Up Up Arrow w
Down Down Arrow s
Left Left Arrow a
Right Right Arrow d
Game Gear Start p
ColecoVision Button Player 1 Player 2
Up w Up Arrow
Down s Down Arrow
Left a Left Arrow
Right d Right Arrow
Left Action q -
Right Action e =
1 4 8
2 5 9
3 6 0
4 r i
5 t o
6 y p
7 f k
8 g l
9 h ;
* v ,
0 b .
# n /
NES Button Player 1 Player 2
A ' b
B ; v
Up Up Arrow w
Down Down Arrow s
Left Left Arrow a
Right Right Arrow d
Start p e
Select o q
Note that all keys can be changed in the preferences dialog. As of CrabEmu
0.2.0, the key configured as the Game Gear Start button also acts as the SMS'
Pause button, consistent with how things work on the Dreamcast port (and on an
actual Game Gear when playing a SMS game).
Also, beginning with CrabEmu 0.1.8, the Terebi Oekaki drawing board is also
supported (Mac/Linux only, at the moment). It is controlled with the mouse. Hold
the left mouse button to actually draw anything.
Here's how controls are mapped on the Dreamcast version (these are not able to
be changed, for now):
Master System Button Controller Button
1 (Start) A
2 B
Up DPad Up
Down DPad Down
Left DPad Left
Right DPad Right
Game Gear Start Start
ColecoVision Button Controller Button
Up Joystick Up
Down Joystick Down
Left Joystick Left
Right Joystick Right
Left Action A
Right Action B
1 X
2 Y
3 DPad Up
4 DPad Down
5 DPad Left
6 DPad Right
7 Left Trigger + A
8 Left Trigger + B
9 Left Trigger + DPad Up
* Left Trigger + DPad Down
0 Left Trigger + DPad Left
# Left Trigger + DPad Right
NES Button Controller Button
A B
B A
Up DPad Up
Down DPad Down
Left DPad Left
Right DPad Right
Start Start
Select Y
In Menu:
Move Up one Rom DPad Up
Move Down one Rom DPad Down
Move Up a page of Roms DPad Left
Move Down a page of Roms DPad Right
Start Rom A
Start Rom (stretched graphics) Left Trigger + A
Miscellaneous:
Return to Menu Left Trigger + Y
Save SRAM (to VMU in slot A1) Right Trigger + Y
Enable Cheats Right Trigger + X
Save State (to VMU in slot A1) Right Trigger + A
Load State (from A1) Right Trigger + B
How do I make a CrabEmu disc (for Dreamcast)?
---------------------------------------------
Well, to make a disc for CrabEmu, you need all the files in the Dreamcast binary
package that you downloaded. The 1ST_READ.BIN file is already scrambled. To
actually build the disc, use your favorite method of selfbooting and make sure
that you end up with a crabemu directory in the root of the CD. Also, all of
your roms should go in the crabemu/roms directory (other than BIOSes). The BIOS
files can be either the ones provided with CrabEmu or practically any other
appropriate (SMS or GG) BIOS images (they still need to be named bios)
Note, you will have to provide an IP.BIN file. Most selfbooting programs do
this for you, or you could look on http://mc.pp.se/dc/sw.html and get IP
creator to make your own.
To play ColecoVision games, you MUST provide a ColecoVision BIOS rom. It must be
named coleco.rom and be in the crabemu directory on the CD. If you do not
provide this file, you will not be able to play ColecoVision games.
Your CD's final directory structure should look something like this:
- Root of CD
- 1ST_READ.BIN
- IP.BIN
- crabemu (directory)
- bios.sms (if SMS BIOS support is to be used)
- bios.gg (if Game Gear BIOS support is to be used)
- coleco.rom (if ColecoVision support is to be used)
- title.png
- crab.png
- roms (directory)
- all of your rom files in .sms, .gg, .sg, .col, or .rom format go here
How do I use an SD card with CrabEmu (for Dreamcast)?
-----------------------------------------------------
To use the SD card support with CrabEmu, you will still need to have a CD handy
with all the UI graphics and whatnot (built as specified above). You will also
need to have your SD card formatted with an ext2 filesystem. Once you have that,
you can put your game ROMs anywhere on the SD card and browse through them with
the file browser in the menu.
You can also put all the UI stuff on the SD card. If you want to do that, put
them in a crabemu directory off the root of the card. The same goes for the
bios files.
When formatting your SD card, you must make sure that the partition with any
CrabEmu files on it is the first partition, and you must have an MBR partition
table on the card. Additionally, you should make the partition table actually
say that the partition type is a "Linux" partition (type 0x83), but that isn't
strictly necessary, assuming that it has been formatted properly with mke2fs.
What do I need to build CrabEmu (for Mac OS X)?
-----------------------------------------------
In case you want to build your own copy of CrabEmu, here are the requirements
to build it on Mac OS X.
- Xcode 3 (I'm using 3.2.6 at the moment, but it should still build with older
versions of Xcode 3.x -- the project files are set to Xcode 3.0 format).
- At least the Mac OS X 10.4 Universal and Mac OS X 10.6 SDKs installed.
To build CrabEmu once you have everything set up, all you should have to do is
open the Xcode project file (CrabEmu.xcodeproj in the osx directory) and hit the
build button.
You should be able to build CrabEmu against any Mac OS X SDK that supports
Universal binaries (so anything 10.4u and up). You may have to tweak some
variables in the project configuration for that though.
What do I need to build CrabEmu (for Dreamcast)?
------------------------------------------------
For the Dreamcast:
- Some sort of sh-elf targeted GCC toolchain (I currently use GCC 4.7.0 and
Binutils 2.22).
- KallistiOS out of the Git repository (from Febrary 27, 2013 or later).
You must have libpng, libz, and libbz2 built as well. The versions in kos-ports
will work fine.
The main reason for such a new version of KOS out of the Git repository is
because you'll need libkosext2fs. You could probably make do with a version as
old as the initial commit of libkosext2fs (on December 17, 2012) if you don't
intend to actually use the SD card. If you want to use the SD cards, you'll need
to have at least commit 21deaf55920776d590cc8fd404355a45fcd711d6 (from Febrary
27, 2013) as there were two major bugs fixed in that commit for reading files
from the SD card.
What do I need to build CrabEmu (for *nix or Windows)?
--------------------------------------------
In order to build CrabEmu with the Qt GUI, you must have CMake, Qt 4.x or 5.x,
and SDL installed. Since you will be compiling, you will need both the libraries
themselves and the development packages installed as well. You will also
probably want libbz2 and zlib installed as well so that you'll be able to use
compressed roms.
To build with Qt 4.x, create a build directory and run (filling in
Path_To_CrabEmu as appropriate):
cmake Path_To_CrabEmu
To build with Qt 5.x, you must specify that option to CMake:
cmake Path_To_CrabEmu -DQt5=ON
Then you can build it (generally) by running "make".
To install, run "make install" which, by default, will install to
/usr/local/bin This can be changed by adding
-DCMAKE_INSTALL_PREFIX=/new/path to the cmake command.
There are some options available for the CMake build. You should take a look at
the CMakeLists.txt file in the same directory as this README to see if any apply
to you. The Qt5 option mentioned up there is one of them.
The Qt version of CrabEmu currently lacks a few features of the Mac OS X
version, including various things related to NES support.
Known Issues
------------
The Dreamcast port of CrabEmu has a few issues still to be sorted:
- SRAM saving doesn't happen automatically (unless you change games).
- No way to selectively enable BIOS support and select a BIOS (if the
bios.* files are found, they're used).
- Save States take up quite a bit of space on a VMU. This isn't really an
issue, so to speak, but it is something to be aware of.
As for the Mac OS X version, there are still some odd graphical glitches here
and there. I need to do some major improvements to the VDP core sometime...
Acknowledgements
----------------
CrabEmu makes use of the following components not written by me (possibly with
modifications):
Pixel Art Scaling Toolkit v0.2 - Copyright 2006-2009 WolfWings
- Licensed under the ISC License, see src/utils/pastlib/readme.txt and
src/utils/pastlib/COPYING for more information.
minizip 1.01e - Copyright (C) 1998-2005 Gilles Vollant
- Licensed under the zlib license, see src/utils/unzip.h for more information.
stb-2.23 (specifically, the rom_adler32 function in rom.c) - Public Domain
ym2413.c/ym2413.h - Copyright (C) 2002 Jarek Burczynski
- Licensed under the MAME license. A special exemption is given to link CrabEmu
with this code and distribute the resulting binary. Note that the MAME license
is NOT compatible with the GPL, hence this exemption is granted specifically
for the ym2413.[ch] files provided in the src/sound directory. See the "MAME
(tm) YM2413 Core" section below for more information about the terms that
using this code adds (specifically, the commercial activities section,
although I hope that nobody is trying to sell CrabEmu anyway). Note that my
permission to distribute CrabEmu binaries linked with the YM2413 code from
MAME does NOT grant you permission to distribute CrabEmu binaries linked with
any other parts of MAME (including the Z80 core).
Nofrendo/Nosefart NES APU Core - Copyright (C) 1998-2000 Matthew Conte
- Licensed under the GNU Library GPL version 2. See src/sound/nes_apu/COPYING
for more information. The version in that tree was taken from Nosefart-2.8mls,
and was modified slightly for use in CrabEmu.
zlib - Copyright (C) 1995-2012 Jean-loup Gailly and Mark Adler
- License terms included in README.3rdparty.
libbzip2 - Copyright (C) 1996-2010 Julian R Seward
- License terms included in README.3rdparty.
Dreamcast-specific acknowledgements
-----------------------------------
KallistiOS - Copyright (C) 1997-2013 KallistiOS Contributors
- Licensed under the KOS License, which is a 3-clause BSD license. See
README.3rdparty for more information.
libpng
- License terms included in README.3rdparty.
Special Thanks
--------------
I would like to thank the following people who helped make CrabEmu what it is
today (either directly or indirectly):
- Jean-Paul Van Gorder (for the menu art for the Dreamcast port as well as
other art used in CrabEmu)
- Dan Potter (and everyone else who's ever worked on KallistiOS)
- Charles MacDonald (for all his hardware notes and info on SMS Power)
- Sean Young (for "The Undocumented Z80 Documented" and his documentation of
the TMS9918A)
- Maxim (for his documentation of the SN76489 PSG)
- Cyle Terry (for doing a WHOLE LOT of testing)
- Guillaume Duhamel (for testing on Linux)
- Johannes Manhave (for testing on 64-bit Linux, which pointed me at a rather
stupid bug)
- Harley Laue (for stepping up to improve/maintain/etc the Qt port)
- Everyone who has contributed to the S8-Dev Wiki
- Omar Cornut for his dedication to preservation of Sega's 8-bit history,
including (but not limited to) his work in creating MEKA, and for providing
resources that helped me in adding various mappers to CrabEmu.
- Everyone else who has helped me along the way that I have forgotten above
MAME (tm) YM2413 Core
---------------------
As mentioned in the Acknowledgements section above, a special exemption to the
GPL is granted to link with the provided version of the YM2413 code from MAME.
This code is provided under the following license:
Copyright (C) 1997-2010, Nicola Salmoria and the MAME team. All rights reserved.
Redistribution and use of the MAME code or any derivative works are permitted
provided that the following conditions are met:
- Redistributions may not be sold, nor may they be used in a commercial product
or activity.
- Redistributions that are modified from the original source must include the
complete source code, including the source code for all components used by a
binary built from the modified sources. However, as a special exception, the
source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major components
(compiler, kernel, and so on) of the operating system on which the executable
runs, unless that component itself accompanies the executable.
- Redistributions must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
MAME (tm) Z80 Core
------------------
The MAME Z80 core (contained in cpu/mamez80 in the source distribution) is
not considered a part of CrabEmu. It is provided for those who are curious
and may want to use the debug Z80 mode I had implemented.
The MAME Z80 core is provided under a license that is not compatible with
the GPL. The license terms that it is distributed under are in the
comment at the top of the z80.c file in the directory mentioned above.
I DO NOT provide support for anyone that wishes to use the MAME Z80 core
with CrabEmu. As stated above, it is only provided for those curious
about my debugging setup when I was originally building CrabZ80. It may
or may not be included with future releases, but you can always get it
from the source code distribution of MAME.
CZ80 Core (by Stphane Dallongeville)
-------------------------------------
The CZ80 core (contained in cpu/cz80 in the source distribution) isn't really a
part of CrabEmu proper, either. It is distributed under its own license terms,
which, to my understanding are not compatible with the GPL (covered in its
readme.txt file). CZ80 isn't used in any binaries of CrabEmu, and is only
included as a historical note (it was only added to run it through zexall,
really). The smsz80-cz80.c file provides an interface to use CZ80 with CrabEmu,
but it is incomplete, and probably won't ever be completed (it works enough to
run zexall, but I don't promise much else).
Its interesting to note though that I took quite a few design cues from CZ80
when I (re)designed CrabZ80 (especially the last time).
Mac OS X 10.3 Support
---------------------
There are a few issues with Mac OS X 10.3 support as it stands at the moment as
well. Namely, the Help file doesn't seem to work properly (this is probably
something stupid...) and Fullscreen mode doesn't work (this won't ever be fixed,
most likely). I do not actively test CrabEmu on Mac OS X 10.3, so please let me
know if there are other issues not mentioned above.
Mac OS X 10.2 Support
---------------------
As of CrabEmu 0.1.9, Mac OS X 10.2 is no longer supported. CrabEmu 0.1.8 and
below are available for users of Mac OS X 10.2. I've never been able to test
CrabEmu on Mac OS X 10.2, and I feel that it is a bad idea to support something
that I cannot possibly test.
That's All Folks
----------------
That's pretty much all I could think of to put in this README file,
suggestions would be nice for the next time I have to write one of these.
- Lawrence Sebald
http://crabemu.sourceforge.net/
