Mednafen

General Documentation

Last updated December 23, 2005
Valid as of Mednafen 0.4.1

Table of Contents:

Introduction

Mednafen is an NTSC and PAL NES and Famicom, GameBoy, GameBoy Color, GameBoy Advance, Atari Lynx, PC Engine, and SuperGrafx emulator for various platforms. It is primarily based off the last publicly released version of FCE Ultra, with code from VisualBoy Advance for GB(A) emulation, and Handy for Lynx emulation.

This document has been arranged to keep user interface details and emulation details as separate as possible, though this has not been accomplished entirely.

In several places references are made to the "base directory". If you are running a port on a UN*X-like system(Linux/*BSD/Mac OSX/SunOS/etc.), the base directory is "~/.mednafen", or in other words, "your home directory plus .mednafen". For all other ports(including DOS and MS Windows), the base directory is the directory that the executable is in.

Mednafen includes or links with the following software packages and programs, so give the developers lots of thanks sometime(NOTE they do not provide user support for Mednafen, so don't ask them questions about Mednafen)!

Core Features

Automatic IPS Patching

Place the IPS file in the same directory as the file to load, and name it filename.ips. 

        Examples:       Boat.nes - Boat.nes.ips
                        Boat.zip - Boat.zip.ips
                        Boat.nes.gz - Boat.nes.gz.ips
                        Boat     - Boat.ips

Some operating systems and environments will hide file extensions. Keep this in mind if you are having trouble.

Patching is supported for all supported formats, but it will probably only be useful for fixed-position file formats.

Using Mednafen

Key Assignments

Key(s):Action:Configuration String:
F5Save state.save_state
F7Load state.load_state
0-9Select save state slot."0" through "9"
Shift + F5Record movie.save_movie
Shift + F7Play movie.load_movie
Shift + 0-9Select movie slot."m0" through "m9"
F1Toggle 600-frame(~10 seconds on NES) save-state rewinding functionality, disabled by default.state_rewind_toggle
BackspaceRewind emulation, if save-state rewinding functionality is enabled, up to 600 frames.state_rewind
F9Save screen snapshot.take_snapshot
Alt + EnterToggle fullscreen mode.toggle_fs
Ctrl + 1
through
Ctrl + 9		Toggle layer."tl1" through "tl9"
~Fast-forward.fast_forward
F2Activate in-game input configuration process for a command key.input_configc
F10Reset.reset
F11Hard reset(toggle power switch).power
F12Exit.exit

NES

Key(s):Action:Configuration String:
F3Activate in-game input configuration process for input port 1.input_config1
Shift + F3Activate in-game input configuration process for input port 2.input_config2
Alt + F3Activate in-game input configuration process for the Famicom expansion port.input_configfc

VS Unisystem

Key:Action:Configuration String:
F8Insert coin.insert_coin
F6Show/Hide dip switches.toggle_dipview
1-8Toggle dip switches(when dip switches are shown)."1" through "8"

Famicom Disk System

Key:Action:Configuration String:
F6Select disk and disk side.select_disk
F8Eject or Insert disk.insert_eject_disk

Barcode Readers

Key:Action:Configuration String:
0-9Barcode digits(after activating barcode input)."0" through "9"
F8Activate barcode input/scan barcode.activate_barcode

Game Pad

Key:Button on Emulated Gamepad:
Keypad 2B
Keypad 3A
Enter/ReturnStart
TabSelect
ZDown
WUp
ALeft
SRight

Power Pad

Side B
OP []
KL;'
M,./

Side A
P [
KL;'
,.

Family Keyboard

All emulated keys are mapped to the closest open key on the PC keyboard, with a few exceptions. The emulated "@" key is mapped to the "`"(grave) key, and the emulated "kana" key is mapped to the "Insert" key(in the 3x2 key block above the cursor keys).

To enable or disable Family Keyboard input, press the "Scroll Lock" key. When Family Keyboard input is enabled, Mednafen will also attempt to prevent any key presses from being passed to the GUI or system.

HyperShot Controller

RunJump
Controller IQW
Controller IIER

Mahjong Controller

Emulated Mahjong Controller:ABCDEFGHIJKLMN
PC Keyboard:QWERTASDFGHJKL

Emulated Mahjong Controller:SELST?????
PC Keyboard:ZXCVBNM

Quiz King Controller

Emulated Buzzer:123456
PC Keyboard:QWERTY

Atari Lynx

Key(s):Action:Configuration String:
F3Activate in-game input configuration process for Lynx pad.input_config1
F8Rotate the screenrotatescreen

Key:Action/Button:
Keypad 2B
Keypad 3A
Keypad 4 & Enter/ReturnPause
Keypad 7Option 1
Keypad 1Option 2
WUp
ZDown
ALeft
SRight

GameBoy/GameBoy Color/GameBoy Advance

Key(s):Action:Configuration String:
F3Activate in-game input configuration process for GameBoy pad.input_config1

Key:Action/Button:
Keypad 2B
Keypad 3A
Enter/ReturnStart
TabSelect
Keypad 5Shoulder Left
Keypad 6Shoulder Right
WUp
ZDown
ALeft
SRight

PC Engine(TurboGrafx 16)/SuperGrafx

Key(s):Action:Configuration String:
F3Activate in-game input configuration process for gamepad 1.input_config1
Shift+F3Activate in-game input configuration process for gamepad 2.input_config2
F4Activate in-game input configuration process for gamepad 3.input_config3
Shift+F4Activate in-game input configuration process for gamepad 4.input_config4
Ctrl+Shift+F4Activate in-game input configuration process for gamepad 5.input_config5

Key:Action/Button:
Keypad 2II
Keypad 3I
Enter/ReturnRun
TabSelect
WUp
ZDown
ALeft
SRight

Command-line

Mednafen supports arguments passed on the command line. Arguments are taken in the form of "-parameter value". Some arguments are valueless. Arguments that have both a parameter and a value will be saved in the configuration file, with the exception being the network-play arguments.

Arguments listed in this table that contain <system> should have that string replaced with "nes", "pce", "gb", "gba", or "lynx".
Example: <system>.xscale becomes nes.xscale.

Argument:Value Type:Default value:Description:
-loadcd xstringn/aLoad and boot a CD for system "x"(only "pce" is valid). This argument modifies the usage of the filename component of the command-line. For example, "mednafen -loadcd pce /somewhere/over/the/rainbow/game.cue" will load the CUE sheet as the emulated CDROM.
"mednafen -loadcd pce" will load from the default physical CDROM device.
-nes.fnscan xboolean1If value is true, scan the NES ROM image filename for (U), (J), and (E), and set the emulated video system(NTSC/PAL) accordingly, with NTSC preferred.
-autosave xboolean0Automatically save the game state when a game is closed and reload the state when the game is loaded again.
-dfmd5 xboolean1Include the MD5 hash of the loaded game in the filenames of the data file(save states, SRAM backups) Mednafen creates.
-snapname xboolean0If value is true, use an alternate naming scheme(file base and numeric) for screen snapshots.
-sound xboolean1If value is true, enable sound emulation and output.
-soundrate xinteger48000Specifies the sound playback rate, in frames per second("Hz").
-soundvol xinteger100Sound volume.
-soundbufsize xinteger32(52 for Win32)Specifies the desired size of the sound buffer, in milliseconds.
-autofirefreq xinteger3Set auto fire frequency to ~60Hz / (x + 1). Replace "60" with "50" for PAL games. A value of "0" disables the configured autofire buttons.
-ckconfig xstring(comma-delimited)Configure mapping of physical buttons to commands. Values that are valid in the comma-delimited string include:
  • save_state
  • load_state
  • save_movie
  • load_movie
  • cheats
  • "0" through "9"
  • "m0" through "m9"
  • "tl1" through "tl9"
  • take_snapshot
  • hide_sprites
  • hide_bg
  • toggle_fs
  • fast_forward
  • insert_coin
  • toggle_dipview
  • select_disk
  • insert_eject_disk
  • activate_barcode
  • toggle_fkb
  • input_config1
  • input_config2
  • input_config3
  • input_config4
  • input_configfc
  • state_rewind_toggle
  • state_rewind
  • rotatescreen
  • reset
  • power
  • exit

During configuration, pressing the same button twice in a row will cause configuration to move to the next command to configure. A maximum of 4 physical buttons may be assigned to one command.

-inputcfg xstringConfigure mapping of physical device inputs to a virtual device. Valid values(listed by system) are:
  • NES
    • gamepad1
    • gamepad2
    • gamepad3
    • gamepad4
    • powerpad1
    • powerpad2
    • ftrainer
  • PC Engine
    • pcegamepad1
    • pcegamepad2
    • pcegamepad3
    • pcegamepad4
    • pcegamepad5

During configuration, pressing the same button twice in a row will cause configuration to move to the next button on the virtual device. A maximum of 4 physical buttons may be assigned to one virtual button.

-nes.input1 x
and
-nes.input2 x		stringgamepadSelect input device for input port 1 or 2. Valid strings are "none", "gamepad", "zapper", "powerpada", and "powerpadb".
-nes.fcexp xstringnoneSelect Famicom expansion port device. Valid strings are "none", "shadow", "arkanoid", "4player", and "fkb".
-nes.nofs xboolean0If value is true, disable four-score emulation.
-nes.gg xboolean0Enable NES Game Genie emulation.
-ffspeed xinteger2Specifies the speed multiplier to be used in fast-forward mode.
-nothrottle xboolean0If value is true, disable the speed throttling that is used when sound emulation is disabled.
-nes.cpalette xstring0Load a custom global NES palette from file "x". To stop using a custom palette:
mednafen -cpalette "" game.nes
-nes.ntsccol xboolean0If value is true, enable automatic generation and use of an NTSC NES' colors.
-nes.pal xboolean0If value is true, emulate a PAL NES. Otherwise emulate an NTSC NES.
-nes.clipsides xboolean0If value is true, clip leftmost and rightmost 8 columns of pixels of the video output.
-nes.slstart xinteger8 First scanline to be rendered in NTSC emulation mode(when PAL emulation is disabled).
-nes.slend xinteger231 Last scanline to be rendered in NTSC emulation mode.
-nes.slstartp xinteger0 First scanline to be rendered in PAL emulation mode.
-nes.slendp xinteger239 Last scanline to be rendered in PAL emulation mode.
-pce.forcesgx xboolean0Force SuperGrafx emulation.
-pce.ocmultiplier xinteger1CPU overclock multiplier.
-pce.nospritelimit xboolean0No 16-sprites-per-scanline limit option.
-pce.cdbios xstringPath to the CD BIOS
-pce.cddaquality xinteger3CD-DA resampler quality, higher is generally better quality, but more CPU intensive. The resampler is not used at all if the sound playback rate is 44100Hz.
  • 0 = Zero order hold
  • 1 = Linear interpolation
  • 2 = Bandlimited interpolator, 80% bandwidth.
  • 3 = Bandlimited interpolator, 90% bandwidth.
  • 4 = Bandlimited interpolator, 97% bandwidth.
-pce.compressor xboolean1Enable audio volume compressor.
Argument:Value Type:Default value:Description:
-connectTrigger to connect to remote host after the game is loaded.
-nethost xstringSet server's hostname to connect to during netplay.
-netport xinteger4046Set port number to connect to on remote host.
-netpassword xstringThe optional password used to connect to a netplay server.
-netlocalplayers xinteger1Set the number of local players on your system during netplay.
-netnick xstringSet nickname used during chat when using netplay.
-vdriver xinteger0Select which video output "driver" to use.
  • 0 = OpenGL + SDL
  • 1 = SDL framebuffer

Bilinear interpolation and Lynx screen rotation are not available with the "SDL framebuffer" driver.
-<system>.videoip xboolean0
PCE: 1		Use bilinear interpolation.
-<system>.scanlines xinteger0If non-zero, enable scanlines; scanline_brightness = 100% - (100% / x)
-<system>.special xstringnoneUse a special video scaling filter applied before OpenGL rasterization. The destination rectangle is NOT altered by this setting, so if you have xscale and yscale set to "2", and try to use a 3x scaling filter like hq3x, the image is not going to look that great. The nearest-neighbor scalers are intended for use with bilinear interpolation enabled, at high resolutions(such as 1280x1024; nn2x(or nny2x) + bilinear interpolation + fullscreen stretching at this resolution looks quite nice).
  • none or 0 (disable special scaler)
  • hq2x
  • hq3x
  • hq4x
  • scale2x
  • scale3x
  • scale4x
  • nn2x (Nearest-neighbor 2x)
  • nn3x (Nearest-neighbor 3x)
  • nn4x (Nearest-neighbor 4x)
  • nny2x (Nearest-neighbor 2x, y axis only)
  • nny3x (Nearest-neighbor 3x, y axis only)
  • nny4x (Nearest-neighbor 4x, y axis only)
-<system>.stretch xboolean0Stretch to fill screen when in fullscreen mode.
-doublebuf xboolean1Request double buffering(note that double buffering or sync-to-vblank may already be forcibly enabled by your video drivers).
-<system>.xscale
(-<system>.xscalefs)
/
-<system>.yscale
(-<system>.yscalefs)		realNES: 2(2)/2(2)
GB: 4(4)/4(4)
GBA: 3(3)/3(3)
Lynx: 4(4)/4(4)
PCE: 3(3)/3(3)		Specify the scaling factor for each axis.
-<system>.xres x
/
-<system>.yres y		integerNES: 640/480
GB: 800/600
GBA: 800/600
Lynx: 640/480
PCE: 1024/768		Set the desired horizontal/vertical resolution when in fullscreen mode.
-fsboolean0Full screen mode.

Game-specific Emulation Hacks

Title:Description:Source code files affected:
KickMaster KickMaster relies on the low-level behavior of the MMC3(PPU A12 low->high transition) to work properly in certain parts. If an IRQ begins at the "normal" time on the last visible scanline(239), the game will crash after beating the second boss and retrieving the item. The hack is simple, to clock the IRQ counter twice on scanline 238. src/nes/boards/mmc3.cpp
Shougi Meikan '92
Shougin Meikan '93		 The hack for these games is identical to the hack for KickMaster. src/nes/boards/mmc3.cpp
Star Wars (PAL/European Version) This game probably has the same(or similar) problem on Mednafen as KickMaster. The hack is to clock the IRQ counter twice on the "dummy" scanline(scanline before the first visible scanline).src/nes/boards/mmc3.c

Credits

Name:Contribution(s):
\Firebug\High-level mapper information.
Andrea MazzoleniScale2x/Scale3x scalers included in Mednafen.
BeroOriginal FCE source code.
Brad TaylorNES sound information.
Charles MacDonaldPC Engine technical information.
EFXTesting.
Fredrik OlsonNES four-player adapter information.
Gilles VollantPKZIP file loading functions.
gorohVarious documents.
Info-ZIPZLIB
Jeremy ChadwickGeneral NES information.
kevtrisLow-level NES information and sound information.
KiVarious technical information.
Mark KnibbsVarious NES information.
Marat FayzullinGeneral NES information.
Matthew ConteSound information.
Maxim Stepinhq2x and hq3x scalers included in Mednafen.
MitsutakaYM2413 emulator.
noriFDS sound information.
QuietustVRC7 sound translation code by The Quietust (quietust at ircN dort org).
rahgaFamicom four-player adapter information.
TheRedEyeROM images, testing.
XodnizelFCE Ultra.
...and everyone whose name my mind has misplaced.