README

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