Mupen64Plus README
------------------

The most current version of this README and more documentation can be found on the Mupen64Plus wiki:

http://code.google.com/p/mupen64plus/wiki/README

Mupen64Plus is based off of mupen64, originally created by Hacktarux. The Mupen64Plus package contains the mupen64 emulator program (renamed mupen64plus) plus graphics, sound, input, and RSP plugins.

README Sections
  1. Building From Source
  2. Installation
  3. Multi-user Support
  4. Key Commands In Emulator
  5. Known Issues


1. Building From Source
-----------------------

If you downloaded the binary distribution of Mupen64Plus, skip to the Installation section. To build the source distribution, unzip and cd into the source directory, then build using make:

 $ unzip Mupen64Plus-x-y-z-src.zip
 $ cd Mupen64Plus-x-y-z-src
 $ make all

Type 'make' by itself to view all available build options:

 $ make
 Mupen64Plus makefile. 
   Targets:
     all           == Build Mupen64Plus and all plugins
     clean         == remove object files
     rebuild       == clean and re-build all
     install       == Install Mupen64Plus and all plugins
     uninstall     == Uninstall Mupen64Plus and all plugins
   Options:
     BITS=32       == build 32-bit binaries on 64-bit machine
     VCR=1         == enable video recording
     LIRC=1        == enable LIRC support
     GUI=NONE      == build without GUI support
     GUI=GTK2      == build GTK2 GUI support (default)
     GUI=KDE4      == build KDE4 GUI support
     PREFIX=path   == specify install/uninstall prefix (default: /usr/local)
   Debugging Options:
     PROFILE=1     == build gprof instrumentation into binaries for profiling
     DBGSYM=1      == add debugging symbols to binaries
     DBG=1         == build graphical debugger
     DBG_CORE=1    == print debugging info in r4300 core
     DBG_COUNT=1   == print R4300 instruction count totals (64-bit dynarec only)
     DBG_COMPARE=1 == enable core-synchronized r4300 debugging
     DBG_PROFILE=1 == dump profiling data for r4300 dynarec to data file

Previous to version 1.3, building mupen64 built two programs: mupen64 and mupen64_nogui. mupen64 had a gtk graphical frontend including a rom browser. mupen64_nogui contained no graphical frontend and all options were specified via the commandline. As of version 1.3, the mupen64 and mupen64_nogui codebases have been combined. Now, building mupen64plus results in one executable called mupen64plus that can either be run with a gui (default) or without a gui, by specifying --nogui at the commandline. For backwards compatability, if a symbolic link to the mupen64plus executable called mupen64plus_nogui (or mupen64_nogui) is created, running the mupen64plus_nogui symlink is equivalent to running mupen64plus with the --nogui flag.

NOTE: If you want to build a nogui-only version of mupen64plus, i.e. without gtk+ dependencies, pass the GUI=NONE option to make, like this:

 $ make GUI=NONE all

2. Installation
---------------

*Binary Distribution*

To install the binary distribution of Mupen64Plus, su to root and run the provided install.sh script:

 $ su
 # ./install.sh
 # exit
 $

The install script will copy the executable to /usr/local/bin and a directory called /usr/local/share/mupen64plus will be created to hold plugins and other files used by mupen64plus.

NOTE: By default, install.sh uses /usr/local for the install prefix. Although the user can specify an alternate prefix to install.sh at the commandline, the mupen64plus binary was compiled to look for the install directory in /usr/local, so specifying an alternate prefix to install.sh will cause problems (mupen64plus will not find the install directory). If you want to use a prefix other than /usr/local, you will have to download the source package and build with the PREFIX option (see below).

*Source Distribution*

After building mupen64plus and all plugins, su to root and type 'make install' to install Mupen64Plus. The install process will copy the executable to $PREFIX/bin and a directory called $PREFIX/share/mupen64plus will be created to hold plugins and other files used by mupen64plus. By default, PREFIX is set to /usr/local. This can be changed by passing the PREFIX option to make. NOTE: you must pass the prefix, when building AND installing. For example, to install mupen64plus to /usr, do this:

 $ make PREFIX=/usr all
 $ su
 # make PREFIX=/usr install
 # exit
 $

3. Multi-user Support
---------------------

As of version 1.3, Mupen64Plus now has support for multi-user environments.

The mupen64plus program will look for user configuration files in a .mupen64plus directory in the user's home directory. If the directory does not exist, it will be created and a default mupen64plus.conf file will be written to that directory on exit. If desired, an alternate config directory can be specified using the --configdir commandline option.

By default, the mupen64plus program will look for plugins, icons, and language translation files in the install directory $PREFIX/share/mupen64plus (see Installation section for details). If this directory does not exist, mupen64plus will try to use the current working directory. An alternate installation directory can be specified using the --installdir commandline option.

Run 'mupen64plus --help' for a complete list of commandline options:

 $ mupen64plus --help
 Usage: mupen64plus [parameter(s)] rom

 Parameters:
         --nogui                 : do not display GUI
         --fullscreen            : turn fullscreen mode on
         --gfx (path)            : use gfx plugin given by (path)
         --audio (path)          : use audio plugin given by (path)
         --input (path)          : use input plugin given by (path)
         --rsp (path)            : use rsp plugin given by (path)
         --emumode (number)      : set emu mode to: 0=Interpreter 1=DynaRec 2=Pure Interpreter
         --sshotdir (dir)        : set screenshot directory to (dir)
         --configdir (dir)       : force config dir (must contain mupen64plus.conf)
         --installdir (dir)      : force install dir (place to look for plugins, icons, lang, etc)
         --noask                 : don't ask to force load on bad dumps
         -h, --help              : see this help message


4. Key Commands In Emulator
---------------------------
The keys or joystick/mouse inputs which will be mapped to the N64 controller for playing the games are determined by the input plugin.  The emulator core also supports several key commands during emulation, which are fixed and cannot be changed.  They are:

   Escape == Quit the emulator
      0-9 == Select virtual 'slot' for save/load state (F5 and F7) commands
       F5 == Save emulator state
       F7 == Load emulator state
Alt-Enter == Toggle between windowed and fullscreen (may not be supported by all video plugins)
   p or P == Pause on/off
   m or M == Mute/unmute sound
        [ == Decrease volume
        ] == Increase volume


5. Known Issues
-----------------------
As of March 2008, the RiceVideoLinux plugin may be unstable with users of the open source drivers for an ATI Radeon graphics adapter when fog is enabled.  If you have are using the open source Radeon driver, you should set the "EnableFog" value in RiceVideo.cfg to 0.