Download Latest Version CrabEmu-0.2.0.tar.bz2 (612.9 kB) Get Updates
Home / CrabEmu / 0.2.0
Name Modified Size InfoDownloads / Week
Parent folder
README 2013-02-28 19.6 kB
CrabEmu-BIOS-0.2.0.tar.bz2 2013-02-28 18.9 kB
CrabEmu-0.2.0.tar.bz2 2013-02-28 612.9 kB
CrabEmu-0.2.0.dmg 2013-02-28 922.3 kB
CrabEmu-0.2.0-dc.tar.bz2 2013-02-28 546.2 kB
Totals: 5 Items   2.1 MB 21
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 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) - (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 StŽphane 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
Source: README, updated 2013-02-28