Advance Projects - AdvanceMAME Documentation

Documentation of the AdvanceMAME advmame program.

AdvanceMAME/MESS Emulator

1 Synopsis

advmame GAME [-default] [-remove] [-cfg FILE]
    [-log] [-listxml] [-record FILE] [-playback FILE]
    [-version] [-help]

advmess MACHINE [images...] [-default] [-remove] [-cfg FILE]
    [-log] [-listxml] [-record FILE] [-playback FILE]
    [-version] [-help]

2 Description

AdvanceMAME is an unofficial MAME version for GNU/Linux, Mac OS X, DOS and Windows with an advanced video support for helping the use with TVs, Arcade Monitors, Fixed Frequencies Monitors and also with normal PC Monitors.

The major features are:

Automatic creation of `perfect' video modes with the correct size and clock.
A lot of video boards supported for direct hardware registers programming. (see the card*.txt files)
Support for 8, 15, 16 and 32 bits video modes.
Real hardware scanlines.
Software video image stretching by fractional factors, for example to play vertical games like "Pac-Man" with horizontal Arcade Monitors or TVs.
Special `scale', `lq' and `hq' effects to improve the aspect with modern PC Monitors.
Special `blit' effects to improve the image quality in stretching.
Special `rgb' effects to simulate the aspect of a real Arcade Monitor.
Change of the video mode and other video options at runtime.
Support of Symmetric Multi-Processing (SMP) with a multiple thread architecture (only for Linux).
Sound and video recording in WAV, PNG and MNG files.
Multiple mice support in Linux, DOS, Windows 2000 and Windows XP.
Automatic exit after some time of inactivity.
Scripts capabilities to drive external hardware devices like LCDs and lights.
Textual configuration files.
Help screen describing the user input keys.

The sections of this document are:

3 Keys

In the game play you can use the following keys:

	ESC	Exit.
	F1	Help.
	TAB	Main Menu.
	F2	Test/Service Switch.
	F3	Reset the game.
	F7	Load a game state.
	SHIFT + F7	Save a gam state.
	F8	Decrease the frame skip value.
	F9	Increase the frame skip value.
	F10	Speed throttle.
	F11	Display the frame per second.
	F12	Save a snapshot.
	P	Pause.
	PAD *	Turbo mode until pressed.
	PAD /	Cocktail mode (flip the screen vertically).
	PAD	- Mark the current time as the startup time of the game.
	CTRL + ENTER	Start the sound and video recording.
	ENTER	Stop the sound and video recording.
	,	Previous video mode.
	.	Next video mode.
	TILDE	Volume Menu.

for player 1 you can use the keys:

1 Play.

5 Insert coin.

ARROW Move.

CTRL First button.

ALT Second button.

SPACE Third button.

for player 2 you can use the keys:

2 Play.

6 Insert coin.

R, F, D, G Move.

A First button.

S Second button.

Q Third button.

for AdvanceMESS are available also the following keys:

ScrollLock Switch to partial keyboard emulation which lets you use keys like TAB, ALT and CTRL.

4 Options

This is the list of the available command line options:

GAME/MACHINE

The game or machine to emulate. If the specified GAME/MACHINE is unknown, a list of possible `guesses' is printed.

-default

Add to the configuration file all the missing options with default values.

-remove

Remove from the configuration file all the options with default values.

-cfg FILE

Select an alternate configuration file. In Linux and Mac OS X the you can prefix the file name with "./" to load it from the current directory.

-log

A very detailed log of operations is saved in a `.log' file. Very useful for debugging problems.

-listxml

Outputs the internal MAME database in XML format.

-record FILE

Record all the game inputs in the specified file. The file is saved in the directory specified by the `dir_inp' configuration option.

-playback FILE

Play back the previously recorded game inputs in the specified file.

-version

Print the version number, the low-level device drivers supported and the configuration directories.

-help

Print a short command line help.

On the command line you can also specify all configuration options with the format -OPTION ARGUMENT. For boolean options you don't need to specify the argument but you must use the -OPTION or -noOPTION format. For example:

advmame pacman -device_sound sb -nodisplay_scanlines

You can use short options if they are unambiguous. You can remove any prefix tag separated with `_' or truncate it. For example `-dev_cartdrige' can be written as `-dev_cart', `-cartdrige', `-cart', ...

In Linux and Mac OS X you can also use `--' before options instead of `-'. In DOS and Windows you can also use `/'.

5 Features

This section contains a brief description of all the features of AdvanceMAME.

5.1 Automatic Video Mode Generation

AdvanceMAME has the ability to directly control your video board to get the best possible video modes with always the correct size and aspect ratio.

You can control how the video modes are generated with the `display_adjust' option. More details are in the `install.txt' file.

5.2 Video Menu

AdvanceMAME adds a new `Video' menu in MAME to change the video options.

You can select the desired video mode, the resize type and the video effects.

The selected option is displayed at the right side of the menu, the effective value used for the option is displayed in `[]'.

5.3 Resize

AdvanceMAME supports many software stretching types of the game image. Generally they are not used, because a video mode of the correct size is automatically generated. But in some conditions it isn't possible, in this case the image is stretched.

There are four stretch types: `none', `integer', `mixed', `fractional'. You can control the type of stretching with the `display_resize' option.

The `none' option simply disables any type of stretching. The `integer' option allows only integer stretching in the horizontal and vertical directions. For example 1x2, 2x1, 2x2. The `mixed' option allows integer stretching in the horizontal direction and fractional stretching in the vertical direction. For example 1x1.23, 2x1.18. The `fractional' option allows fractional stretching in any directions. For example 1.08x1.08, 1.34x1.78.

Usually the best choice is the `mixed' option. It's very fast and the image quality doesn't suffer too much.

5.4 Blit Effects

AdvanceMAME supports many special video effects to improve the image quality when it's stretched.

There are a lot of video effects: `none', `max', `mean', `filter', `scale', `lq' and `hq'. You can select the favorite effect with the `display_resizeeffect' option.

The `none' effect simply duplicates and removes rows and lines when the image is stretched. The `max' effect tries to save the image details checking the luminosity of the pixels in stretching. It ensures to have vertical and horizontal lines always of the same thickness. The `mean' effect tries to save the image details displaying the mean color of the pixels in stretching. The `filter' effect applies a generic blur filter computing the mean color in the horizontal and vertical directions. The best results are when the image is stretched almost by a double factor. When the image is enlarged the filter is applied after stretching; when reduced, it's applied before. The `scale', `lq' and `hq' effects add missing pixels trying to match the image patterns.

The `mean' and `filter' effects work only in RGB video modes (not palettized).

The `scale', `lq' and `hq' effects work only if the image is magnified. To enable it you should also use the `magnify' option.

5.5 RGB Effects

AdvanceMAME supports also some special video effects to simulate the aspect of the game as displayed in an old fashion Arcade Monitor.

You can simulate the RGB triads of the screen or the vertical and horizontal scanlines.

5.6 Mode Selection

In the `Video Mode' submenu you can select the favorite video mode.

If you choose `auto', the best video mode is chosen automatically.

You can change the active video mode pressing `,' and `.' when in game play.

You can force a specific video mode with the option `display_mode'.

5.7 Per game/resolution/frequency/orientation options

All the options are customizable in the configuration file for the single game or for a subset of games defined by the game resolution, frequency and orientation.

5.8 Scripts

AdvanceMAME supports a basic script language capable to control an external hardware through the parallel port or keyboard led signals.

More details are in the `script.txt' file.

5.9 Aspect Ratio Control

AdvanceMAME tries always to display the game with the correct aspect ratio.

But if you want, you can permit a small aspect error to enlarge the effective game image on the screen. It's very useful to display vertical games on horizontal monitors and vice versa.

More details are in the description of the `display_expand' option.

5.10 Speed Control

AdvanceMAME permits a special speed control of the game play.

You can play the game in a faster way, change arbitrarily the frame rate, skip the game startup process at the maximum speed, or skip the game animations pressing a key.

Press `asterisk_pad' to enable the `turbo' mode. Press `minus_pad' to mark the time of the real game start. The next time the game is started, it will execute very fast until this time.

More details are in the description of the `sync_fps', `sync_speed', `sync_turbospeed' and `sync_startuptime' options.

The video and audio synchronization uses an advanced algorithm, which ensure always the best performance.

The program continuously measures the time required to compute a frame and continuously adapt the number of frame to skip and to draw.

If it detects that you have system too slow to play the game at full speed, it automatically disables any frame skipping.

If the underline Operand System allows that, AdvanceMAME release the CPU when it isn't used after computing each frame reducing the CPU occupation. For example this happen on Linux 2.6 which has a 3ms delay granularity, but not in Linux 2.4 which has a 20ms granularity.

5.11 Audio Control

The audio volume is automatically adjusted to ensure that all the emulated games have the same volume power.

