
===============================================================================
-------------------------------------------------------------------------------
Mupen64plus-ui-console README                                              v2.5
-------------------------------------------------------------------------------
===============================================================================

The latest documentation for this plugin can be found at:

https://mupen64plus.org/wiki/index.php/UIConsoleUsage

-------------------------------------------------------------------------------
Console Options
-------------------------------------------------------------------------------

At startup, the mupen64plus program will look for a user configuration file
called 'mupen64plus.cfg'.  If this file does not exist, it will be created and
default settings will be written. If desired, an alternate config directory can
be specified using the --configdir commandline option.

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

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

Parameters:
    --noosd               : disable onscreen display
    --osd                 : enable onscreen display
    --fullscreen          : use fullscreen display mode
    --windowed            : use windowed display mode
    --resolution (res)    : display resolution (640x480, 800x600, 1024x768, etc)
    --nospeedlimit        : disable core speed limiter (should be used with dummy audio plugin)
    --cheats (cheat-spec) : enable or list cheat codes for the given rom file
    --corelib (filepath)  : use core library (filepath) (can be only filename or full path)
    --configdir (dir)     : force configation directory to (dir); should contain mupen64plus.cfg
    --datadir (dir)       : search for shared data files (.ini files, languages, etc) in (dir)
    --debug               : launch console-based debugger (requires core lib built for debugging)
    --plugindir (dir)     : search for plugins in (dir)
    --sshotdir (dir)      : set screenshot directory to (dir)
    --gfx (plugin-spec)   : use gfx plugin given by (plugin-spec)
    --audio (plugin-spec) : use audio plugin given by (plugin-spec)
    --input (plugin-spec) : use input plugin given by (plugin-spec)
    --rsp (plugin-spec)   : use rsp plugin given by (plugin-spec)
    --emumode (mode)      : set emu mode to: 0=Pure Interpreter 1=Interpreter 2=DynaRec
    --testshots (list)    : take screenshots at frames given in comma-separated (list), then quit
    --set (param-spec)    : set a configuration variable, format: ParamSection[ParamName]=Value
    --gb-rom-{1,2,3,4}    : define GB cart rom to load inside transferpak {1,2,3,4}"
    --gb-ram-{1,2,3,4}    : define GB cart ram to load inside transferpak {1,2,3,4}"
    --core-compare-send   : use the Core Comparison debugging feature, in data sending mode
    --core-compare-recv   : use the Core Comparison debugging feature, in data receiving mode
    --nosaveoptions       : do not save the given command-line options in configuration file
    --verbose             : print lots of information
    --help                : see this help message

(plugin-spec):
    (pluginname)          : filename (without path) of plugin to find in plugin directory
    (pluginpath)          : full path and filename of plugin
    'dummy'               : use dummy plugin

(cheat-spec):
    'list'                : show all of the available cheat codes
    'all'                 : enable all of the available cheat codes
    (codelist)            : a comma-separated list of cheat code numbers to enable,
                            with dashes to use code variables (ex 1-2 to use cheat 1 option 2)

-------------------------------------------------------------------------------
Cheats
-------------------------------------------------------------------------------

To list the available cheats in the rom:

mupen64plus --cheats list "/path/to/my/rom.v64"

If there are cheats in the rom, you will get (in the output console):

UI-Console: 3 cheat code(s) found for ROM 'MY ROM'
   0: [Enable All Levels] (This is needed to be able to Play all Levels of the Game)
   1: [Enable All Weapons] (This is needed to be able to Play with all Weapons of the Game)
   2: etc...

All you have to do to use this cheats is:

mupen64plus --cheats 0,1,2 "/path/to/my/rom.v64"

-------------------------------------------------------------------------------
Debugger
-------------------------------------------------------------------------------

Setup
=====

You must use a mupen64plus core library which was built with the DEBUGGER flag set.

Running
=======

Use the --debug command-line option to enable the console debugger.

The emulator mode should be set to "interpreter", as the dynarec seems to cause
issues when interacting with the debugging API. This can be done with the R4300Emulator
config setting or with the --emumode flag.

Usage
=====

Once the emulator boots, it will be paused by default. You will be presented
with a prompt as follows:

(dbg) 

The following commands can be entered:

run
  Unpauses the game.

pause
  Pauses the game.

step <num-steps>
  When paused, instructs the emulator to make a single step, or a series of
  steps if num-steps is provided.

regs
  Prints out general purpose register values.

pc
  Print current value of Program Counter register

pc-1
  Print previous value of Program Counter register

asm
  Print assembly language instruction at current PC location

mem
  Print memory values. Several forms are supported:
  
  mem <addr>        Print one 32-bit word at <addr>
  
  mem /N <addr>     Print <N> 32-bit words at <addr>
  mem /Nb <addr>    Print <N> 8-bit bytes at <addr>
  mem /Nh <addr>    Print <N> 16-bit half-words at <addr>
  mem /Nw <addr>    Print <N> 32-bit words at <addr>
  mem /Nd <addr>    Print <N> 64-bit double-words at <addr>

  mem /NxM <addr>   Print <N> rows of <M> 32-bit words at <addr>
  mem /NxMb <addr>  Print <N> rows of <M> 8-bit bytes at <addr>
  mem /NxMh <addr>  Print <N> rows of <M> 16-bit half-words at <addr>
  mem /NxMw <addr>  Print <N> rows of <M> 32-bit words at <addr>
  mem /NxMd <addr>  Print <N> rows of <M> 64-bit double-words at <addr>

bp add <addr>
  Adds a breakpoint at a given address.

bp rm <addr|index>
  Removes a breakpoint by address or number.

bp list
  Lists all breakpoints.

exit|quit
  Stop emulator and quit debugger

