summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/commandline/commandline-all.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/commandline/commandline-all.rst')
-rw-r--r--docs/source/commandline/commandline-all.rst589
1 files changed, 400 insertions, 189 deletions
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index ff0f6e6dd5d..89f7dac1287 100644
--- a/docs/source/commandline/commandline-all.rst
+++ b/docs/source/commandline/commandline-all.rst
@@ -1,10 +1,10 @@
-.. _universal-command-line:
+.. _mame-commandline-universal:
-Universal Commandline Options
-=============================
+Universal Command-line Options
+==============================
This section contains configuration options that are applicable to *all* MAME
-sub-builds (both SDL and Windows native).
+configurations (including both SDL and Windows native).
.. contents:: :local:
@@ -19,6 +19,8 @@ Verbs are actions to take upon something with the command (e.g.
**mame -validate pacman** has *mame* as a command and *-validate* as a verb)
+.. _mame-commandline-patterns:
+
Patterns
--------
@@ -38,7 +40,7 @@ File Names and Directory Paths
------------------------------
A number of options for specifying directories support multiple paths (for
-for example to search for ROMs in multiple locations). MAME expects multiple
+example to search for ROMs in multiple locations). MAME expects multiple
paths to be separated with semicolons ( ``;`` ).
MAME expands environment variable expressions in paths. The syntax used depends
@@ -80,6 +82,8 @@ Terminal window, set the working directory to the location of the script
(i.e. the folder containing MAME), and then start MAME.
+.. _mame-commandline-coreverbs:
+
Core Verbs
----------
@@ -136,6 +140,9 @@ Core Verbs
apple2_flop_orig.xml(137.3): mismatched tag
+
+.. _mame-commandline-configverbs:
+
Configuration Verbs
-------------------
@@ -175,6 +182,8 @@ Configuration Verbs
a sufficient description.
+.. _mame-commandline-fronendverbs:
+
Frontend Verbs
--------------
@@ -441,17 +450,17 @@ overwritten.
.. _mame-commandline-romident:
-**-romident** [*path\\to\\romstocheck.zip*]
+**-romident** [*path/to/romstocheck.zip*]
Attempts to identify ROM files, if they are known to MAME, in the specified
.zip file or directory. This command can be used to try and identify ROM
sets taken from unknown boards. On exit, the errorlevel is returned as one
of the following:
- * 0: means all files were identified
- * 7: means all files were identified except for 1 or more "non-ROM" files
- * 8: means some files were identified
- * 9: means no files were identified
+ * 0: means all files were identified
+ * 7: means all files were identified except for 1 or more "non-ROM" files
+ * 8: means some files were identified
+ * 9: means no files were identified
Example:
.. code-block:: bash
@@ -526,6 +535,32 @@ overwritten.
joy Apple II analog joysticks
paddles Apple II paddles
+.. _mame-commandline-listbios:
+
+**-listbios** [*<pattern>*]
+
+ Show available BIOS options for a system (if available). BIOS options may
+ be available for the system or any devices selected as slot options.
+
+ If no pattern is specified, the results will include *all* supported
+ systems.
+
+ Example:
+ .. code-block:: bash
+
+ mamed -listbios apple2 -sl2 grapplus -sl4 videoterm
+ BIOS options for system Apple ][ (apple2):
+ default Original Monitor
+ autostart Autostart Monitor
+
+ BIOS options for device Orange Micro Grappler+ Printer Interface (-sl2 grapplus):
+ v30 ROM 3.0
+ v32 ROM 3.2
+
+ BIOS options for device Videx Videoterm 80 Column Display (-sl4 videoterm):
+ v24_60hz Firmware v2.4 (60 Hz)
+ v24_50hz Firmware v2.4 (50 Hz)
+
.. _mame-commandline-listmedia:
**-listmedia** / **-lm** [<*pattern*>]
@@ -664,8 +699,8 @@ overwritten.
romset apple2_flop_orig:autobahn is good
...
-.. _osd-commandline-options:
+.. _mame-commandline-osdoptions:
OSD-related Options
-------------------
@@ -684,6 +719,49 @@ OSD-related Options
mame ibm5150 -uimodekey DEL
+.. _mame-commandline-controllermap:
+
+**-controller_map** / **-ctrlmap** *<filename>*
+
+ Path to a text file containing game controller button and axis mappings in
+ the format used by SDL2 and Steam, or ``none`` to use only built-in
+ mappings. Must use an ASCII-compatible text encoding with native line
+ endings (e.g. CRLF on Windows). Currently only supported when using the
+ ``sdlgame`` joystick provider. The default setting is ``none``.
+
+ A `community-sourced list of game controller mappings
+ <https://github.com/gabomdq/SDL_GameControllerDB>`_ can be found on GitHub.
+ Besides using a text editor, several tools are available for creating game
+ controller mappings, including `SDL2 Gamepad Mapper
+ <https://gitlab.com/ryochan7/sdl2-gamepad-mapper/-/releases>`_ and SDL2
+ ControllerMap which is `supplied with SDL
+ <https://github.com/libsdl-org/SDL/releases/latest>`_. You can also
+ configure your controller in Steam’s Big Picture mode, then copy the
+ mappings from ``SDL_GamepadBind`` entries in the **config.vdf** file found
+ in the **config** folder inside your Steam installation folder.
+
+ Example:
+ .. code-block:: bash
+
+ mame -controller_map gamecontrollerdb.txt sf2ce
+
+.. _mame-commandline-backgroundinput:
+
+**-[no]background_input**
+
+ Sets whether input is accepted or ignored when MAME does not have UI focus.
+ This setting is ignored when the debugger is enabled. The default is OFF
+ (**-nobackground_input**).
+
+ Currently supported for RawInput mouse/keyboard input, DirectInput
+ mouse/keyboard/joystick input and XInput joystick input on Windows, and SDL
+ game controller/joystick input.
+
+ Example:
+ .. code-block:: bash
+
+ mame -background_input ssf2tb
+
.. _mame-commandline-uifontprovider:
**-uifontprovider** *<module>*
@@ -878,7 +956,8 @@ Example:
**-joystickprovider** *<module>*
- Chooses how MAME will get joystick input. The default is ``auto``.
+ Chooses how MAME will get joystick and other game controller input. The
+ default is ``auto``.
.. list-table:: Supported joystick input providers per-platform
:header-rows: 0
@@ -889,38 +968,90 @@ Example:
- winhybrid
- dinput
- xinput
+ - sdlgame
+ - sdljoy
- none
- - sdl
* - **SDL**
- auto [#JIPAutoSDL]_.
-
-
-
+ - sdlgame
+ - sdljoy
- none
- - sdl
.. rubric:: Footnotes
-.. [#JIPAutoWindows] On Windows, auto will default to ``dinput``.
+.. [#JIPAutoWindows] On Windows native, auto will default to ``winhybrid``.
+
+.. [#JIPAutoSDL] On SDL, auto will default to ``sdlgame``.
+
+winhybrid
+ Uses XInput for compatible game controllers, falling back to DirectInput for
+ other game controllers. Typically provides the best experience on Windows.
+dinput
+ Uses DirectInput for all game controllers. May be useful if you want to use
+ more than four XInput game controllers simultaneously. Note that LT and RT
+ controls are combined with using XInput game controllers via DirectInput.
+xinput
+ Supports up to four XInput game controllers.
+sdlgame
+ Uses the SDL game controller API for game controllers with button/axis
+ mappings available, falling back to the SDL joystick API for other game
+ controllers. Provides consistent button and axis assignment and meaningful
+ control names for popular game controllers. Use the :ref:`controller_map
+ option <mame-commandline-controllermap>` to supply mappings for additional
+ game controllers or override built-in mappings.
+sdljoy
+ Uses the SDL joystick API for all game controllers.
+none
+ Ignores all game controllers.
+
+Example:
+ .. code-block:: bash
+
+ mame mk2 -joystickprovider winhybrid
+
+.. _mame-commandline-midiprovider:
-.. [#JIPAutoSDL] On SDL, auto will default to ``sdl``.
+**-midiprovider** *<module>*
-.. Tip:: Note that Microsoft XBox 360 and XBox One controllers connected to
- Windows will work best with ``winhybrid`` or ``xinput``. The
- ``winhybrid`` option supports a mix of DirectInput and XInput
- controllers at the same time.
+ Chooses how MAME will communicate with MIDI devices and applications (e.g.
+ music keyboards and synthesisers). Supported options are ``pm`` to use the
+ PortMidi library, or ``none`` to disable MIDI input and output (MIDI files
+ can still be played). The default is ``auto``, which will use PortMidi if
+ available.
Example:
.. code-block:: bash
- mame mk2 -joystickprovider winhybrid
+ mame -midiprovider none dx100 -midiin canyon.mid
+
+.. _mame-commandline-networkprovider:
+
+**-networkprovider** *<module>*
+
+ Chooses how MAME will provide communication for emulated packet-oriented
+ network interfaces (e.g. Ethernet cards). Supported options are ``taptun``
+ to use the TUN/TAP, TAP-Windows or similar, ``pcap`` to use a pcap library,
+ or ``none`` to disable communication for emulated network interfaces.
+ Available options depend on your operating system. By default, ``taptun``
+ and ``none`` are available on Windows and Linux, and ``pcap`` and ``none``
+ are available on macOS.
-.. Tip:: On Windows, winhybrid is likely to give the best experience by
- supporting both XInput and DirectInput controllers.
+ The default is ``auto`` which will use ``taptun`` if available, falling back
+ to ``pcap``.
+
+Example:
+ .. code-block:: bash
+ mame -networkprovider pcap apple2ee -sl3 uthernet
-OSD CLI Options
----------------
+
+.. _mame-commandline-cliverbs:
+
+OSD Command-Line Verbs
+----------------------
.. _mame-commandline-listmidi:
@@ -961,6 +1092,8 @@ OSD CLI Options
any network adapters.
+.. _mame-commandline-osdoutput:
+
OSD Output Options
------------------
@@ -987,6 +1120,8 @@ OSD Output Options
led0 = 0
+.. _mame-commandline-configoptions:
+
Configuration Options
---------------------
@@ -1025,6 +1160,8 @@ Configuration Options
mame apple2ee -noreadconfig -sl6 diskii -sl7 cffa2 -hard1 TotalReplay.2mg
+.. _mame-commandline-pathoptions:
+
Core Search Path Options
------------------------
@@ -1039,7 +1176,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -homepath c:\mame\lua
+ mame -homepath C:\mame\lua
.. _mame-commandline-rompath:
@@ -1054,7 +1191,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -rompath c:\mame\roms;c:\roms\another
+ mame -rompath C:\mame\roms;C:\roms\another
.. _mame-commandline-hashpath:
@@ -1069,7 +1206,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -hashpath c:\mame\hash;c:\roms\softlists
+ mame -hashpath C:\mame\hash;C:\roms\softlists
.. _mame-commandline-samplepath:
@@ -1084,7 +1221,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -samplepath c:\mame\samples;c:\roms\samples
+ mame -samplepath C:\mame\samples;C:\roms\samples
.. _mame-commandline-artpath:
@@ -1099,7 +1236,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -artpath c:\mame\artwork;c:\emu\shared-artwork
+ mame -artpath C:\mame\artwork;C:\emu\shared-artwork
.. _mame-commandline-ctrlrpath:
@@ -1115,7 +1252,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -ctrlrpath c:\mame\ctrlr;c:\emu\controllers
+ mame -ctrlrpath C:\mame\ctrlr;C:\emu\controllers
.. _mame-commandline-inipath:
@@ -1144,7 +1281,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -inipath c:\users\thisuser\documents\mameini
+ mame -inipath C:\Users\thisuser\documents\mameini
.. _mame-commandline-fontpath:
@@ -1159,7 +1296,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -fontpath c:\mame\;c:\emu\artwork\mamefonts
+ mame -fontpath C:\mame\;C:\emu\artwork\mamefonts
.. _mame-commandline-cheatpath:
@@ -1174,7 +1311,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -cheatpath c:\mame\cheat;c:\emu\cheats
+ mame -cheatpath C:\mame\cheat;C:\emu\cheats
.. _mame-commandline-crosshairpath:
@@ -1189,7 +1326,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -crosshairpath c:\mame\crsshair;c:\emu\artwork\crosshairs
+ mame -crosshairpath C:\mame\crsshair;C:\emu\artwork\crosshairs
.. _mame-commandline-pluginspath:
@@ -1203,7 +1340,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -pluginspath c:\mame\plugins;c:\emu\lua
+ mame -pluginspath C:\mame\plugins;C:\emu\lua
.. _mame-commandline-languagepath:
@@ -1218,7 +1355,7 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -languagepath c:\mame\language;c:\emu\mame-languages
+ mame -languagepath C:\mame\language;C:\emu\mame-languages
.. _mame-commandline-swpath:
@@ -1232,8 +1369,10 @@ Core Search Path Options
Example:
.. code-block:: bash
- mame -swpath c:\mame\software;c:\emu\mydisks
+ mame -swpath C:\mame\software;C:\emu\mydisks
+
+.. _mame-commandline-coreoutdir:
Core Output Directory Options
-----------------------------
@@ -1255,7 +1394,7 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -cfg_directory c:\mame\cfg
+ mame -cfg_directory C:\mame\cfg
.. _mame-commandline-nvramdirectory:
@@ -1273,7 +1412,7 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -nvram_directory c:\mame\nvram
+ mame -nvram_directory C:\mame\nvram
.. _mame-commandline-inputdirectory:
@@ -1290,7 +1429,7 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -input_directory c:\mame\inp
+ mame -input_directory C:\mame\inp
.. _mame-commandline-statedirectory:
@@ -1307,7 +1446,7 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -state_directory c:\mame\sta
+ mame -state_directory C:\mame\sta
.. _mame-commandline-snapshotdirectory:
@@ -1323,7 +1462,7 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -snapshot_directory c:\mame\snap
+ mame -snapshot_directory C:\mame\snap
.. _mame-commandline-diffdirectory:
@@ -1342,7 +1481,7 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -diff_directory c:\mame\diff
+ mame -diff_directory C:\mame\diff
.. _mame-commandline-commentdirectory:
@@ -1359,9 +1498,11 @@ Core Output Directory Options
Example:
.. code-block:: bash
- mame -comment_directory c:\mame\comments
+ mame -comment_directory C:\mame\comments
+.. _mame-commandline-savestate:
+
Core State/Playback Options
---------------------------
@@ -1484,22 +1625,6 @@ Core State/Playback Options
you should only record and playback with all configuration (.cfg),
NVRAM (.nv), and memory card files deleted.
-.. _mame-commandline-recordtimecode:
-
-**-record_timecode**
-
- Tells MAME to create a timecode file. It contains a line with elapsed times
- on each press of timecode shortcut key (default is **F12**). This option
- works only when recording mode is enabled (**-record** option). The
- timecode file is saved in the ``inp`` folder.
-
- By default, no timecode file is saved.
-
- Example:
- .. code-block:: bash
-
- mame pacman -record worldrecord -record_timecode
-
.. _mame-commandline-mngwrite:
**-mngwrite** *<filename>*
@@ -1549,7 +1674,7 @@ Core State/Playback Options
Example:
.. code-block:: bash
- mame pacman -wavewrite pacsounds
+ mame pacman -wavwrite pacsounds
.. _mame-commandline-snapname:
@@ -1722,6 +1847,8 @@ Core State/Playback Options
mame neogeo -burnin
+.. _mame-commandline-perf:
+
Core Performance Options
------------------------
@@ -1778,7 +1905,7 @@ Core Performance Options
**-[no]throttle**
- Enable or disable thottling emulation speed. When throttling is enabled,
+ Enable or disable throttling emulation speed. When throttling is enabled,
MAME limits emulation speed to so the emulated system will not run faster
than the original hardware. When throttling is disabled, MAME runs the
emulation as fast as possible. Depending on your settings and the
@@ -1878,7 +2005,7 @@ Core Performance Options
.. _mame-commandline-lowlatency:
-**-lowlatency**
+**-[no]lowlatency**
This tells MAME to draw a new frame before throttling to reduce input
latency. This is particularly effective with VRR (Variable Refresh Rate)
@@ -1894,6 +2021,8 @@ Core Performance Options
mame bgaregga -lowlatency
+.. _mame-commandline-rotation:
+
Core Rotation Options
---------------------
@@ -1994,6 +2123,8 @@ Core Rotation Options
mame -flipy suprmrio
+.. _mame-commandline-videooptions:
+
Core Video Options
------------------
@@ -2006,35 +2137,35 @@ Core Video Options
Generally Available:
- | Using ``bgfx`` specifies the new hardware accelerated renderer.
- |
- | Using ``opengl`` tells MAME to render video using OpenGL acceleration.
- |
- | Using ``none`` displays no windows and does no drawing. This is primarily present for doing CPU benchmarks without the overhead of the video system.
- |
+ * Using ``bgfx`` specifies the new hardware accelerated renderer.
+ * Using ``opengl`` tells MAME to render video using OpenGL acceleration.
+ * Using ``none`` displays no windows and does no drawing. This is primarily
+ intended for benchmarking emulation without the overhead of the video
+ system.
On Windows:
- | Using ``gdi`` tells MAME to render video using older standard Windows graphics drawing calls. This is the slowest but most compatible option on older versions of Windows.
- |
- | Using ``d3d`` tells MAME to use Direct3D for rendering. This produces the better quality output than ``gdi`` and enables additional rendering options. It is recommended if you have a semi-recent (2002+) video card or onboard Intel video of the HD3000 line or better.
- |
+ * Using ``gdi`` tells MAME to render video using older standard Windows
+ graphics drawing calls. This is the slowest but most compatible option on
+ older versions of Windows or buggy graphics hardware drivers.
+ * Using ``d3d`` tells MAME to use Direct3D 9 for rendering. This produces
+ better quality output than ``gdi`` and enables additional rendering
+ options. It is recommended if you have a 3D-capable video card or onboard
+ Intel video of the HD3000 line or better.
On other platforms (including SDL on Windows):
- | Using ``accel`` tells MAME to render video using SDL's 2D acceleration if possible.
- |
- | Using ``soft`` uses software rendering for video output. This isn't as fast or as nice as OpenGL but will work on any platform.
- |
+ * Using ``accel`` tells MAME to render video using SDL’s 2D acceleration if
+ possible.
+ * Using ``soft`` uses software rendering for video output. This isn’t as
+ fast or as nice as OpenGL, but it will work on any platform.
Defaults:
- | The default on Windows is ``d3d``.
- |
- | The default for Mac OS X is ``opengl`` because OS X is guaranteed to have a compliant OpenGL stack.
- |
- | The default on all other systems is ``soft``.
- |
+ * The default on Windows is ``d3d``.
+ * The default for macOS is ``opengl`` because OS X is guaranteed to have a
+ compliant OpenGL stack.
+ * The default on all other systems is ``soft``.
Example:
.. code-block:: bash
@@ -2203,7 +2334,7 @@ Core Video Options
The default is ``1``.
- This is supported with all video output types ( ``bgfx``, ``d3d``, etc) on
+ This is supported with all video output types ( ``bgfx``, ``d3d``, etc.) on
Windows and is supported with BGFX and OpenGL on other platforms.
Example:
@@ -2238,7 +2369,7 @@ Core Video Options
**-[no]unevenstretch**
Allow non-integer scaling factors allowing for great window sizing
- flexability.
+ flexibility.
The default is ON. (**-unevenstretch**)
@@ -2248,6 +2379,8 @@ Core Video Options
mame dkong -nounevenstretch
+.. _mame-commandline-fullscreen:
+
Core Full Screen Options
------------------------
@@ -2273,6 +2406,8 @@ Core Full Screen Options
mame kof97 -video d3d -switchres -resolution 1280x1024
+.. _mame-commandline-windowoptions:
+
Core Per-Window Options
-----------------------
@@ -2438,6 +2573,8 @@ Core Per-Window Options
mame contra -view native
+.. _mame-commandline-artwork:
+
Core Artwork Options
--------------------
@@ -2491,6 +2628,8 @@ Core Artwork Options
mame galaga -override_artwork puckman
+.. _mame-commandline-screenoptions:
+
Core Screen Options
-------------------
@@ -2585,6 +2724,8 @@ Core Screen Options
mame pacman -effect scanlines
+.. _mame-commandline-vectoroptions:
+
Core Vector Options
-------------------
@@ -2665,12 +2806,14 @@ Core Vector Options
mame asteroid -flicker 0.15
-Core Video OpenGL Debugging Options
------------------------------------
+.. _mame-commandline-opengloptions:
+
+Core Video OpenGL Feature Options
+---------------------------------
These options are for compatibility in **-video opengl**. If you report
-rendering artifacts you may be asked to try messing with them by the devs, but
-normally they should be left at their defaults which results in the best
+rendering artifacts you may be asked to try messing with them by the developers,
+but normally they should be left at their defaults which results in the best
possible video performance.
.. Tip:: Examples are not provided for these options as MAMEdev will provide
@@ -2709,16 +2852,18 @@ possible video performance.
The default is ON. (**-gl_pbo**)
+.. _mame-commandline-openglglsl:
+
Core Video OpenGL GLSL Options
------------------------------
.. _mame-commandline-glglsl:
-**-gl_glsl**
+**-[no]gl_glsl**
Enable OpenGL GLSL, if available.
- The default is OFF.
+ The default is OFF (**-nogl_glsl**).
Example:
.. code-block:: bash
@@ -2751,7 +2896,7 @@ Core Video OpenGL GLSL Options
**-glsl_shader_mame9**
- Set a custom OpenGL GLSL shader effect to the internal systcm screen in the
+ Set a custom OpenGL GLSL shader effect to the internal system screen in the
given slot. MAME does not include a vast selection of shaders by default;
more can be found online.
@@ -2772,7 +2917,7 @@ Core Video OpenGL GLSL Options
Set a custom OpenGL GLSL shader effect to the whole scaled-up output screen
- that will be rendered by your graphics card.MAME does not include a vast
+ that will be rendered by your graphics card. MAME does not include a vast
selection of shaders by default; more can be found online.
Example:
@@ -2781,19 +2926,7 @@ Core Video OpenGL GLSL Options
mame suprmrio -gl_glsl -glsl_shader_screen0 gaussx -glsl_shader_screen1 gaussy -glsl_shader_screen2 CRT-geom-halation
-.. _mame-commandline-glglslvidattr:
-
-**-gl_glsl_vid_attr**
-
- Enable OpenGL GLSL handling of brightness and contrast.
- Better RGB system performance.
-
- Default is ``on``.
-
- Example:
- .. code-block:: bash
-
- mame pacman -gl_glsl -gl_glsl_vid_attr off
+.. _mame-commandline-soundoptions:
Core Sound Options
------------------
@@ -2844,11 +2977,14 @@ Core Sound Options
**-volume** / **-vol** *<value>*
- Sets the startup volume. It can later be changed with the user interface
- (see Keys section). The volume is an attenuation in dB: e.g.,
- "**-volume -12**" will start with -12dB attenuation.
+ Sets the initial sound volume. It can be changed later with the user
+ interface (see Keys section). The volume is an attenuation in decibels:
+ e.g. "**-volume -12**" will start with -12 dB attenuation. Note that if the
+ volume is changed in the user interface it will be saved to the
+ configuration file for the system. The value from the configuration file
+ for the system has priority over ``volume`` settings in general INI files.
- The default is ``0``.
+ The default is ``0`` (no attenuation, or full volume).
Example:
.. code-block:: bash
@@ -2920,11 +3056,11 @@ Core Sound Options
The default is ``1``.
- | For PortAudio, see the section on :ref:`-pa_latency <mame-commandline-pa-latency>`.
- | XAudio2 calculates audio_latency as 10ms steps.
- | DSound calculates audio_latency as 10ms steps.
- | CoreAudio calculates audio_latency as 25ms steps.
- | SDL calculates audio_latency as Xms steps.
+ * For PortAudio, see the section on :ref:`-pa_latency <mame-commandline-palatency>`.
+ * XAudio2 calculates audio_latency as 10ms steps.
+ * DSound calculates audio_latency as 10ms steps.
+ * CoreAudio calculates audio_latency as 25ms steps.
+ * SDL calculates audio_latency as Xms steps.
Example:
.. code-block:: bash
@@ -2932,6 +3068,8 @@ Core Sound Options
mame galaga -audio_latency 1
+.. _mame-commandline-inputoptions:
+
Core Input Options
------------------
@@ -2977,7 +3115,16 @@ Core Input Options
Controls whether or not MAME makes use of mouse controllers. When this is
enabled, you will likely be unable to use your mouse for other purposes
- until you exit or pause the system.
+ until you exit or pause the system. Supported mouse controllers depend on
+ your :ref:`mouseprovider setting <mame-commandline-mouseprovider>`.
+
+ Note that if this setting is off (**-nomouse**), mouse input may still be
+ enabled depending on the inputs present on the emulated system and your
+ :ref:`automatic input enable settings <mame-commandline-inputenable>`. In
+ particular, the default is to enable mouse input when the emulated system
+ has mouse inputs (**-mouse_device mouse**), so MAME will capture your mouse
+ pointer when you run a system with mouse inputs unless you also change
+ the **mouse_device** setting.
The default is OFF (**-nomouse**).
@@ -2990,11 +3137,17 @@ Core Input Options
**-[no]joystick** / **-[no]joy**
- Controls whether or not MAME makes use of joystick/gamepad controllers.
+ Controls whether or not MAME makes use of game controllers (e.g. joysticks,
+ gamepads and simulation controls). Supported game controllers depend on
+ your :ref:`joystickprovider setting <mame-commandline-joystickprovider>`.
When this is enabled, MAME will ask the system about which controllers are
connected.
+ Note that if this setting is off (**-nojoystick**), joystick input may still
+ be enabled depending on the inputs present on the emulated system and your
+ :ref:`automatic input enable settings <mame-commandline-inputenable>`.
+
The default is OFF (**-nojoystick**).
Example:
@@ -3007,8 +3160,14 @@ Core Input Options
**-[no]lightgun** / **-[no]gun**
Controls whether or not MAME makes use of lightgun controllers. Note that
- most lightguns map to the mouse, so using **-lightgun** and **-mouse**
- together may produce strange results.
+ most lightguns also produce mouse input, so enabling mouse and lightgun
+ controllers simultaneously (using **-lightgun** and **-mouse** together) may
+ produce strange behaviour. Supported lightgun controllers depend on your
+ :ref:`lightgunprovider setting <mame-commandline-lightgunprovider>`.
+
+ Note that if this setting is off (**-nolightgun**), lightgun input may still
+ be enabled depending on the inputs present on the emulated system and your
+ :ref:`automatic input enable settings <mame-commandline-inputenable>`.
The default is OFF (**-nolightgun**).
@@ -3150,17 +3309,17 @@ Core Input Options
map. Below is an example map for an 8-way joystick that matches the
picture shown above:
- +-------------+--------------------------------------------------------+
- | | 777888999 | |
- | | 777888999 | | Note that the numeric digits correspond to the keys |
- | | 777888999 | | on a numeric keypad. So '7' maps to up+left, '4' maps|
- | | 444555666 | | to left, '5' maps to neutral, etc. In addition to the|
- | | 444555666 | | numeric values, you can specify the character 's', |
- | | 444555666 | | which means "sticky". Sticky map positions will keep|
- | | 111222333 | | the output the same as the last non-sticky input sent|
- | | 111222333 | | to the system. |
- | | 111222333 | |
- +-------------+--------------------------------------------------------+
+ +-------------+--------------------------------------------------------+
+ | | 777888999 | |
+ | | 777888999 | | Note that the numeric digits correspond to the keys |
+ | | 777888999 | | on a numeric keypad. So '7' maps to up+left, '4' maps|
+ | | 444555666 | | to left, '5' maps to neutral, etc. In addition to the|
+ | | 444555666 | | numeric values, you can specify the character 's', |
+ | | 444555666 | | which means "sticky". Sticky map positions will keep|
+ | | 111222333 | | the output the same as the last non-sticky input sent|
+ | | 111222333 | | to the system. |
+ | | 111222333 | |
+ +-------------+--------------------------------------------------------+
To specify the map for this parameter, you can specify a string of rows
separated by a '.' (which indicates the end of a row), like so:
@@ -3209,17 +3368,17 @@ Core Input Options
This map would look somewhat like:
- +-------------+---------------------------------------------------------+
- | | s8888888s | |
- | | 4s88888s6 | | For this mapping, we have a wide range for the |
- | | 44s888s66 | | cardinal directions on 8, 4, 6, and 2. We have sticky|
- | | 444555666 | | on the meeting points between those cardinal |
- | | 444555666 | | directions where the appropriate direction isn't |
- | | 444555666 | | going to be completely obvious. |
- | | 44s222s66 | |
- | | 4s22222s6 | |
- | | s2222222s | |
- +-------------+---------------------------------------------------------+
+ +-------------+---------------------------------------------------------+
+ | | s8888888s | |
+ | | 4s88888s6 | | For this mapping, we have a wide range for the |
+ | | 44s888s66 | | cardinal directions on 8, 4, 6, and 2. We have sticky|
+ | | 444555666 | | on the meeting points between those cardinal |
+ | | 444555666 | | directions where the appropriate direction isn't |
+ | | 444555666 | | going to be completely obvious. |
+ | | 44s222s66 | |
+ | | 4s22222s6 | |
+ | | s2222222s | |
+ +-------------+---------------------------------------------------------+
To specify the map for this parameter, you can specify a string of rows
separated by a '.' (which indicates the end of a row), like so:
@@ -3241,17 +3400,17 @@ Core Input Options
**-joystick_deadzone** *<value>* / **-joy_deadzone** *<value>* / **-jdz** *<value>*
- If you play with an analog joystick, the center can drift a little.
- joystick_deadzone tells how far along an axis you must move before the axis
- starts to change. This option expects a float in the range of 0.0 to 1.0.
- Where 0 is the center of the joystick and 1 is the outer limit.
+ If you play with an analog joystick, the center can drift a little.
+ joystick_deadzone tells how far along an axis you must move before the axis
+ starts to change. This option expects a float in the range of 0.0 to 1.0.
+ Where 0 is the center of the joystick and 1 is the outer limit.
- The default is ``0.3``.
+ The default is ``0.15``.
Example:
.. code-block:: bash
- mame sinistar -joystick_deadzone 0.45
+ mame sinistar -joystick_deadzone 0.3
.. _mame-commandline-joysticksaturation:
@@ -3270,13 +3429,36 @@ Core Input Options
mame sinistar -joystick_saturation 1.0
+.. _mame-commandline-joystickthreshold:
+
+**-joystick_threshold** *<value>* / **joy_threshold** *<value>* / **-jthresh** *<value>*
+
+ When a joystick axis (or other absolute analog axis) is assigned to a
+ digital input, this controls how far it must be moved from the neutral
+ position (or centre) to be considered active or switched on. This option
+ expects a float in the range of 0.0 to 1.0, where 0 means any movement from
+ the neutral position is considered active, and 1 means only the outer limits
+ are considered active. This threshold is **not** adjusted to the range
+ between the dead zone and saturation point.
+
+ Note that if a :ref:`joystick map <mame-commandline-joystickmap>` is
+ configured, that will take precedence over this setting when a joystick’s
+ main X/Y axes are assigned to digital inputs.
+
+ The default is ``0.3``.
+
+ Example:
+ .. code-block:: bash
+
+ mame raiden -joystick_threshold 0.2
+
.. _mame-commandline-natural:
-**\-natural**
+**\-[no]natural**
Allows user to specify whether or not to use a natural keyboard or not.
This allows you to start your system in a 'native' mode, depending on your
- region, allowing compatability for non-"QWERTY" style keyboards.
+ region, allowing compatibility for non-"QWERTY" style keyboards.
The default is OFF (**-nonatural**)
@@ -3286,18 +3468,22 @@ Core Input Options
presses/releases the emulated key.
In "natural keyboard" mode, MAME attempts to translate characters to
- keystrokes. The OS translates keystrokes to characters
- (similarly when you type into a text editor), and MAME attempts to translate
- these characters to emulated keystrokes.
+ keystrokes. The OS translates keystrokes to characters (similarly to when
+ you type into a text editor), and MAME attempts to translate these
+ characters to emulated keystrokes.
**There are a number of unavoidable limitations in "natural keyboard" mode:**
- * The emulated system driver and/or keyboard device or has to support it.
- * The selected keyboard *must* match the keyboard layout selected in the emulated OS!
- * Keystrokes that don't produce characters can't be translated. (e.g. pressing a modifier on its own such as **shift**, **ctrl**, or **alt**)
- * Holding a key until the character repeats will cause the emulated key to be pressed repeatedly as opposed to being held down.
- * Dead key sequences are cumbersome to use at best.
- * It won't work at all if IME edit is involved. (e.g. for Chinese/Japanese/Korean)
+ * The emulated system driver and/or keyboard device has to support it.
+ * The selected keyboard layout *must* match the keyboard layout selected in
+ the emulated OS!
+ * Keystrokes that don’t produce characters can’t be translated (e.g.
+ pressing a modifier on its own such as **shift**, **ctrl**, or **alt**).
+ * Holding a key until the character repeats will cause the emulated key to
+ be pressed repeatedly as opposed to being held down.
+ * Dead key sequences are cumbersome to use at best.
+ * It won’t work at all if IME edit is involved (e.g. for Chinese, Japanese
+ or Korean language input).
Example:
.. code-block:: bash
@@ -3306,7 +3492,7 @@ Core Input Options
.. _mame-commandline-joystickcontradictory:
-**-joystick_contradictory**
+**-[no]joystick_contradictory**
Enable contradictory direction digital joystick input at the same time such
as **Left and Right** or **Up and Down** at the same time.
@@ -3333,6 +3519,8 @@ Core Input Options
mame contra -coin_impulse 1
+.. _mame-commandline-inputenable:
+
Core Input Automatic Enable Options
-----------------------------------
@@ -3368,21 +3556,34 @@ Core Input Automatic Enable Options
**-mouse_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
- Each of these options controls autoenabling the mouse, joystick, or lightgun
- depending on the presence of a particular class of analog control for a
- particular system. For example, if you specify the option
- **-paddle mouse**, then any game that has a paddle control will
- automatically enable mouse controls just as if you had explicitly specified
- **-mouse**.
+ Each of these options sets whether mouse, joystick or lightgun controllers
+ should be enabled when running an emulated system that uses a particular
+ class of analog inputs. These options can effectively set
+ :ref:`-mouse <mame-commandline-nomouse>`, :ref:`-joystick
+ <mame-commandline-nojoystick>` and/or :ref:`-lightgun
+ <mame-commandline-nolightgun>` depending on the type of inputs present on
+ the emulated system. Note that these options *will not* override explicit
+ **-nomouse**, **-nojoystick** and/or **-nolightgun** settings at a higher
+ priority level (e.g. in a more specific INI file or on the command line).
+
+ For example, if you specify the option **-paddle_device mouse**, then mouse
+ controls will automatically be enabled when you run a game that has paddle
+ controls (e.g. Super Breakout), even if you specified **-nomouse** .
+
+ The default is to automatically enable mouse controls when running emulated
+ systems with mouse inputs (**-mouse_device mouse**).
Example:
.. code-block:: bash
mame sbrkout -paddle_device mouse
-.. Tip:: Note that these controls override the values of **-[no]mouse**,
- **-[no]joystick**, etc.
+.. Tip:: Note that these settings can override **-nomouse**, **-nojoystick**
+ and/or **-nolightgun** depending on the inputs present on the emulated
+ system.
+
+.. _mame-commandline-debugging:
Debugging Options
-----------------
@@ -3447,11 +3648,10 @@ Debugging Options
**-[no]debug**
- Activates the integrated debugger. By default, pressing the tilde
- (**~**) key during emulation breaks into the debugger. MAME also
- breaks into the debugger after the initial soft reset on startup if
- the debugger is active. See :ref:`debugger` for information on using
- the debugger.
+ Activates the integrated debugger. By default, pressing the backtick/tilde
+ (**~**) key during emulation breaks into the debugger. MAME also breaks
+ into the debugger after the initial soft reset on startup if the debugger is
+ active. See :ref:`debugger` for information on using the debugger.
The default is OFF (**-nodebug**).
@@ -3587,6 +3787,8 @@ Debugging Options
mame marble -debug -debugger_font "Comic Sans MS" -debugger_font_size 16
+.. _mame-commandline-commoptions:
+
Core Communication Options
--------------------------
@@ -3662,6 +3864,8 @@ Core Communication Options
mame arescue -comm_remotehost 192.168.1.3 -comm_remoteport 30100 -comm_framesync
+.. _mame-commandline-miscoptions:
+
Core Misc Options
-----------------
@@ -3680,7 +3884,7 @@ Core Misc Options
.. _mame-commandline-drcusec:
-**\-drc_use_c**
+**\-[no]drc_use_c**
Force DRC to use the C code backend.
@@ -3693,7 +3897,7 @@ Core Misc Options
.. _mame-commandline-drcloguml:
-**\-drc_log_uml**
+**\-[no]drc_log_uml**
Write DRC UML disassembly log.
@@ -3706,7 +3910,7 @@ Core Misc Options
.. _mame-commandline-drclognative:
-**\-drc_log_native**
+**\-[no]drc_log_native**
Write DRC native disassembly log.
@@ -3722,8 +3926,8 @@ Core Misc Options
**-bios** *<biosname>*
Specifies the specific BIOS to use with the current system, for systems that
- make use of a BIOS. The **-listxml** output will list all of the possible
- BIOS names for a system.
+ make use of a BIOS. The **-listbios** output will list all of the possible
+ BIOS names for a system, as does the **-listxml** output.
The default is ``default``.
@@ -3785,7 +3989,7 @@ Core Misc Options
Specifies the type of UI to use, either ``simple`` or ``cabinet``.
- The default is Cabinet (**-ui cabinet**).
+ The default is cabinet (**-ui cabinet**).
Example:
.. code-block:: bash
@@ -3805,7 +4009,7 @@ Core Misc Options
.. _mame-commandline-confirmquit:
-**\-confirm_quit**
+**\-[no]confirm_quit**
Display a Confirm Quit dialog to screen on exit, requiring one extra step
to exit MAME.
@@ -3819,11 +4023,11 @@ Core Misc Options
.. _mame-commandline-uimouse:
-**\-ui_mouse**
+**\-[no]ui_mouse**
- Displays a mouse cursor when using the built-in UI for MAME.
+ Displays a mouse cursor when using the built-in MAME user interface.
- The default is (**-noui_mouse**).
+ The default is ON (**-ui_mouse**).
.. _mame-commandline-language:
@@ -3858,6 +4062,8 @@ Core Misc Options
mame galaga88 -nonvram_save
+.. _mame-commandline-scripting:
+
Scripting Options
-----------------
@@ -3866,8 +4072,8 @@ Scripting Options
**-autoboot_command** *"<command>"*
Command string to execute after machine boot (in quotes " "). To issue a
- quote to the emulation, use """ in the string. Using **\\n** will issue a
- create a new line, issuing what was typed prior as a command.
+ quote to the emulation, use """ in the string. Using **\\n** will create
+ a new line, issuing what was typed prior as a command.
This works only with systems that support natural keyboard mode.
@@ -3947,8 +4153,11 @@ Scripting Options
mame alcon -noplugin cheat
+.. _mame-commandline-webserver:
+
HTTP Server Options
-------------------
+
.. _mame-commandline-http:
**-[no]http**
@@ -3986,13 +4195,15 @@ HTTP Server Options
Example:
.. code-block:: bash
- mame apple2 -http -http_port 6502 -http_root c:\users\me\appleweb\root
+ mame apple2 -http -http_port 6502 -http_root C:\Users\me\appleweb\root
+
+.. _mame-commandline-portaudio:
PortAudio Options
-----------------
-.. _mame-commandline-pa-api:
+.. _mame-commandline-paapi:
**-pa_api** *API*
@@ -4048,7 +4259,7 @@ PortAudio Options
mame suprmrio -sound portaudio -pa_api "Windows WASAPI"
-.. _mame-commandline-pa-device:
+.. _mame-commandline-padevice:
**-pa_device** *device*
@@ -4062,7 +4273,7 @@ PortAudio Options
mame suprmrio -sound portaudio -pa_api "Windows WASAPI" -pa_device "NX-EDG27 (NVIDIA High Definition Audio)"
-.. _mame-commandline-pa-latency:
+.. _mame-commandline-palatency:
**-pa_latency** *latency*