An equalizer and a spectrum analyzer are also available.

More details are in the description of the `sound_normalize' and `sound_equalizer' options.

5.12 Exit Control

If you have a real Arcade Cabinet you can configure AdvanceMAME to automatically exit after some time of inactivity to save your monitor screen.

For some supported games you can force the display of an exit menu during the game play to prevent unwanted exit.

More details are in the description of the `misc_safequit', and `input_idleexit' options.

5.13 Input Control

AdvanceMAME supports a very fine control of the mapping of the analog and digital inputs. You can remap any input event using easy to maintain text configuration files.

More details are in the description of the `input_map' option.

5.14 Audio and Video Recording

AdvanceMAME can saves the game play in .WAV audio files and .MNG video files.

More details are in the description of the `record_*' options.

5.15 User Interface

AdvanceMAME displays the user interface directly on the screen instead on the game image.

This means that the interface doesn't have applied the same video effects of the game, it isn't limited on the game area, it isn't recorded on video clips and you can customize the font.

Also, True Type fonts with alpha blending are supported.

More details are in the description of the `ui_*' options.

5.16 Input Help

AdvanceMAME is able to display a help image containing the input mapping of the emulated game. Any input element has a different depending on the assigned player and if it's pressed or not.

The default image is a standard keyboard, with the used keys highlighted. If you have an Arcade cabinet you can create your personalized control image and select each region to highlight.

Press `f1' on the game play to display it.

More details are in the description of the `ui_help*' options.

5.17 Input Text Configuration File

All the user customizations are stored in a single textual configuration file and not in a lot of .cfg file like other MAME ports.

This allows to view, edit and copy any customization manually. They are also more compact because only the difference from the default is saved.

They are independent of the internal MAME structure, so, when it changes, you don't lose the customizations.

More details are in the description of the `input_setting', `input_dipswitch', `input_configswitch' options.

5.18 Cocktail

For cocktail arcade cabinets you can manually flip vertically the screen for games without cocktail support.

Press `slash_pad' to flip the screen.

5.19 Dipswitches Control

You can customize with specialized options the game difficulty and the game freeplay. These options are smart enough to solve common ambiguities and errors in the game dipswitches definitions.

More details are in the description of the `misc_diffucilty' and `misc_freeplay' options.

5.20 LCD

AdvanceMAME is able to talk to an `lcdproc' server located anywhere in internet to display arbitrary information on a real or simulated LCD display.

6 Use Cases

This section describes some useful cases for AdvanceMAME on different video hardware.

6.1 With a PC Multi-Sync Monitor

On a PC Multi-Sync monitor you can get any resolution at any Vertical Frequency. In this case AdvanceMAME always generates a `perfect' video mode with the correct size and clock. It doesn't require any type of stretching. For example for the game "Bomb Jack" a video mode of 400x256 at 60 Hz (perfect size and perfect frequency) is used.

6.2 With a PC VGA Monitor/Fixed Frequency Monitor/Arcade Monitor

On Fixed Frequency monitors you are physically limited on the choice of Horizontal Frequency in the video mode. In this case AdvanceMAME takes care of your monitor's limitations and in the most cases is able to use a video mode with the correct size but not with the correct frequency due to the monitor's limitations. For example for the game "Pac-Man" and a VGA monitor (31.5 kHz) a video mode of 400x288 at 100 Hz (perfect size) is used.

6.3 With a NTSC or PAL TV

On a TV you are physically limited to use both fixed Horizontal and Vertical Frequencies. This results on a prefixed number of rows for the video mode. For example for a NTSC TV you can get 240 rows (480 if interlaced) and for a PAL TV 288 rows (576 if interlaced). In this case AdvanceMAME uses a video mode with the prefixed number of rows but with the correct number of columns. So, ONLY a vertical image stretching is required. For example for the game "Pac-Man" on a NTSC TV a video mode of 400x240 (perfect horizontal size) is used. For stretching some special algorithms are used to minimize the lose of details.

6.4 With a Multi-format NTSC and PAL TV

If your TV supports both formats, AdvanceMAME automatically chooses the format that better fits the game requirements. For example for the game "Mr. Do!" a video mode of 336x240 NTSC (perfect size) is used. For the game "Pac-Man" a video mode of 400x288 PAL (perfect size) is used.

7 Other Ports

This section compares the AdvanceMAME video support with the other MAME ports.

7.1 Windows MAME

The official Windows MAME is forced by Windows drivers to select a video mode from a prefixed list of mode sizes and clocks. If the emulated game requires a not standard mode size the emulator must stretch the game image to fit the screen (losing in quality). If the emulated games requires a not standard clock the emulator must play the game without synchronizing with the video vertical retrace (generating the tearing disturb on scrolling game) or display frames for different time (generating a not constant scrolling).

Depending on the type of your video drivers you can sometimes edit the prefixed list of video modes.

The TV support depends on the video drivers of your board and it's generally limited at the interlaced mode 640x480. Arcade monitors are used as NTSC TVs.

Generally this port is limited by Windows to get the best from your monitor.

7.2 DOS MAME

The official DOS MAME is limited to use only the standard VESA resolutions. Generally they are only 320x200, 320x240, 400x300, 512x384, 640x480, ...

The Arcade/TV support is limited at the mode 640x480 for the ATI boards.

7.3 xmame

The xmame port has nearly the same video capabilities of AdvanceMAME. The major drawback is that it requires a manual modeline creation. Instead AdvanceMAME is able to create modelines dynamically.

AdvanceMAME has also some unique features like `scale', `lq', `hq', `filter' and `rgb' effects, turbo mode, scripts, SMP, 8 bit depth and much more.

8 Configuration

In DOS and Windows the configuration options are read from the files `advmame.rc' and `advmess.rc' in the current directory.

In Linux and Mac OS X the configuration options are read from the files `advmame.rc' and `advmess.rc' in the $host, $data and the $home directory. The $host directory is `$SYSCONFDIR', where $SYSCONFDIR is the `sysconfdir' directory configured with the `configure' script. The default is `/usr/local/etc'. The $data directory is `$DATADIR/advance', where $DATADIR is the `datadir' directory configured with the `configure' script. The default is `/usr/local/share'. The $home directory is `$ADVANCE', where $ADVANCE is the value of the ADVANCE environment variable when the program is run. If the ADVANCE environment variable is missing the $home directory is `$HOME/.advance' where $HOME is the value of the HOME environment variable. If both the ADVANCE and HOME environment variables are missing the $data directory became also the $home directory.

The priority of the options is in the order: $host, $home and $data.

The $home directory is also used to write all the information by the program. The files in the $host and $data directory are only read.

You can include an additional configuration files with the `include' option. In DOS and Windows the files are searched in the current directory. In Linux and Mac OS X the files are searched in the $home directory if they are expressed as a relative path. You can force the search in the current directory prefixing the file with `./'. To include more than one file you must divide the names with `;' in DOS and Windows, and with `:' in Linux and Mac OS X.

You can force the creation of a default configuration file with the command line option `-default'.

In the configuration file the options are specified in this format:

[SECTION/]OPTION VALUE

If the SECTION is omitted the `' (empty) section is assumed.

You can split long options in a multi-line format ending the line with the char `\':

[SECTION/]OPTION FIRST_LINE \ SECOND_LINE \ ... \ LAST_LINE

When you run a game every option is read in different sections in the following order:

`SYSTEM[SOFTWARE]' The short system name and the loaded software on the command line, like `ti99_4a[ti-inva]', `a7800[digdug]' and `nes[commando]'.

`GAME' The short game (or system) name, like `pacman', `ti99_4a' and `nes'.

`PARENT' If present, the parent name of the game, like `puckman'.

`BIOS' If present, the bios name of the game, like `neogeo'.

`RESOLUTIONxCLOCK' The resolution and the clock of the game, like `244x288x60' for raster games or `vector' for vector games. If the vertical clock is a real value, it's rounded downwards to the nearest integer.

`RESOLUTION' The resolution of the game, like `244x288' for raster games or `vector' for vector games.

`ORIENTATION' The game orientation. One of `vertical', `horizontal'.

`CONTROLLER' The game input device. One of `joy4way', `joy8way', `doublejoy4way', `doublejoy8way', `paddle', `dial', `trackball', `stick', `lightgun', `mouse'.

`Nplayer' Number of players in the game. One of `1player', `2player', `3player', ...

`' The default empty section.

For example for the game `pacman' the following sections are read: `pacman', `puckman', `224x288x60', `224x288', `vertical', `joy4way', `2player' and `'.

You can override any global options inserting new options in any of the sections of the game.

For example:

display_scanlines no pacman/display_scanlines yes 244x288x60/display_scanlines yes vertical/display_ror yes horizontal/display_ror no

8.1 Software Configuration Options

