===============================================================================

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 --savestate (filepath) : savestate loaded at startup --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} --dd-ipl-rom : define 64DD IPL rom --dd-disk : define disk to load into the disk drive --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 --pif (filepath) : use a binary PIF ROM (filepath) instead of HLE PIF --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 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 instructions. Several forms are supported:

asm Print one instruction at the Program Counter register

asm Print one instruction at

asm Print instructions starting at

asm Print instructions starting at with flags - If flags bit-3 is set (i.e. & 0x04): also print binary instruction data - If flags bit-2 is set: prefix each instruction with its memory address - If flags bit-1 is set: prefix each instruction with a counter from

mem Print memory values. Several forms are supported:

mem Print one 32-bit word at

mem /N Print <N> 32-bit words at mem /Nb Print <N> 8-bit bytes at mem /Nh Print <N> 16-bit half-words at mem /Nw Print <N> 32-bit words at mem /Nd Print <N> 64-bit double-words at

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

write Write values to memory. Several forms are supported:

write Write a (1) byte value to

write b Write a (1) byte value to write h Write a half-word value (2 bytes) to write w Write a word value (4 bytes) to write d Write a double-word value (8 bytes) to

translate Translates virtual memory addresses to physical memory addresses. Memory read/write breakpoints must operate on physical addresses, in contrast to the memory read/write commands and execution breakpoints that operate on virtual addresses.

translate Print the 32-bit physical address for the provided argument.

bp add Adds a breakpoint at a given address. Several forms are supported:

bp add pc Add a breakpoint at the Program Counter, triggered on EXEC, READ, and WRITE.

bp add Add a breakpoint at , triggered on EXEC, READ, and WRITE.

bp add Add a breakpoint starting at , extending bytes, triggered on EXEC, READ, and WRITE.

bp add Add a breakpoint starting at , extending bytes, with specified trigger flags. - M64P_BKP_FLAG_READ = 0x02 - M64P_BKP_FLAG_WRITE = 0x04 - M64P_BKP_FLAG_EXEC = 0x08

bp trig Prints the reason for the most recently activated breakpoint trigger. Memory read/write breakpoints will indicate the hit address.

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

bp list Lists all breakpoints.

exit|quit Stop emulator and quit debugger

64DD Support

Some compatibility with the 64DD disk drive unit has been implemented, but there are a few small usability issues of which users should be aware.

When using the 64DD, you need to pass a path to a cartridge rom, even if none is strictly required. The IPL boot rom will execute first and select the disk if you have one inserted, or just show the boot menu otherwise. We can remove this requirement at a later time. For now all we need to remember is to use a Japanese ROM (otherwise some region check will fail) with same features as the 64DD game you want to play (think RumblePak, TransferPak, otherwise, they won't be available).

There is a sibling issue also with 64DD games in that there are no entries in the game db (mupen64plus.ini) for them, and the core currently only relies on the cart ROM loaded to fetch the ROM infos.