config

gameboy 模拟器的源代码

GUIDE TO CONFIGURING GNUBOY


[ P A R T   I ]
  OVERVIEW

There are two major ways of configuring the way gnuboy behaves at
runtime: setting the values of variables, and binding commands to keys
and joystick buttons. Each can be done either on the command line, or
from a config (rc) file.

If you don't want to read all this detailed info, look at the sample
rc files provided, then browse back through this file to clarify
anything that seems confusing. You might also skip down to Part II if
you're already familiar with the syntax of gnuboy rc files and such;
the second part explains the configurable variables which you can play
with.


  WHAT HAPPENS AT STARTUP

When gnuboy is started, it first processes gnuboy.rc, the primary
configuration file. On *nix systems, gnuboy will initially look for
its rc files in ~/.gnuboy, or if that fails, the present working
directory. On DOS and Windows, the current directory will be searched
first, followed by the directory containing the gnuboy executable.

After finishing with gnuboy.rc, gnuboy next looks for an rc file with
the same base name as the rom to be loaded. For example, if the name
of the rom is mygame.gb, gnuboy will process mygame.rc, if it exists.
This allows you to configure different preferences on a per-rom
basis. The locations searched for the rom-specific rc file are the
same as those searched for gnuboy.rc, unless gnuboy.rc has changed the
search path (see below for more info).

Finally, options on the command line are processed. The command line
will override any settings in the auto-loaded rc files. This is a good
place for options that you just want to use occasionally, but not on a
regular basis.

After all of the above is finished, gnuboy loads the rom and starts
emulation.


  RC FILES

The rc files gnuboy uses are plain text files, with one command on
each line. Lines that start with # are treated as comments, that is to
say they are ignored, and blank lines are ignored as well.

There are three major types of commands.


  RC FILES -- SETTING VARIABLES

First of all, there is the "set" command, which is used for setting
the values of variables. For example,

  set scale 2

will set the screen scaling factor to 2. If you need to include a
space in the value of a variable, you can do something like this:

  set savename "I like spaces in my filenames"

and then your save files will be named something like:

  I like spaces in my filenames.sav
  I like spaces in my filenames.000
  I like spaces in my filenames.001
  I like spaces in my filenames.002
  etc.

Finally, some variables allow multiple numbers to be given. For
example, to set the video mode to 640x480, 16bpp, you might do
something like this:

  set vmode 640 480 16

Observe that each number is separate, and there are no quotation marks
used.


  RC FILES -- KEYBINDINGS

Next, we have commands that deal with key and joystick bindings. These
are fairly simple.

The "unbindall" command removes all existing keybindings -- be
careful! -- and its main use is for people who want to redefine their
keyboard controls entirely and throw away the defaults. Be warned that
if you unbind the quit key and don't bind a new key for quitting, you
may be unable to exit gnuboy cleanly!

The "unbind" command is similar, but it only unbinds one key at a
time. For example, to unbind the "space" key, use this command:

  unbind space

See below for a list of key names to use with unbind.

Now we get to the main useful keybinding command: "bind". For example,
if you want the "tab" key to perform the Gameboy "select" button
function, use the following bind command:

  bind tab +select

The significance of the + sign will be explained below. As with the
"set" command, quotation marks can be used with bind if the command
needs to contain spaces.


  KEY NAMES FOR BINDINGS

When using the bind and unbind commands, you need to tell gnuboy which
key you wish to affect. Most of the keys that correspond to a
character you can type can just be referenced by that character. For
example, the alphabetical keys are bound by the lowercase letter they
represent, and the numeral keys (on the main keyboard, not the numeric
keypad) can be bound by their numeral. Other keys require a name. Some
are really obvious:

  shift, ctrl, alt, up, down, right, left
  enter, tab, space, home, end, esc, pause
  f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12