This section describes the options used to customize the software loaded by system emulated.

8.1.1 dev_*

Loads a specific device for the AdvanceMESS emulator. These options are mainly used on the command line to specify the machine software to load. The file specified is searched in the directory list specified in the `dir_image' option.

dev_COMMAND FILE

Commands:

cartridge Load a cartridge.

floppydisk Load a floppydisk.

harddisk Load an harddisk.

cylinder Load a cylinder.

cassette Load a cassette.

punchcard Load a punchcard.

punchtape Load a punchtape.

printer Load a printer.

serial Load a serial.

parallel Load a parallel.

snapshot Load a snapshot.

quickload Load a quickload.

Examples:

advmess ti99_4a -dev_cartridge attackg.bin advmess ti99_4a -cart alpinerc.bin -cart alpinerg.bin

8.2 Directory Configuration Options

This section describes the options used to customize the directories used by the program.

8.2.1 dir_*

Specify all the support directories. In DOS and Windows use the `;' char as directory separator. In Linux and Mac OS X use the `:' char.

dir_* DIR[;DIR]... (DOS, Windows)
dir_* DIR[:DIR]... (Linux, Mac OS X)

Options:

dir_rom Multi directory specification for the AdvanceMAME `rom' files and AdvanceMESS `bios' files.

dir_image Multi directory specification for the chd/disk/cartdrige/... image files.

dir_diff Multi directory specification for the disk image differential files.

dir_sample Multi directory specification for the zipped `sample' files. Only the zipped format is supported.

dir_artwork Multi directory specification for the zipped `artwork' files. Only the zipped format is supported.

dir_nvram Single directory for `nvram' files.

dir_memcard Single directory for `memcard' files.

dir_hi Single directory for `hi' files.

dir_inp Single directory for `inp' files.

dir_sta Single directory for `sta' files.

dir_snap Single directory for the `snapshot' files.

dir_crc Single directory for the `crc' files.

Defaults for DOS and Windows:

dir_rom rom

dir_image image

dir_diff diff

dir_sample sample

dir_artwork artwork

dir_nvram nvram

dir_memcard memcard

dir_hi hi

dir_inp inp

dir_sta sta

dir_snap snap

dir_crc crc

Defaults for Linux and Mac OS X:

dir_rom $home/rom:$data/rom

dir_image $home/image:$data/image

dir_diff $home/image:$data/diff

dir_sample $home/sample:$data/sample

dir_artwork $home/artwork:$data/artwork

dir_nvram $home/nvram

dir_memcard $home/memcard

dir_hi $home/hi

dir_inp $home/inp

dir_sta $home/sta

dir_snap $home/snap

dir_crc $home/crc

If a not absolute dir is specified, in Linux and Mac OS X it's expanded as "$home/DIR:$data/DIR". In DOS and Windows it's maintained relative.

For the `dir_rom' and `dir_image' the following file combinations are tried:

DIR/GAME/ROM.EXT
DIR/GAME.zip/ROM.EXT
DIR/GAME/ROM.zip/ROM

Where DIR is substituted with the directories specified, GAME is the name of the game or machine emulated, ROM is the rom name and EXT is the rom extension.

For the files searched in the `dir_image' option you can also specify a different zip name prefixing the rom name with the zip name without extension and the `=' char. For example to run the `ti99_4a' emulator and load the cartdriges `alpinerc.bin' and `alpinerg.bin' both contained in the zip file `alpiner.zip' you can use this syntax:

advmess ti99_4a -cart alpiner=alpinerc.bin -cart alpiner=alpinerg.bin

This feature is used automatically by AdvanceMENU to correctly run AdvanceMESS software in zip files.

8.3 Display Configuration Options

This section describes the options used to customize the display.

8.3.1 device_video_*

These options are used to customize the video drivers.

All the `device_video_*' options described in the `advdev.txt' file can be used.

If you use a `System' video driver, you don't need to set these options. They are mostly ignored.

With a `Generate' video drivers these options are used to select and create the correct video mode. They are mandatory. You can use the `advcfg' utility to set them interactively.

8.3.2 display_mode

Selects a specific modeline by its name.

display_mode auto | MODELINE_NAME

Options:

MODELINE_NAME Specific modeline, as named with the `advv' utility.

auto Automatically chooses the best modeline available (default).

8.3.3 display_adjust

Controls how are generate the video modes. Correct use of this option removes the need of any software stretching improving a lot the game image.

For an introduction on how the program operates on video mode, you can see the `install.txt' file.

display_adjust none | x | clock | xclock | generate_exact
    | generate_y | generate_clock | generate_clocky
    | generate_yclock

Options:

none No automatic video mode creation. Use only the available modelines (default).

x Adjusts the available modeline horizontal resolution to match the game image's size. The stretched modeline keeps all the clock attributes of the original modeline. Also all other modeline attributes, like doublescan and interlace, are maintained.

clock Adjusts the available modeline's vertical clock to match the game's frame rate.

xclock Adjusts the available modeline's horizontal resolution and the vertical clock.

generate_exact Creates automatically some new modelines using the format specified on the `device_video_format' option. The generated modelines will be named `generate-*'. Check the `advdef.txt' file for the description of the `device_video_format' option or simply use the `advcfg' utility to set it up correctly. If the `device_video_format' option isn't specified a default value for your monitor clock limits is guessed.

generate_y Like generate_exact, and it allows generating modes with a wrong vertical size if a perfect mode is not possible.

generate_clock Like generate_exact, and it allows generating modes with a vertical clock different than the game original clock if a perfect mode is not possible.

generate_yclock Like generate_exact, and it allows generating modes with a wrong vertical clock and/or size if a perfect mode is not possible. Modes with a correct size are favorite over mode than a correct clock.

generate_clocky Like generate_exact, and it allows generating modes with a wrong vertical clock and/or size if a perfect mode is not possible. Modes with a correct clock are favorite over mode with a correct size.

The `generate' options are able to create at runtime all the required modelines. You don't need to create a list of modelines manually.

The not `generate' options use only the modelines defined with the `device_video_modeline' option in the configuration file. You can add them manually or using the `advv' utility. Check the `advdev.txt' file for more details on the `device_video_modeline' option.

Of all the `generate' options, the `generate_yclock' is the suggested and the most powerful. The `advcfg' utility always sets the `generate_yclock' option in your configuration file.

Of all the not `generate' options, the `xclock' is the suggested and the most powerful.

If you can't get good result with the `generate' options you should create a list of modelines and try with the `xclock' value. You don't need to duplicate the same modeline with different horizontal resolutions and/or the clocks, because the `xclock' value allows the program to adjust them. Instead, you should create a wide set of different vertical resolutions on which the video mode can be chosen. A good choice is to create all the resolutions with a step of 16 rows.

8.3.4 display_color

Controls the color format of the video mode.

display_color auto | palette8 | bgr8 | bgr15 | bgr16 | bgr32 | yuy2

Options:

auto Automatically choose the best option.

palette8 Palettized 8 bits mode.

bgr8 RGB 8 bits mode.

bgr15 RGB 15 bits mode.

bgr16 RGB 16 bits mode.

bgr32 RGB 32 bits mode.

yuy2 YUV mode in the YUY2 format.

Note that the 24 bit color mode isn't supported.

The modes are called bgr because in the video memory the order of the color channel is: Blue, Green, Red.

8.3.5 display_resize

Suggests the favorite image stretching when a video mode with the correct size isn't available. This option doesn't have any effect for vector games, they are always stretched to fit the whole screen.

display_resize none | integer | mixed | fractional

Options:

none Original size.

integer Integer stretch, i.e. x2, x3, x4,...

mixed Integer horizontal stretch and fractional vertical stretch.

fractional Fractional stretch (default).

The `fractional' option involves a slowdown, so the `mixed' option is the default.

Examples:

display_resize mixed

8.3.6 display_magnify

Suggests the use of a double or bigger resolution video mode. It is mainly used to enable the `scale', `lq' and `hq' effects. This option doesn't have any effect for vector games.

display_magnify auto | 1 | 2 | 3 | 4

Options:

auto Double or triplicate the size if the resulting video mode width is smaller than 512 pixels.

1 Normal size (default).

2 Double size.

3 Triple size.

4 Quadruple size.

8.3.7 display_scanlines

Suggests the use of hardware scanlines when choosing the video mode.

display_scanlines yes | no

Options:

yes Try to select a singlescan video mode.

no Try to select a doublescan video mode (default).

8.3.8 display_buffer

Activates the video image buffering.

display_buffer yes | no

Options:

no Doesn't use any buffering (default).

yes Use the best buffering available.

8.3.9 display_vsync

