README

   1 GNUBOY 1.0.4 README
   2
   3 Welcome to gnuboy, one of the fastest if not the fastest GB/GBC emu-
   4 lator available.
   5
   6 gnuboy was written well over 20 years ago and achieved full speed
   7 on most machines of that era, on today's machines it runs close to
   8 0% CPU usage.
   9
  10 gnuboy development was mostly stagnant for the past 20 years, but
  11 i revived it using the last released sources and CVS dumps and fixed
  12 numerous minor issues with modern compilers and systems, as well
  13 as the occasional bugfix, plus a new SDL2 backend.
  14
  15 changes to 1.0.3 include:
  16
  17 - new ao audio backend
  18 - new SDL2 video/input/audio backend
  19 - fixed cpu cycle accuracy for all CPU ops
  20 - backported fix for some opcodes
  21 - fixed issues with window in NBA hoopz
  22 - added support for .xz compressed roms
  23 - added support for original BIOS
  24
  25 unlike most modern GB emulators, gnuboy doesn't strive to be
  26 cycle-accurate (except where necessary), but to be fast, portable
  27 and compatible and to provide a good gaming experience.
  28
  29 it works using the following backends:
  30
  31 - linux fbdev
  32 - linux joystick
  33 - SDL1.2
  34 - SDL2
  35 - X11
  36 - AO audio
  37 - OSS audio
  38 - SVGAlib
  39 - DOS/Windows (untested)
  40
  41 old README follows.
  42
  43   INTRO
  44
  45 Welcome to gnuboy, one of the few pieces of Free Software to emulate
  46 the Game Boy handheld game console. Written in ANSI C with a few
  47 optional assembler optimizations for particular cpus, gnuboy supports
  48 a wide range of host systems, and has been tested successfully on:
  49
  50   GNU/Linux
  51   FreeBSD
  52   OpenBSD
  53   BeOS
  54   Linux/390 (IBM S/390 Mainframe)
  55   SunOS/Sun Ultra60
  56   IRIX/SGI O2
  57   IRIX/SGI Indy
  58   AIX/Unknown
  59   DR-DOS
  60   MS-DOS
  61   Windows DOS box
  62   Windows 9x/NT/2k
  63
  64 Additionally, gnuboy should run on any other *nix variants that have
  65 ANSI C compilers and that are remotely POSIX compliant. As gnuboy is
  66 Free Software, you're welcome to fix any problems you encounter
  67 building it for a particular system, or to port it to entirely new
  68 systems.
  69
  70
  71   EMULATION
  72
  73 gnuboy emulates nearly all aspects of the (Color) Gameboy, including
  74 all of the following and much more:
  75
  76   Full GBZ80 instruction set.
  77   Scanline-based LCD engine.
  78   Ten sprites per scanline limit.
  79   Support for all CGB graphics extensions.
  80   Sprite DMA, HDMA, and GDMA.
  81   All four sound channels including digital samples.
  82   MBC1, MBC2, MBC3 (including clock), and MBC5 mappers.
  83   Wave pattern memory corruption when sound channel 3 is played.
  84   Pad, timer, divide counter, and other basic hardware registers.
  85   CGB double-speed CPU mode.
  86
  87 Aspects not emulated at this time include:
  88
  89 * Serial IO (link cable).
  90   Undocumented 'extra' ram in OAM space on Gameboy Color.
  91   All Super Gameboy extensions.
  92 * GBC, HuC1, and HuC3 IR ports.
  93 * Obscure mappers such as TAMA5.
  94   Sorting sprites by X coordinate in DMG mode.
  95   HALT instruction skipping in DMG mode.
  96   CPU stalls during HDMA and GDMA.
  97
  98 Only the two marked by * are known to affect the playability of
  99 actual games or demos; the rest are just listed for completeness'
 100 sake.
 101
 102
 103   CONFIGURATION
 104
 105 Please refer to docs/CONFIG and the sample files in etc/.
 106 The default search path order for configuration files is:
 107
 108   $HOME/.gnuboy/gnuboy.rc
 109   ./gnuboy.rc
 110
 111
 112   FEATURES
 113
 114 In addition to basic emulation, gnuboy provides the following
 115 features:
 116
 117   Highly flexible keybinding and configuration subsystem.
 118   State saving and loading at any point.
 119   Very precise timing/synchronization, preserved across save/load.
 120   Joystick support on Linux, DOS, and all SDL-based ports.
 121   Fully customizable palettes for DMG games.
 122   Screen scaling by a factor of 2, 3, or 4 in all ports.
 123   Hardware-based screen scaling on platforms where it's available.
 124   Debug traces to stdout.
 125   Dynamic palette allocation when run in 256-color modes...
 126   OR simulated 3/3/2 bits per channel in 256-color modes.
 127
 128 For information on configuring and using these features, see the
 129 additional documentation in the "docs" directory.
 130
 131
 132   COMPATIBILITY
 133
 134 Out of over 300 results reported by testers, all games are known to
 135 work perfectly on gnuboy with the following exceptions:
 136
 137   Fighting Phoenix (Japanese) may or may not work since it uses the
 138   HuC1 memory controller, which is not implemented properly. There has
 139   been no report either way so far.
 140
 141   Pocket Bomberman (Japanese version, which uses HuC1) runs, but can
 142   be made to crash if the player jumps into the ceiling in the first
 143   level. It's not clear whether this bug is MBC-related, something
 144   else, or an actual bug in the original game.
 145
 146   Monster Go! Go! Go! (Japanese) is unplayable. The cause of the
 147   problem is not fully known, but it's either a very bad dump or it's
 148   using some sort of specialized MBC that's not documented.
 149
 150   Final Fantasy Adventure has visual problems with the fade between
 151   screens. Does not affect gameplay.
 152
 153   Bubble Bobble 2 has some minor tile glitches right before gameplay
 154   actually begins. Cause unknown. Does not affect gameplay.
 155
 156   Alone in the Dark is reported to have minor visual glitches. I
 157   haven't seen it myself so I can't judge their severity.
 158
 159   Both new Zelda games are reported to have a visual glitch at the
 160   beginning of the game, and on certain other screens. I haven't seen
 161   the problem myself, but supposedly it impacts gameplay to some
 162   extent.
 163
 164 Please report any other incompatibilities discovered directly to
 165 gnuboy@unix-fu.org, so that they can be documented and hopefully
 166 fixed.
 167
 168
 169   FUTURE / WISHLIST
 170
 171 Here's a brief list of what may appear in gnuboy in the future:
 172
 173   Screenshots.
 174   Integrated debugger.
 175   Super Gameboy support.
 176   Serial link over the internet.
 177   Serial link to a real Gameboy with a custom cable.
 178   Configurable color filters to provide more authentic LCD look.
 179   Custom colorization of DMG games on a per-tile basis.
 180   Support for more colorspaces in the hardware scaler.
 181   Recording audio.
 182   GBS player built from the same source tree.
 183   Full recording and playback of emulation.
 184   So-called "high level emulation" of certain typical dumb loops.
 185
 186 Features that are not likely to appear soon or at all include:
 187
 188   Rumble support - this would be nice, but SDL doesn't seem to support
 189   force-feedback yet. We'll see about it in the long-term though.
 190
 191   Eagle/2xSaI/etc. - probably not feasible since these libraries don't
 192   appear to be compatible with the terms of the GPL. We might work on
 193   our own interpolation engine eventually, but that's low priority.
 194
 195   GUI/GUI-like features - such things are best handled by external
 196   front-ends. We might eventually add a mechanism for external
 197   programs to communicate with gnuboy and reconfigure it while it's
 198   running, however.
 199
 200   Plugins - NO! The way I see it, plugins are just an attempt to work
 201   around the GPL. In any case, even if you are adding plugin support
 202   yourself, you are bound by the terms of the GPL when linking ANY
 203   code to gnuboy, including dynamic-linked modules. However we'd
 204   rather not deal with this mess to begin with.
 205
 206   Compressed ROMs/Saves - this one is very iffy. On most systems, this
 207   is redundant; *nix users can just pipe the rom through a
 208   decompression program, and Windows users can just double-click or
 209   drag files from their favorite GUI unzipper program. Linking to zlib
 210   isn't really acceptable since it's massively bloated and we don't
 211   want to include it with gnuboy or add external dependencies. We may,
 212   however, write our own tiny decompressor to use at some point.
 213
 214 Ideas and suggestions for other features are welcome, but won't
 215 necessarily be used. You're of course also free to add features
 216 yourself, and if they fit well into the main tree they may eventually
 217 get included in the official release. See the file HACKING for more
 218 details on modifying and/or contributing.
 219
 220
 221   THANKS
 222
 223 Thanks goes out to everyone who's expressed interest in gnuboy by
 224 writing -- users, porters, authors of other emulators, and so forth.
 225 Apologies if we don't get a personal response out to everyone, but
 226 either way, consider your feedback appreciated.
 227
 228
 229   EPILOGUE
 230
 231 OK, that looks like about it. More to come, stick around...
 232
 233
 234
 235                                           -Laguna  <laguna@aerifal.cx>
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246