Others are a bit less obvious but still should make sense. Some of
these can also be referenced by other names; read the source file
keytable.c for a full list:

  bs            Backspace
  ins           Insert
  del           Delete
  prior         Page Up
  next          Page Down
  caps          Caps Lock
  numlock       Num Lock
  scroll        Scroll Lock
  minus         - or _
  equals        = or +
  tilde         ` or ~
  slash         / or ?
  bslash        \ or |
  semi          ; or :
  quote         ' or "

The numeric keypad is referenced as follows

  num0-num9     Numeral keys 0-9 (on keypad)
  numplus       Numeric keypad +
  numminus      Numeric keypad -
  nummul        Numeric keypad *
  numdiv        Numeric keypad /
  numdot        Numeric keypad .
  numenter      Numeric keypad Enter key

Joystick buttons and directions also have names for binding, and they
are bound just like ordinary keys. Their names are as follows:

  joyup         Joystick up
  joydown       Joystick down
  joyleft       Joystick left
  joyright      Joystick right
  joy0-joy15    Joystick buttons

The way joystick buttons are numbered varies from one joystick to
another. Experiment to find the names that are right for the buttons
you want to use.


  RC FILES -- THE SOURCE COMMAND

The "source" command simply causes gnuboy to process another rc file
before resuming processing of the current one. It is useful for
splitting up your config into multiple parts, perhaps one file
auto-generated by a front-end and another hand-customized. Use of this
command is very simple:

  source myfile.rc

will perform all the commands in myfile.rc. Note that the source
command also provides a method for binding multiple commands to a
single key. For example, simply

  bind f1 "source f1stuff.rc"

and then f1stuff.rc will be run whenever you press F1.


  RC FILES -- ACTION COMMANDS

Finally, we have rc commands that perform actions. These commands are
probably only useful when bound to a key, and might cause unexpected
behavior or even crashes if used by themselves in an rc file loaded at
startup.

First of all, the "quit" command should be obvious. It simply exits
the emulator. If the rom that's loaded uses battery backed save ram or
realtime clock, these files will automatically be saved at exit.

The "reset" command should also be fairly obvious. It acts as a reset
button, restarting execution of the loaded rom at the beginning, as if
you turned the Gameboy power off and back on.

Slightly more interesting are the "savestate" and "loadstate"
commands. These are used for saving and resuming "saved state" files,
which allow you to save the exact status of the emulation environment
and restore it later, effectively letting you "save game" at any point
in any game. If a number is specified after either of those commands,
the indicated save slot number is used. Otherwise, the slot set in the
"saveslot" variable will be used. See the information on variables
below for more info.

Most importantly, we have the action commands that control the
emulated Gameboy input pad. They are described below:


  COMMANDS THAT BEGIN WITH A PLUS SIGN

Normally, gnuboy only performs the command bound to a key when the key
is pressed; nothing happens when it is released. But for some things,
particularly the Gameboy pad buttons, it's important for something to
happen when the bound key is released. This is the purpose of commands
that begin with a + sign. When a key is released, gnuboy checks to see
if the bound command begins with +, and if so, it changes the + to -
and performs the resulting command. This causes the Gameboy pad
buttons to go back to their normal state when the keys bound to them
are released.

The Gameboy pad commands, which should be self-explanatory, are as
follows:

  +a, +b, +start, +select, +up, +down, +left, +right

If you're at all familiar with Quake's config system, this should all
be clear.


  THE GNUBOY COMMAND LINE

Additional rc files to process, variable settings, and keybindings can
be specified on the command line when gnuboy is run.

Processing an extra config file is simple:

  gnuboy --source myfile.rc game.gb

Specifying an extra rc file on the command line like this is
especially useful for frontends, which may want to put all the options
they set in one rc file so they don't have to pass a super-long
command line to gnuboy.

Binding keys is also pretty simple. Just use something like:

  gnuboy --bind tab +select game.gb

Setting variables is where things get a bit more complicated. For
on/off (boolean) settings, you can just do something like

  gnuboy --no-sound game.gb

to turn a variable (sound) off, i.e. set it to 0. Likewise, boolean
variables can be turned on via something like

  gnuboy --rgb332 game.gb

which turns the "rgb332" variable on (see below for information on
what it does).

For other variables where you actually want to set a number or a
string, use this form:

  gnuboy --savename=mygame2 game.gb

Finally, for variables with multiple numbers to be set, you can
separate them by commas as follows:

  gnuboy --vmode=512,384,32

to avoid having to quote the spaces.


[ P A R T   I I ]
  GUIDE TO CONFIGURABLE VARIABLES

What follows is a detailed explanation of most of the configuration
variables available for your tweaking. They are organized by what part
of gnuboy's behavior they affect -- graphics, sound, emulation, and so
on.

Some variables may or may not be available depending on how gnuboy was
built. For example, if you built gnuboy on a system without sound
support, some variables related to sound may not exist for you, and
attempts to set them will be silently ignored. In most cases, it's
noted in the documentation when variables might not be available.

Also, there are a few highly system-specific variables, such as names
of devices to use for video and sound on *nix systems. These are
listed separately at the end, and it should go without saying that
they will not be available on all builds of gnuboy.


  VIDEO AND GRAPHICS SETTINGS

Since this is everyone's favorite thing to customize, video seems a
good place to start.


  SCREEN SCALING

There are a number of variables that control how gnuboy scales the
display. The most basic is the "scale" option, which is just the
factor to scale by. For example

  set scale 2

will double the size of the display. Set the scale factor to 1 for no
scaling.

There are two ways gnuboy can go about doing scaling. The preferable
way is to use your computer's graphics hardware to do all the work.
This cuts down on the amount of CPU time consumed and provides