Synchronizes the video display with the video beam instead of using the CPU timer. This option can be used only if the selected video mode has an appropriate refresh rate. To ensure this you can use the option `display_adjust' to allow a clock correction of the video mode.

display_vsync yes | no

Options:

no Use the timer.

yes Use the video refresh rate (default).

You can enable or disable it also on the runtime Video menu.

8.3.10 display_restore

Selects whether or not to reset to default text mode at the emulator exit.

display_restore yes | no

Options:

yes Resets to text mode (default).

no Doesn't change the video mode.

8.3.11 display_frameskip

Skips frames to speed up the emulation.

display_frameskip auto | FACTOR

Options:

auto Auto frame skip (default).

FACTOR Float factor for the fraction of frames to display. From 0 to 1. To completely disable the frame skipping use the value 1.

Use `f11' to display the speed your computer is actually reaching. If it is below 100%, increase the frame skip value. You can press `f8/f9' to change frame skip while running the game. When set to auto (default), the frame skip setting is dynamically adjusted during runtime to display the maximum possible frames without dropping below the 100% speed. Pressing `f10' you can enable and disable the throttle synchronization.

Examples:

display_frameskip 0.5

8.4 Display Aspect Configuration Options

This section describes the options used to customize the display aspect.

8.4.1 display_expand

Enlarges the screen area used by the vertical games on horizontal monitors (and horizontal games in vertical monitors).

display_expand FACTOR

Options:

FACTOR Expansion float factor from 1.0 to 2.0 (default 1.0).

Examples:

display_expand 1.15

8.4.2 display_aspectx/aspecty

Selects the aspect of the monitor used.

display_aspectx INT
display_aspecty INT

Options:

INT Integer number starting from 1 (default 4 and 3).

For 16/9 TV you can use the 16 and 9 values. For truly vertical monitors (not horizontal monitors rotated) you can simply swap the values, for example 3 and 4 instead of 4 and 3.

Examples:

display_aspectx 16 display_aspecty 9

8.4.3 display_ror/rol/flipx/flipy

Flips and rotates the game image.

display_ror yes | no
display_rol yes | no
display_flipx yes | no
display_flipy yes | no

Examples:
To rotate left vertical games:

vertical/display_rol yes

8.4.4 display_skiplines/skipcolumns

Selects the centering of the visible area.

display_skiplines auto | SKIPLINES
display_skipcolumns auto | SKIPCOLUMNS

Options:

auto Auto center (default).

SKIPLINES Lines to skip.

SKIPCOLUMNS Columns to skip.

8.5 Display Effect Configuration Options

This section describes the options used to customize the display effects.

8.5.1 display_resizeeffect

When a video mode is smaller or bigger than the original arcade screen, the `resizeeffect' option controls the type of the transformation applied.

display_resizeeffect auto | none | max | mean | filter
    | scale | lq | hq

Options:

auto Selects automatically the best effect (default). This selection is list based, and may be incomplete. If the scale factor is 2, 3 o 4 the `scale' effect is selected. On the other cases the `mean' or `max' effect is selected.

none Simply removes or duplicates lines as required.

max In reduction merges consecutive columns and rows using the lightest pixels versus the darkest. In expansion duplicate columns and rows using the darkest pixels versus the lightest. Supported in both rgb and palette video modes. It works best for the games with black background or without scrolling. Like "Pac-Man". This effect ensures to have always rows and columns of the same thickness.

mean In reduction it merges columns and rows using the mean color of the pixels. In expansion it adds columns and rows that are the mean of previous and next lines. Supported only in rgb video modes. It works best for the games with animated or scrolling background. Like "1941".

filter It removes or duplicates columns and rows with a low pass filter in the x and the y directions. It's a simple FIR filter with two points of equal value. Supported only in rgb video modes.

scale It adds the missing pixels matching the original bitmap pattern. It doesn't interpolate pixels and it compares colors for equality. If works only for expansion factor of 2, 3 and 4.

lq It adds the missing pixels matching the original bitmap pattern. It uses a deeper analysis than `scale'. It interpolates pixels and it compares colors for equality. It works only for expansion factor of 2, 3 and 4, and only in rgb modes at 15, 16 and 32 bits per pixel.

hq It adds the missing pixels matching the original bitmap pattern. It uses a deeper analysis than `scale'. It interpolates pixels and it compares colors for distance. It works only for expansion factor of 2, 3 and 4, and only in rgb modes at 15, 16 and 32 bits per pixel.

8.5.2 display_rgbeffect

Selects a special effect to simulate the aspect of an Arcade Monitor with a PC monitor. The resulting image is better when you use a big video mode. These effects require a RGB video mode, they don't work with palettized or YUV modes.

display_rgbeffect none | triad3dot | triad6dot
    | triad16dot | triadstrong3dot | triadstrong6dot
    | triadstrong16dot | scan2vert | scan3vert
    | scan2horz | scan3horz.

Options:

none No effect (default).

triad3dot RGB triad of 3 pixels.

triad6dot RGB triad of 6 pixels.

triad16dot RGB triad of 16 pixels.

triadstrong3dot RGB strong triad of 3 pixels.

triadstrong6dot RGB strong triad of 6 pixels.

triadstrong16dot RGB strong triad of 16 pixels.

scan2vert Scanline of 2 vertical lines.

scan3vert Scanline of 3 vertical lines.

scan2horz Scanline of 2 horizontal lines.

scan3horz Scanline of 3 horizontal lines.

8.5.3 display_interlaceeffect

Selects some special effects for interlaced video modes. On not interlaced modes the effects are always disabled.

display_interlaceeffect none | even | odd | filter

Options:

none No effect (default).

even Swap the even rows.

odd Swap the odd rows.

filter Apply a vertical filter.

If your monitor uses a swapped order for interlaced rows, using the `even' or `odd' effect you can probably fix the image.

The effects operate on the rows in the following way:

Row Even Odd Filter A A A A B B A B+A C A C C+B D D B D+C E C E E+D F F D F+E G E G G+F H H F H+G

8.5.4 Display Color Configuration Options

This section describes the options used to customize the display color adjustments.

8.5.5 display_brightness

Selects the image brightness factor.

display_brightness FACTOR

Options:

FACTOR Brightness float factor (default 1.0).

8.5.6 display_gamma

Sets the image gamma correction factor.

display_gamma FACTOR

Options:

FACTOR Gamma float factor (default 1.0).

8.5.7 display_pausebrightness

Selects the brightness of the display when game is paused.

display_pausebrightness FACTOR

Options:

FACTOR Float brightness factor. From 0.0 to 1.0 (default 1.0).

Examples:

display_pausebrightness 0.6

8.6 Display Artwork Configuration Options

This section describes the options used to customize the display artwork.

8.6.1 display_artwork_backdrop/overlay/bezel

Enables or disables the artworks display.

display_artwork_backdrop yes | no
display_artwork_overlay yes | no
display_artwork_bezel yes | no

Options:

yes Enables the artwork (default for backdrop and overlay).

no Doesn't display the artwork (default for bezel).

8.6.2 display_artwork_crop

Crops the artwork at the game size.

display_artwork_crop yes | no

Options:

yes Crops the artwork (default).

no Doesn't crop the artwork.

8.7 Display Vector Configuration Options

This section describes the options used to customize the display of vector games.

8.7.1 display_antialias

Enables or disables the anti-aliasing for vector games.

display_antialias yes | no

Options:

yes Anti-aliasing enabled (default)

no Anti-aliasing disabled.

8.7.2 display_beam

Sets width in pixels of vectors.

display_beam SIZE

Options:

SIZE A float in the range of 1.0 through 16.0 (default 1.0).

8.7.3 display_flicker

Makes vectors flicker.

display_flicker FACTOR

Options:

FACTOR A float in the range 0.0 - 100.0 (default 0).

8.7.4 display_translucency

Enables or disables vector translucency.

display_translucency yes | no

8.7.5 display_intensity

Sets the vector intensity.

display_intensity FACTOR

Options:

FACTOR A float in the range 0.5 - 3.0 (default 1.5).

8.8 Sound Configuration Options

This section describes the options used to customize the sound.

8.8.1 device_sound_*

These options are used to customize the audio drivers.

All the `device_sound_*' options defined in the `advdev.txt' file can be used.

8.8.2 sound_mode

Sets the sound output mode.

sound_mode auto | mono | stereo | surround

Options:

auto Use mono if the emulated game is mono or stereo if it's stereo (default).

mono Use always mono. The game stereo channels are mixed.

stereo Use always stereo. The game mono channel is duplicated.

surround Use a fake surround effect. With stereo games the right channel plays part of the left channel as negate samples and vice-versa. With mono games the left channel is the negation of the right channel. This means that with surround enabled the output is always stereo. If you use mono headphones, the effect will not work and you will hear silence or an attenuated sound.

8.8.3 sound_samplerate

Sets the audio sample rate.

sound_samplerate RATE

Options:

RATE Sample rate. Common values are 11025, 22050, 44100 and 48000 (default 44100).

If the sound driver doesn't support the specified sample rate a different value is selected.

8.8.4 sound_volume

Sets the global sound volume.

sound_volume VOLUME

Options:

VOLUME The volume attenuation in dB (default -3). The attenuation is a negative value from -40 to 0.

Examples:

sound_volume -5

8.8.5 sound_adjust

Sets the sound gain volume. This option can be used to adjust the volume of some games to have all the games with the same volume. If the `sound_normalize' option is active this value is also automatically updated in the game play and you cannot change it manually.

sound_adjust auto | VOLUME

Options:

auto Get the value for the current game from an internal database.

VOLUME The volume gain in dB (default 0). The gain is a positive value from 0 to 40. If the `sound_normalize' option is active the volume is automatically updated in the game play.

Examples:

sound_adjust 16

8.8.6 sound_normalize

Automatically increases and decreases the sound volume.

sound_normalize yes | no

Precisely, the program continously measures the normalized sound power adjusting it with the Fletcher-Munson "Equal Loudness Courve" at 80 dB to remove inaudible frequencies. It tries to keep constant the 95% median power of the last 3 minutes.

For more details check:

http://replaygain.hydrogenaudio.org/equal_loudness.html

Options:

yes Enable the volume normalization (default).

no Disable it.

8.8.7 sound_equalizer_*

Sets the equalizer volume. To disable the equalizer set all the VOLUME values to 0. The cut-off frequencies are 800 and 8000 Hz.

sound_equalizer_lowvolume VOLUME sound_equalizer_midvolume VOLUME sound_equalizer_highvolume VOLUME

Options:

VOLUME The volume gain in dB (default 0). The gain is a integer value from -20 to 20.

8.8.8 sound_latency

Sets the minimum audio latency.

sound_latency TIME

Options:

TIME Latency in seconds from 0 to 2.0 (default 0.05).

If in the game play you hear some sound ticks you can try to increase the latency. Try doubling the value until the ticks go away.

8.9 Input Configuration Options

This section describes the options used to customize the user input.

8.9.1 device_keyboard/joystick/mouse_*

These options are used to customize the input drivers.

All the `device_keyboard/joystick/mouse_*' options defined in the `advdev.txt' file can be used.

8.9.2 input_steadykey

Helps recognition of very long key sequences. But slows a bit the key recognition.

input_steadykey yes | no

Options:

no Standard key recognition (default).

yes Wait until the keyboard state is stabilized before report any key change.

8.9.3 input_hotkey

Enables or disables the recognition of the special OS keyboard sequences.

input_hotkey yes | no

Options:

no No hot key recognition.

yes Hot key recognition (default).

In DOS the hotkey recognized are:

CTRL+ALT+DEL Reset.

CTRL+ALT+END Quit.

CTRL+BREAK (Pause) Break.

In Linux the hotkey recognized generally are:

CTRL+C Break.

ALT+Fx Change virtual console.

8.9.4 input_idleexit

Activates the automatic exit after some time of inactivity.

input_idleexit TIME

Options:

TIME Number of seconds to wait, if 0 (default) never exits automatically.

8.9.5 input_map[ANALOG]

Changes the analog control mapping. Maps joystick, trackball and mouse controls on a player analog control.

input_map[ANALOG] auto | [[-]joystick[JOY,CONTROL,AXE]]
    [[-]mouse[MOUSE,AXE]] [[-]joystick_ball[JOY,AXE]] ...

The default is always `auto'.

Options:

ANALOG Player analog control. One of: p1_paddlex, p2_paddlex, p3_paddlex, p4_paddlex, p1_paddley, p2_paddley, p3_paddley, p4_paddley, p1_stickx, p2_stickx, p3_stickx, p4_stickx, p1_sticky, p2_sticky, p3_sticky, p4_sticky, p1_stickz, p2_stickz, p3_stickz, p4_stickz, p1_lightgunx, p2_lightgunx, p3_lightgunx, p4_lightgunx, p1_lightguny, p2_lightguny, p3_lightguny, p4_lightguny, p1_pedalgas, p2_pedalgas, p3_pedalgas, p4_pedalgas, p1_pedalbrake, p2_pedalbrake, p3_pedalbrake, p4_pedalbrake, p1_pedalother, p2_pedalother, p3_pedalother, p4_pedalother, p1_dialx, p2_dialx, p3_dialx, p4_dialx, p1_dialy, p2_dialy, p3_dialy, p4_dialy, p1_trackballx, p2_trackballx, p3_trackballx, p4_trackballx, p1_trackbally, p2_trackbally, p3_trackbally, p4_trackbally, p1_mousex, p2_mousex, p3_mousex, p4_mousex, p1_mousey, p2_mousey, p3_mousey, p4_mousey.

- Invert the direction of the movement.

JOY Number of physical joystick: 0, 1, 2, 3, ...

MOUSE Number of physical mouse: 0, 1, 2, 3, ...

CONTROL Number or name of physical control of the joystick: 0, 1, 2, 3, ...

AXE Number or name of physical axe of the control: 0, 1, 2, 3 ...

The `joystick' option is used to reference all the analog controls which report an absolute position. For example stick, lightgun, steering wheel, pedal, throttle and rudder controls.

The `joystick_ball' and `mouse' options are used to reference all the analog controls which reports a relative position. For example trackball, dial and mouse controls. The option `joystick_ball' is for joystick devices which have other relative analog controls. The option `mouse' is for mouse devices which have only relative analog controls.

The exact CONTROL and AXE names can be checked interactively using the `advj' and `advm' utility. `advj' is used for `joystick[]' and `joystick_ball[]' specifications. `advm' is used for `mouse[]' specifications.

The CONTROL names for the `joystick' option are:

stick Stick.

gas Acceleration pedal.

brake Brake pedal.

wheel Steering wheel.

hat, hat2, hat3, hat4 Hats.

throttle Throttle.

rudder Rudder.

misc Any other.

The AXE names for the `joystick' option are:

x, y, z Movement on the X, Y, Z axe.

rx, ry, rz Rotation on the X, Y, Z axe.

mono For all the control with a single axe.

The AXE names for the `joystick_ball' and `mouse' options are:

x, y, z Movement on the X, Y, Z axe.

wheel Vertical wheel.

hwheel Horizontal wheel.

dial Dial.

misc Any other.

The ANALOG controls are always formed with a "player" string and with a "control" strings.

p1_CONTROL Player 1.

p2_CONTROL Player 2.

p3_CONTROL Player 3.

p4_CONTROL Player 4.

PLAYER_paddlex Paddle in horizontal direction.

PLAYER_paddley Paddle in vertical direction.

PLAYER_stickx Stick in horizontal direction.

PLAYER_sticky Stick in vertical direction.

PLAYER_stick_z Stick in z axis direction.

PLAYER_lightgunx Lightgun in horizontal direction.

PLAYER_lightguny Lightgun in vertical direction.

PLAYER_pedalgas Gas pedal.

PLAYER_pedalbrake Brake pedal.

PLAYER_pedalother Other pedal.

PLAYER_dialx Dial in horizontal direction.

PLAYER_dialy Dial in vertical direction.

PLAYER_trackballx Trackball in horizontal direction.

PLAYER_trackbally Trackball in vertical direction.

PLAYER_mousex Mouse in horizontal direction.

PLAYER_mousey Mouse in vertical direction.

Examples:

input_map[p1_stickx] joystick[0,0,x] -joystick[0,1,x] input_map[p1_sticky] joystick[0,0,y] -joystick[0,1,y] input_map[p1_trackballx] mouse[0,x] -mouse[1,x] input_map[p1_trackbally] mouse[0,y] -mouse[1,y]

If required you can compose the options to get a rotation of 45° of the control. For example:

input_map[p1_stickx] mouse[0,x] mouse[0,y] input_map[p1_sticky] mouse[0,x] -mouse[0,y]

8.9.6 input_map[DIGITAL]

Changes the digital control mapping. Maps a sequence of keyboard/mouse/joystick keys on a player button or analog simulation digital control.

input_map[DIGITAL] auto | keyboard[KEYBOARD,KEY]
    | mouse_button[MOUSE,MOUSE_BUTTON] | joystick_button[JOY,JOY_BUTTON]
    | joystick_digital[JOY,CONTROL,AXE,DIR]
    | or | not | ...

The default is always `auto' which uses the standard mapping. The previous mapping is always overwritten.

Options:

DIGITAL Player button, analog simulation, digital or keyboard control.

KEYBOARD Number of physical keyboard: 0, 1, 2, 3, ...

KEY Name of physical key.

MOUSE Number of physical mouse: 0, 1, 2, 3, ...

MOUSE_BUTTON Number or name of a physical mouse button: 0, 1, 2, 3, ...

JOY Number of physical joystick: 0, 1, 2, 3, ...

CONTROL Number or name of physical control of the joystick: 0, 1, 2, 3, ...

DIR Direction of the movement: left, up, right, down.

AXE Number or name of physical axe of the control: 0, 1, 2, 3, ...

JOY_BUTTON Number or name of a physical joystick button: 0, 1, 2, 3, ...

or Or operand.

not Not operand.

auto Use the default mapping.

The DIGITAL controls are:
p1_up, p2_up, p3_up, p4_up, p1_down, p2_down, p3_down, p4_down, p1_left, p2_left, p3_left, p4_left, p1_right, p2_right, p3_right, p4_right, p1_doubleright_up, p2_doubleright_up, p3_doubleright_up, p4_doubleright_up, p1_doubleright_down, p2_doubleright_down, p3_doubleright_down, p4_doubleright_down, p1_doubleright_left, p2_doubleright_left, p3_doubleright_left, p4_doubleright_left, p1_doubleright_right, p2_doubleright_right, p3_doubleright_right, p4_doubleright_right, p1_doubleleft_up, p2_doubleleft_up, p3_doubleleft_up, p4_doubleleft_up, p1_doubleleft_down, p2_doubleleft_down, p3_doubleleft_down, p4_doubleleft_down, p1_doubleleft_left, p2_doubleleft_left, p3_doubleleft_left, p4_doubleleft_left, p1_doubleleft_right, p2_doubleleft_right, p3_doubleleft_right, p4_doubleleft_right, p1_button1, p2_button1, p3_button1, p4_button1, p1_button2, p2_button2, p3_button2, p4_button2, p1_button3, p2_button3, p3_button3, p4_button3, p1_button4, p2_button4, p3_button4, p4_button4, p1_button5, p2_button5, p3_button5, p4_button5, p1_button6, p2_button6, p3_button6, p4_button6, p1_button7, p2_button7, p3_button7, p4_button7, p1_button8, p2_button8, p3_button8, p4_button8, p1_button9, p2_button9, p3_button9, p4_button9, p1_button10, p2_button10, p3_button10, p4_button10, p1_paddle_left, p1_paddle_right, p2_paddle_left, p2_paddle_right, p3_paddle_left, p3_paddle_right, p4_paddle_left, p4_paddle_right, p1_paddle_up, p1_paddle_down, p2_paddle_up, p2_paddle_down, p3_paddle_up, p3_paddle_down, p4_paddle_up, p4_paddle_down, p1_stick_left, p1_stick_right, p2_stick_left, p2_stick_right, p3_stick_left, p3_stick_right, p4_stick_left, p4_stick_right, p1_stick_up, p1_stick_down, p2_stick_up, p2_stick_down, p3_stick_up, p3_stick_down, p4_stick_up, p4_stick_down, p1_stick_forward, p1_stick_backward, p2_stick_forward, p2_stick_backward, p3_stick_forward, p3_stick_backward, p4_stick_forward, p4_stick_backward, p1_lightgun_left, p1_lightgun_right, p2_lightgun_left, p2_lightgun_right, p3_lightgun_left, p3_lightgun_right, p4_lightgun_left, p4_lightgun_right, p1_lightgun_up, p1_lightgun_down, p2_lightgun_up, p2_lightgun_down, p3_lightgun_up, p3_lightgun_down, p4_lightgun_up, p4_lightgun_down, p1_pedalgas_push, p1_pedalgas_release, p2_pedalgas_push, p2_pedalgas_release, p3_pedalgas_push, p3_pedalgas_release, p4_pedalgas_push, p4_pedalgas_release, p1_pedalbrake_push, p1_pedalbrake_release, p2_pedalbrake_push, p2_pedalbrake_release, p3_pedalbrake_push, p3_pedalbrake_release, p4_pedalbrake_push, p4_pedalbrake_release, p1_pedalother_push, p1_pedalother_release, p2_pedalother_push, p2_pedalother_release, p3_pedalother_push, p3_pedalother_release, p4_pedalother_push, p4_pedalother_release, p1_dial_left, p1_dial_right, p2_dial_left, p2_dial_right, p3_dial_left, p3_dial_right, p4_dial_left, p4_dial_right, p1_dial_up, p1_dial_down, p2_dial_up, p2_dial_down, p3_dial_up, p3_dial_down, p4_dial_up, p4_dial_down, p1_trackball_left, p1_trackball_right, p2_trackball_left, p2_trackball_right, p3_trackball_left, p3_trackball_right, p4_trackball_left, p4_trackball_right, p1_trackball_up, p1_trackball_down, p2_trackball_up, p2_trackball_down, p3_trackball_up, p3_trackball_down, p4_trackball_up, p4_trackball_down, p1_mouse_left, p1_mouse_right, p2_mouse_left, p2_mouse_right, p3_mouse_left, p3_mouse_right, p4_mouse_left, p4_mouse_right, p1_mouse_up, p1_mouse_down, p2_mouse_up, p2_mouse_down, p3_mouse_up, p3_mouse_down, p4_mouse_up, p4_mouse_down, start1, start2, start3, start4, coin1, coin2, coin3, coin4, coin5, coin6, coin7, coin8, bill1, service_coin1, service_coin2, service_coin3, service_coin4, service_coin5, service_coin6, service_coin7, service_coin8, service, tilt, interlock, p1_start, p2_start, p3_start, p4_start, p1_select, p2_select, p3_select, p4_select, ui_mode_next, ui_mode_pred, ui_record_start, ui_record_stop, ui_turbo, ui_cocktail, ui_help, ui_startup, ui_configure, ui_on_screen_display, ui_pause, ui_reset_machine, ui_show_gfx, ui_frameskip_dec, ui_frameskip_inc, ui_throttle, ui_show_fps, ui_snapshot, ui_toggle_cheat, ui_up, ui_down, ui_left, ui_right, ui_select, ui_cancel, ui_pan_up, ui_pan_down, ui_pan_left, ui_pan_right, ui_show_profiler, ui_toggle_ui, ui_toggle_debug, ui_save_state, ui_load_state, ui_add_cheat, ui_delete_cheat, ui_save_cheat, ui_watch_value, ui_edit_cheat, ui_toggle_crosshair, safequit, event1, event2, event3, event4, event5, event6, event7, event8, event9, event10, event11, event12, event13, event14, key_q, key_w, key_e, key_r, key_t, key_y, key_u, key_i, key_o, key_p, key_a, key_s, key_d, key_f, key_g, key_h, key_j, key_k, key_l, key_z, key_x, key_c, key_v, key_b, key_n, key_m, key_pad_0, key_pad_1, key_pad_2, key_pad_3, key_pad_4, key_pad_5, key_pad_6, key_pad_7, key_pad_8, key_pad_9, key_pad_enter, key_pad_minus, key_pad_plus, key_pad_slash, key_pad_colon, key_pad_diesis, key_pad_asterisk, key_0, key_1, key_2, key_3, key_4, key_5, key_6, key_7, key_8, key_9, key_esc, key_enter, key_backspace, key_tab, key_space, key_ins, key_del, key_home, key_end, key_fctn, key_restore, key_store, key_play, key_print, key_hold, key_rew, key_record, key_break, key_graph, key_pause, key_menu, key_stop, key_again, key_undo, key_move, key_copy, key_open, key_edit, key_paste, key_find, key_cut, key_help, key_back, key_forward, key_capslock, key_scrlock, key_numlock, key_quickload, key_pgup, key_pgdn, key_backquote, key_minus, key_plus, key_asterisk, key_equals, key_openbrace, key_closebrace, key_semicolon, key_quote, key_backslash, key_less, key_comma, key_period, key_slash, key_colon, key_pound, key_doublequote, key_diesis, key_lshift, key_rshift, key_lctrl, key_rctrl, key_lalt, key_ralt, key_ctrl, key_alt, key_shift, key_left, key_right, key_up, key_down, key_f1, key_f2, key_f3, key_f4, key_f5, key_f6, key_f7, key_f8, key_f9, key_f10, key_f11, key_f12, key_f13, key_f14, key_f15, key_f16, key_f17, key_f18, key_f19, key_f20, key_f21, key_f22, key_f23, key_f24.

Note that the p*_start, p*_select and key_* controls are avaiable only in MESS.

The MOUSE_BUTTON names can be checked using the `advm' utility. Generally they are:

left, right, middle Standard buttons.

side Side button.

extra Extra button.

forward Forward button.

back Back button.

fourth, fifth, sixth Misc buttons.

The KEY names can be checked using the `advk' utility. Generally they are:
a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, n0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0_pad, 1_pad, 2_pad, 3_pad, 4_pad, 5_pad, 6_pad, 7_pad, 8_pad, 9_pad, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, esc, backquote, minus, equals, backspace, tab, openbrace, closebrace, enter, semicolon, quote, backslash, less, comma, period, slash, space, insert, del, home, end, pgup, pgdn, left, right, up, down, slash_pad, asterisk_pad, minus_pad, plus_pad, period_pad, enter_pad, prtscr, pause, lshift, rshift, lcontrol, rcontrol, lalt, ralt, lwin, rwin, menu, scrlock, numlock, capslock, stop, again, props, undo, front, copy, open, paste, find, cut, help, calc, setup, sleep, wakeup, file, sendfile, deletefile, xfer, prog1, prog2, www, msdos, coffee, direction, cyclewindows, mail, bookmarks, computer, back, forward, closecd, ejectcd, ejectclosecd, nextsong, playpause, previoussong, stopcd, record, rewind, phone, iso, config, homepage, refresh, exit, move, edit, scrollup, scrolldown, leftparen_pad, rightparen_pad, intl1, intl2, intl3, intl4, intl5, intl6, intl7, intl8, intl9, lang1, lang2, lang3, lang4, lang5, lang6, lang7, lang8, lang9, playcd, pausecd, prog3, prog4, suspend, close, brightnessdown, brightnessup, macro, mute, volumedown, volumeup, power, compose, f13, f14, f15, f16, f17, f18, f19, f20, f21, f22, f23, f24.

You can also specify a numerical scancode N in the form: `scanN'.

The JOY_BUTTON button names can be checked using the `advj' utility. Generally they are:

trigger Joystick trigger button.

top, top2 Joystick top buttons.

thumb, thumb2 Joystick thumb buttons.

pinkie Joystick pinkie button.

base, base2, base3, base4, base5, base6 Joystick base buttons.

dead Joystick dead button.

a, b, c, x, y, z GamePad buttons.

tl, tr, tl2, tr2 GamePad top (left/right) buttons.

thumbl thumbr GamePad thumb (left/right) buttons.

select, start, mode GamePad extra buttons.

gear_up, gear_down Wheel gear buttons.

left, right, middle Ball standard buttons.

side Ball side button.

extra Ball extra button.

forward Ball forward button.

back Ball back button.

fourth, fifth, sixth Ball misc buttons.

0, 1, 2, 3, 4, 5, 6, 7, 8, 9 Misc buttons.

Examples:

input_map[p1_left] keyboard[0,left] or joystick_digital[0,stick,x,left] input_map[p1_right] keyboard[0,right] or joystick_digital[0,stick,x,right] input_map[p1_button1] keyboard[0,lshit] or joystick_button[0,trigger]

8.9.7 input_name

Changes the display name of the specified digital input.

input_name (keyboard[KEYBOARD,KEY]
    | mouse_button[MOUSE,MOUSE_BUTTON]
    | joystick_button[JOY,JOY_BUTTON]
    | joystick_digital[JOY,CONTROL,AXE,DIR])
    NAME

Options:

KEY Name of physical key.

MOUSE Number of physical mouse: 0, 1, 2, 3, ...

MOUSE_BUTTON Number or name of a physical mouse button: 0, 1, 2, 3, ...

JOY Number of physical joystick: 0, 1, 2, 3, ...

CONTROL Number or name of physical control of the joystick: 0, 1, 2, 3, ...

DIR Direction of the movement: left, up, right, down.

AXE Number or name of physical axe of the control: 0, 1, 2, 3, ...

JOY_BUTTON Number or name of a physical joystick button: 0, 1, 2, 3, ...

NAME Display name for digital input.

See input_map for valid KEY, MOUSE_BUTTON, CONTROL, JOY_BUTTON names.

Examples:

input_name keyboard[0,lcontrol] Blue input_name joystick_digital[0,stick,x,right] Right

8.9.8 input_setting[*]

Selects some additional settings for analog inputs. These settings can be modified using the "Analog Config" menu present if the game has analog controls.

input_setting[NAME] SETTING

8.9.9 input_dipswitch[*]

Selects the state of the game dipswitch. These settings can be modified using the "Dipswitch" menu present if the game has dipswitches.

input_dipswitch[NAME] SETTING

8.9.10 input_configswitch[*]

Selects the state of the game configswitch. These settings can be modified using the "Config" menu present if the game has configswitches.

input_configswitch[NAME] SETTING

8.10 User Interface Configuration Options

This section describes the options used to customize the user interface.

8.10.1 ui_helpimage

Selects the image to display on help request. The image must be a PNG file. The pixels in black are used as background, any other color is used as foreground. Please note that the displayed image is always black and white.

ui_helpimage auto | FILE

Options:

auto Use the internal help image. With this option all the ui_helptag options are ignored.

FILE Load an arbitrary image from a file.

The data used for the default image is in the `contrib/help' dir.

8.10.2 ui_helptag

Selects the highlight range for any digital input. When the user press a key/button the related range is highlighted. A different color for any player is used in the image.

ui_helptag (keyboard[KEYBOARD,KEY]
    | mouse_button[MOUSE,MOUSE_BUTTON]
    | joystick_button[JOY,JOY_BUTTON]
    | joystick_digital[JOY,CONTROL,AXE,DIR])
    X Y DX DY

Options:

keyboard/mouse_*/joystick_* One digital input. Like the input_map option.

X, Y The upper/left position in the image of the input range.

DX, DY The size in pixel of the input range.

Examples:

ui_helptag keyboard[0,esc] 6 5 12 12 ui_helptag keyboard[0,f1] 26 5 12 12 ui_helptag keyboard[0,f2] 38 5 12 12 ui_helptag keyboard[0,f3] 50 5 12 12 ui_helptag keyboard[0,f4] 62 5 12 12 ui_helptag keyboard[0,f5] 81 5 12 12 ui_helptag keyboard[0,f6] 93 5 12 12 ui_helptag keyboard[0,f7] 105 5 12 12 ui_helptag keyboard[0,f8] 117 5 12 12 ui_helptag keyboard[0,f9] 137 5 12 12 ui_helptag keyboard[0,f10] 149 5 12 12

The data used for the default image is in the `contrib/help' dir.

8.10.3 ui_font

Selects a font file. The formats TrueType (TTF), GRX, PSF and RAW are supported. You can find a collection of fonts in the `contrib' directory.

ui_font auto | "FILE"

Options:

auto Use the built-in font (default).

FILE Font file path.

The TrueType (TTF) format is supported only if the program is compiled with the FreeType2 library.

8.10.4 ui_fontsize

Selects the font size, if the specified font is scalable. The size is expressed in number of rows and columns of text in the screen.

ui_fontsize auto | ROWS [COLS]

Options:

auto Automatically compute the size (default).

ROWS Number of text rows.

COLS Number of text columns. If omitted, it's computed from the number of rows.

8.10.5 ui_color[*]

Selects the user interface colors.

ui_color[TAG] FOREGROUND BACKGROUND

Tags:

interface Main inteface color.

tag Highlight tags.

select Selected menu entries.

help_p1 Help color for player 1 controls.

help_p2 Help color for player 2 controls.

help_p3 Help color for player 3 controls.

help_p4 Help color for player 4 controls.

help_other Help color for other controls

Options:

FOREGROUND Foreground color in RRGGBB hex format. For example FF0000 is red and 00FF00 is green.

BACKGROUND Background color. Like foreground color.

8.10.6 ui_translucency

Selects the translucency of the user interface.

ui_translucency FACTOR

Options:

FACTOR Translucency factor from 0 to 1 (default 0.8).

The translucency ha no effect on the 8 bits palettized video modes.

8.11 Record Configuration Options

This section describes the options used for the recording features.

To start the recording press `left_ctrl+enter'. To end the recording and to save the clip press `enter'. If you press the start key more than one time the recording starts from the last press.

8.11.1 record_sound

Enables or disables the sound recording.

record_sound yes | no

The sound clip is saved in the `dir_snap' directory (like the snapshot images) in `.wav' format. Specifically the `WAV PCM 16 bit' format is used. The sample rate used is the same sample rate specified with the `sound_samplerate' option.

The clip is saved without compression and without any volume adjustment. You should use an external utility to adjust the volume and compress the resulting file.

8.11.2 record_video

Enables or disables the video recording.

record_video yes | no

The video clip is saved in the `dir_snap' directory (like the snapshot images) in `.mng' format. The `MNG-LC' (Low Complexity) subformat is used.

The clip is saved with a lite compression, you should use an external utility to compress better the resulting file.

A powerful compression utility is the `advmng' program available in the AdvanceCOMP package.

8.11.3 record_video/sound_time

Controls the maximum length in seconds of the recording feature.

record_sound_time TIME
record_video_time TIME

Options:

TIME Time in seconds (default 15).

8.11.4 record_video_interleave

Selects how many frames to save with the video recording.

record_video_interleave COUNT

Options:

COUNT How many frames displayed a frame must be saved (default 2). 1 means save all the frames. 2 means save 1 every 2. 3 means save 1 every 3, and so on.

Examples:

record_video_interleave 1

8.12 Synchronization Options

This section describes the options used for the time synchronization of the emulated game or system.

8.12.1 sync_fps

Selects an arbitrary frame rate for the game.

sync_fps auto | FPS

Options:

auto Use the original framerate of the game (default).

FPS Use the specified framerate.

8.12.2 sync_speed

Selects a speed factor always active. You can play the game in slowdown or in nightmare mode!

sync_speed FACTOR

Options:

FACTOR Float speed factor (default 1.0).

Examples:

sync_speed 1.2

8.12.3 sync_turbospeed

Selects the speed factor used when the `turbo' button is pressed. The default `turbo' key is `asterisk_pad'.

sync_turbospeed FACTOR

Options:

FACTOR Float speed factor (default 3.0).

8.12.4 sync_startuptime

Selects the time in seconds of the duration of the startup speed up. You can press the `startup' key to save the current game time as startup time. The default `startup' key is `minus_pad'.

sync_startuptime auto | none | TIME

Options:

auto Get the value for the current game from an internal database (default).

none Disable the startup.

TIME Time in seconds.

8.12.5 sync_resample

Selects the audio resampling mode.

sync_resample auto | emulation | internal

Options:

auto Select automatically, at present it's always the `internal' mode (default).

emulation Change the emulation to produce the requested number of samples instead of resampling.

internal Internally resample the sound to match the current speed.

Note that the `emulation' mode may result in wrong input recording using the `-record' or `-playback' command line option due incorrect behavior of the emulation. Specifically some implementations may depend on the number of audio sample requested, information that is not stored in the recorded input file.

Also, the `emulation' mode may trigger some bugs in the MAME core.

Anyway, the `emulation' mode generates more stable sound if the CPU load isn't totally empty.

8.13 LCD Configuration Options

AdvanceMAME is able to display arbitrary information on a LCD display using the integrated script capabilities.

To use the LCD support you must install on your system the `lcdproc' program available at:

http://lcdproc.sourceforge.net/

More details and some examples of how to display information on the LCD using the scripts are in the `script.txt' documentation file.

8.13.1 lcd_server

Selects the server address and port to use for display information on the LCD.

lcd_server none | [SERVER][:PORT]

Options:

none Disable the LCD support (default).

SERVER Address of the server. If omitted `localhost' is used.

PORT Port of the server. If omitted `13666' is used.

Examples:

lcd_server localhost

8.13.2 lcd_timeout

Selects the timeout to connect at the server.

lcd_timeout TIMEOUT

Options:

TIMEOUT Timeout in milliseconds (default 500).

8.13.3 lcd_speed

Selects the LCD scrolling speed for long messages.

lcd_speed DELAY

Options:

DELAY Delay in 1/8th of seconds (default 8).

8.14 Misc Configuration Options

8.14.1 misc_bios

Selects the game bios in AdvanceMAME.

misc_bios default | NAME

Options:

default Use the default BIOS.

NAME Select specific BIOS.

8.14.2 misc_ramsize

Controls the ram size of the emulated machine in AdvanceMESS.

misc_ramsize auto | SIZE [k|M|G]

Options:

auto Automatic (default).

SIZE Size of the RAM in bytes. You can use the 'k' (1024), 'M' (1024^2) or 'G' (1024^3) multiplier.

Examples:

misc_ramsize 1024k

8.14.3 misc_difficulty

Selects the game difficulty. This option works only with games which select difficulty with dipswitches.

misc_difficulty none | easiest | easy | normal | hard | hardest

Options:

none Don't change the default difficulty (default).

easiest Easiest game play.

easy Easy game play.

normal Normal game play.

hard Hard game play.

hardest Hardest game play.

8.14.4 misc_freeplay

Selects the freeplay mode if the game support it. This option works only with games that select the freeplay mode with dipswitches.

misc_freeplay yes | no

Options:

no Don't change the default mode (default).

yes Activate the freeplay.

8.14.5 misc_mutedemo

Selects the demo nosound mode if the game support it. This option uses the dipswitches of the game and also the event database to detect if the game is in demo mode.

misc_mutedemo yes | no

Options:

no Don't change the default mode (default).

yes Mute the demo sounds.

8.14.6 misc_lang

Selects the game language and country. This option uses both the dipswitches and the clones description to select the correct game to run.

misc_lang none | usa | canada | englang | italy | germany
    | spain | austria | norway | france | denmark
    | japan | korea | china | hongkong | taiwan

Options:

none Don't change the language (default).

LANG If available select this language.

For example if you run `cadash' with `-lang italy' it's run the clone `cadashi'. If you run `cheesech' with `-lang germany' it's run `cheesech' setting the `Language' dipswitch to `German'.

If the specified language is not available, european and american languages fallback to english language. Asian languages fallback to japanese language.

A game clone is selected only if it's a perfectly working clone.

8.14.7 misc_smp

Enables the "Symmetric Multi-Processing" (SMP). This option uses two concurrent threads. One for MAME and one for updating the screen. The final blit stage in video memory is completely done by the second thread. This behavior requires a complete bitmap redraw by MAME for the games that don't already do it. Generally you get a big speed improvement only if you are using a heavy video effect like `hq'.

misc_smp yes | no

Options:

no Disabled (default).

yes Enabled.

You can enable or disable it also on the runtime Video menu.

8.14.8 misc_quiet

Doesn't print the copyright text message at the startup, the disclaimer and the generic game information screens.

misc_quiet yes | no

8.14.9 misc_timetorun

Run the emulation only for the given number of seconds without any throttling and at the exit print the number of real CPU seconds used. Useful for benchmarking.

misc_timetorun SECONDS

8.15 Support Files Configuration Options

The AdvanceMAME emulator can use also some support files:

	event.dat	The Event and Safequit database.
	cheat.dat	Cheat database.
	hiscore.dat	Highscore database.
	sysinfo.dat	MESS info database.
	english.lng	Language database.

These files should reside in current directory for DOS and Windows or in the $data or $home directories for Linux a Mac OS X.

8.15.1 misc_cheat

Enables or disables the cheat system. It may also change the game behavior enabling the cheat dip-switch if available. If enabled, it disables the hiscore saving.

misc_cheat yes | no

Options:

yes Enable the cheats.

no Disable the cheats (default).

8.15.2 misc_cheatfile

Selects the cheat files. In DOS and Windows use the `;' char as file separator. In Linux and Mac OS X use the `:' char.

misc_cheatfile FILE[;FILE]... (DOS, Windows)
misc_cheatfile FILE[:FILE]... (Linux, Mac OS X)

Options:

FILE Cheat file to load (default cheat.dat).

8.15.3 misc_languagefile

Selects the language file.

misc_languagefile FILE

Options:

FILE Language file to load (default english.lng).

8.15.4 misc_hiscorefile

Selects the hiscore file.

misc_hiscorefile FILE

Options:

FILE High score file to load (default hiscore.dat).

8.15.5 misc_safequit

Activates safe quit mode. If enabled, to stop the emulation, you need to confirm on a simple menu.

misc_safequit yes | no

Options:

no Disabled.

yes Enabled (default).

If the file `event.dat' (specified with the `misc_eventfile' option) is found the exit menu is shown only if one or more coins are inserted or if you are playing.

8.15.6 misc_eventdebug

Activates the debug mode for the event/safequit feature. On the top left of the screen the internal state of the event/safequit engine are printed. The first value is the coin state, the second value is the playing state. If both the values are 1 the exit is permitted without prompting. Other values are the 6 generic events.

misc_eventdebug yes | no

Options:

no Disabled (default).

yes Enabled.

8.15.7 misc_eventfile

Selects the event/safequit database to use.

misc_eventfile FILE

Options:

FILE Event file to load (default event.dat).

8.16 Debugging Configuration Options

The use of these options is discouraged. They are present only for testing purpose.

8.16.1 debug_crash

Crashes the program. It can be used to ensure that the correct video mode is restored on aborting conditions.

debug_crash yes | no

Options:

no Don't crash the program (default).

yes Add a "Crash" menu entry in the video menu. If selected the program crash with a Segmentation Fault.

8.16.2 debug_rawsound

Disables the sound output syncronization with the video.

debug_rawsound yes | no

Options:

no Normal operation (default).

yes Sound output without any syncronization.

8.16.3 debug_speedmark

Enables or disabled the on screen speed mark. If enabled a red square is displayed if the game is too slow. A red triangle when you press the `turbo' key or when the game is accelerated for other reasons.

debug_speedmark yes | no

Options:

yes Display the speed mark when required.

no Don't display the speed mark (default).

9 Signals

The program intercepts the following signals:

	SIGQUIT	Exit normally.
	SIGTERM, SIGINT, SIGALRM	Exit restoring only the output devices.
	SIGHUP	Restart the program.