summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author Firehawke <34792592+Firehawke@users.noreply.github.com>2020-06-11 21:26:28 -0700
committer GitHub <noreply@github.com>2020-06-12 14:26:28 +1000
commit7b6dbd7a1442d6a77f3b410966fdc41769e417b5 (patch)
tree561aa83193e792b1884e40bfbd2fd091c3d14c94 /docs
parent6fb51a0ce70c937b1d9198b6ad3d98c4a50ae265 (diff)
First completed pass of commandline parameters. (nw) (#6711)
* First completed pass of commandline parameters. (nw) * Further refinements on commandline (nw) * Get the audio latency numbers right and add PortAudio info. * FreeSync/GSync information cleanup. * Minor additions to G-Sync/FreeSync. * Add tip for keyboardprovider, remove biospath, correct anchor positioning (nw) * A few corrections per Vas (nw)
Diffstat (limited to 'docs')
-rw-r--r--docs/source/commandline/commandline-all.rst1725
-rw-r--r--docs/source/usingmame/commonissues.rst17
2 files changed, 1592 insertions, 150 deletions
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index 636aef571ec..af743534b0e 100644
--- a/docs/source/commandline/commandline-all.rst
+++ b/docs/source/commandline/commandline-all.rst
@@ -32,12 +32,13 @@ patterns to avoid having your shell try to expand them against filenames (e.g.
.. _mame-commandline-paths:
+
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
-paths to be separated with semicolons (``;``).
+paths to be separated with semicolons ( ``;`` ).
MAME expands environment variable expressions in paths. The syntax used depends
on your operating system. On Windows, ``%`` (percent) syntax is used. For
@@ -47,25 +48,25 @@ Linux), Bourne shell syntax is used, and a leading ``~`` expands to the current
user's home directory. For example, ``~/.mame/${HOSTNAME}/cfg`` expands to
a host-specific path inside the ``.mame`` directory in the current user's home
directory. Note that only simple variable substitutions are supported; more
-complex expressions supported by Bash, ksh or zsh are not recognised by MAME.
+complex expressions supported by Bash, ksh or zsh are not recognized by MAME.
Relative paths are resolved relative to the current working directory. If you
start MAME by double-clicking it in Windows Explorer, the working directory is
set to the folder containing the MAME executable. If you start MAME by
double-clicking it in the macOS Finder, it will open a Terminal window with the
-working directory is set to your home directory (usually ``/Users/<username>``)
+working directory is set to your home directory (usually ``/Users/<username>`` )
and start MAME.
If you want behaviour similar to what Windows Explorer provides on macOS, create
a script file containing these lines in the directory containing the MAME
-executable (for example you could call it ``mame-here``)::
+executable (for example you could call it ``mame-here`` )::
#!/bin/sh
cd "`dirname "$0"`"
exec ./mame64
You should be able to use any text editor. If you have a choice of file format
-or line ending style, chose UNIX. I've assumed you're using a 64-bit release
+or line ending style, choose UNIX. This assumes you're using a 64-bit release
build of MAME, but if you aren't you just need to change ``mame64`` to the name
of your MAME executable. Once you've created the file, you need to mark is as
executable. You can do this by opening a Terminal window, typing **chmod a+x**
@@ -81,12 +82,27 @@ MAME), and then start MAME.
Core Verbs
----------
+.. Tip:: Examples that have the output abbreviated for space reasons will show
+ "**...**" in the output where needed. For instance:
+ .. code-block:: bash
+
+ A
+ B
+ C
+ ...
+ Z
+
.. _mame-commandline-help:
**-help** / **-h** / **-?**
Displays current MAME version and copyright notice.
+ Example:
+ .. code-block:: bash
+
+ mame64 -help
+
.. _mame-commandline-validate:
**-validate** / **-valid** [*<pattern>*]
@@ -100,6 +116,23 @@ Core Verbs
is specified, it will be matched against systems only (not other devices),
and no device type validation will be performed.
+ Example:
+ .. code-block:: bash
+
+ mame64 -validate
+ Driver ace100 (file apple2.cpp): 1 errors, 0 warnings
+ Errors:
+ Software List device 'flop525_orig': apple2_flop_orig.xml: Errors parsing software list:
+ apple2_flop_orig.xml(126.2): Unknown tag: year
+ apple2_flop_orig.xml(126.8): Unexpected content
+ apple2_flop_orig.xml(127.2): Unknown tag: publisher
+ apple2_flop_orig.xml(127.13): Unexpected content
+ apple2_flop_orig.xml(128.2): Unknown tag: info
+ apple2_flop_orig.xml(129.2): Unknown tag: sharedfeat
+ apple2_flop_orig.xml(132.2): Unknown tag: part
+ apple2_flop_orig.xml(133.3): Tag dataarea found outside of software context
+ apple2_flop_orig.xml(134.4): Tag rom found outside of part context
+ apple2_flop_orig.xml(137.3): mismatched tag
Configuration Verbs
@@ -113,16 +146,24 @@ Configuration Verbs
verbs) described below can be permanently changed by editing this
configuration file.
+ Example:
+ .. code-block:: bash
+
+ mame64 -createconfig
+
.. _mame-commandline-showconfig:
**-showconfig** / **-sc**
Displays the current configuration settings. If you route this to a file,
- you can use it as an INI file. For example, the command:
+ you can use it as an INI file.
- **mame -showconfig > mame.ini**
+ Example:
+ .. code-block:: bash
- is equivalent to **-createconfig**.
+ mame -showconfig > mame.ini
+
+ This example is equivalent to **-createconfig**.
.. _mame-commandline-showusage:
@@ -133,7 +174,6 @@ Configuration Verbs
a sufficient description.
-
Frontend Verbs
--------------
@@ -145,20 +185,19 @@ command:
**>** *filename*
where *filename* is the name of the file to save the output in (e.g.
-``list.txt``). Note that if this file already exists, it will be completely
+``list.txt`` ). Note that if this file already exists, it will be completely
overwritten.
-Example:
+ Example:
+ .. code-block:: bash
-| **mame -listcrc puckman > list.txt**
-|
+ mame64 -listcrc puckman > list.txt
This creates (or overwrites the existing file if already there) ``list.txt``
and fills the file with the results of **-listcrc puckman**. In other
words, the list of each ROM used in Puckman and the CRC for that ROM are
written into that file.
-
.. _mame-commandline-listxml:
**-listxml** / **-lx** [*<pattern>*...]
@@ -172,10 +211,57 @@ Example:
front-ends and ROM managers), or processed with scripts query detailed
information.
+ Example:
+ .. code-block:: bash
+
+ mame64 galaxian -listxml
+ <?xml version="1.0"?>
+ <!DOCTYPE mame [
+ <!ELEMENT mame (machine+)>
+ <!ATTLIST mame build CDATA #IMPLIED>
+ <!ATTLIST mame debug (yes|no) "no">
+ <!ATTLIST mame mameconfig CDATA #REQUIRED>
+ <!ELEMENT machine (description, year?, manufacturer?, biosset*, rom*, disk*, device_ref*, sample*, chip*, display*, sound?, input?, dipswitch*, configuration*, port*, adjuster*, driver?, feature*, device*, slot*, softwarelist*, ramoption*)>
+ <!ATTLIST machine name CDATA #REQUIRED>
+ <!ATTLIST machine sourcefile CDATA #IMPLIED>
+ ...
+ <mame build="0.216 (mame0216-154-gabddfb0404c-dirty)" debug="no" mameconfig="10">
+ <machine name="galaxian" sourcefile="galaxian.cpp">
+ <description>Galaxian (Namco set 1)</description>
+ <year>1979</year>
+ <manufacturer>Namco</manufacturer>
+ ...
+ <machine name="z80" sourcefile="src/devices/cpu/z80/z80.cpp" isdevice="yes" runnable="no">
+ <description>Zilog Z80</description>
+ </machine>
+ </mame>
+
+.. Tip:: Output from this command is typically more useful if redirected to
+ an output file. For instance, doing
+ **mame64 -listxml galaxian > galax.xml** will make ``galax.xml`` or
+ overwrite any existing data in the file with the results of
+ **-listxml**; this will allow you to view it in a text editor or parse
+ it with external tools.
+
.. _mame-commandline-listfull:
**-listfull** / **-ll** [*<pattern>*...]
+ Example:
+ .. code-block:: bash
+
+ mame64 -listfull galaxian*
+ Name: Description:
+ galaxian "Galaxian (Namco set 1)"
+ galaxiana "Galaxian (Namco set 2)"
+ galaxianbl "Galaxian (bootleg, set 2)"
+ galaxianbl2 "Galaxian (bootleg, set 4)"
+ galaxiani "Galaxian (Irem)"
+ galaxianm "Galaxian (Midway set 1)"
+ galaxianmo "Galaxian (Midway set 2)"
+ galaxiant "Galaxian (Taito)"
+ galaxian_sound "Galaxian Custom Sound"
+
Displays a list of system driver names and descriptions. By default all
systems and devices are listed; however, you can limit this list by
specifying one or more *patterns* after the **-listfull** verb.
@@ -190,6 +276,12 @@ Example:
you can limit this list by specifying one or more *pattern* after the
**-listsource** verb.
+ Example:
+ .. code-block:: bash
+
+ mame64 galaga -listsource
+ galaga galaga.cpp
+
.. _mame-commandline-listclones:
**-listclones** / **-lc** [*<pattern>*]
@@ -199,6 +291,26 @@ Example:
verb. If a pattern is specified, MAME will list clones of systems that
match the pattern, as well as clones that match the pattern themselves.
+ Example 1:
+ .. code-block:: bash
+
+ mame64 pacman -listclones
+ Name: Clone of:
+ pacman puckman
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 puckman -listclones
+ Name: Clone of:
+ abscam puckman
+ bucaner puckman
+ crockman puckman
+ crockmnf puckman
+ ...
+ puckmod puckman
+ titanpac puckman
+
.. _mame-commandline-listbrothers:
**-listbrothers** / **-lb** [*<pattern>*]
@@ -206,6 +318,18 @@ Example:
Displays a list of *brothers*, i.e. other systems that are defined in the
same source file as a system that matches the specified *pattern*.
+ Example:
+ .. code-block:: bash
+
+ mame64 galaxian -listbrothers
+ Source file: Name: Parent:
+ galaxian.cpp amidar
+ galaxian.cpp amidar1 amidar
+ galaxian.cpp amidarb amidar
+ ...
+ galaxian.cpp zigzagb
+ galaxian.cpp zigzagb2 zigzagb
+
.. _mame-commandline-listcrc:
**-listcrc** [*<pattern>*...]
@@ -215,6 +339,31 @@ Example:
specified, ROMs referenced by all supported systems and devices will be
included.
+ Example:
+ .. code-block:: bash
+
+ mame64 playch10 -listcrc
+ d52fa07a pch1-c__8t_e-2.8t playch10 PlayChoice-10 BIOS
+ 503ee8b1 pck1-c.8t playch10 PlayChoice-10 BIOS
+ 123ffa37 pch1-c_8te.8t playch10 PlayChoice-10 BIOS
+ 0be8ceb4 pck1-c_fix.8t playch10 PlayChoice-10 BIOS
+ 9acffb30 pch1-c__8k.8k playch10 PlayChoice-10 BIOS
+ c1232eee pch1-c__8m_e-1.8m playch10 PlayChoice-10 BIOS
+ 30c15e23 pch1-c__8p_e-1.8p playch10 PlayChoice-10 BIOS
+ 9acffb30 pch1-c__8k.8k playch10 PlayChoice-10 BIOS
+ c1232eee pch1-c__8m_e-1.8m playch10 PlayChoice-10 BIOS
+ 30c15e23 pch1-c__8p_e-1.8p playch10 PlayChoice-10 BIOS
+ 9acffb30 pch1-c__8k.8k playch10 PlayChoice-10 BIOS
+ 83ebc7a3 pch1-c_8m.8m playch10 PlayChoice-10 BIOS
+ 90e1b80c pch1-c_8p-8p playch10 PlayChoice-10 BIOS
+ 9acffb30 pch1-c__8k.8k playch10 PlayChoice-10 BIOS
+ c1232eee pch1-c__8m_e-1.8m playch10 PlayChoice-10 BIOS
+ 30c15e23 pch1-c__8p_e-1.8p playch10 PlayChoice-10 BIOS
+ e5414ca3 pch1-c-6f.82s129an.6f playch10 PlayChoice-10 BIOS
+ a2625c6e pch1-c-6e.82s129an.6e playch10 PlayChoice-10 BIOS
+ 1213ebd4 pch1-c-6d.82s129an.6d playch10 PlayChoice-10 BIOS
+ 48de65dc rp2c0x.pal playch10 PlayChoice-10 BIOS
+
.. _mame-commandline-listroms:
**-listroms** / **-lr** [*<pattern>*...]
@@ -223,6 +372,20 @@ Example:
match the specified pattern(s). If no patterns are specified, the results
will include *all* supported systems and devices.
+ Example:
+ .. code-block:: bash
+
+ mame64 neogeo -listroms
+ ROMs required for driver "neogeo".
+ Name Size Checksum
+ sp-s2.sp1 131072 CRC(9036d879) SHA1(4f5ed7105b7128794654ce82b51723e16e389543)
+ sp-s.sp1 131072 CRC(c7f2fa45) SHA1(09576ff20b4d6b365e78e6a5698ea450262697cd)
+ sp-45.sp1 524288 CRC(03cc9f6a) SHA1(cdf1f49e3ff2bac528c21ed28449cf35b7957dc1)
+ ...
+ sm1.sm1 131072 CRC(94416d67) SHA1(42f9d7ddd6c0931fd64226a60dc73602b2819dcf)
+ 000-lo.lo 131072 CRC(5a86cff2) SHA1(5992277debadeb64d1c1c64b0a92d9293eaf7e4a)
+ sfix.sfix 131072 CRC(c2ea0cfd) SHA1(fd4a618cdcdbf849374f0a50dd8efe9dbab706c3)
+
.. _mame-commandline-listsamples:
**-listsamples** [<*pattern*>]
@@ -231,6 +394,19 @@ Example:
device names. If no pattern is specified, the results will be *all* systems
and devices.
+ Example:
+ .. code-block:: bash
+
+ mame64 armorap -listsamples
+ Samples required for driver "armorap".
+ loexp
+ jeepfire
+ hiexp
+ tankfire
+ tankeng
+ beep
+ chopper
+
.. _mame-commandline-verifyroms:
**-verifyroms** [<*pattern*>]
@@ -239,6 +415,13 @@ Example:
valid ZIP files or directories in the rompath are verified; however, you can
limit this list by specifying a *pattern* after the **-verifyroms** command.
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius -verifyroms
+ romset gradius [nemesis] is good
+ 1 romsets found, 1 were OK.
+
.. _mame-commandline-verifysamples:
**-verifysamples** [<*pattern*>]
@@ -248,6 +431,13 @@ Example:
can limit this list by specifying a *pattern* after the **-verifyroms**
command.
+ Example:
+ .. code-block:: bash
+
+ mame64 armorap -verifysamples
+ sampleset armorap [armora] is good
+ 1 samplesets found, 1 were OK.
+
.. _mame-commandline-romident:
**-romident** [*path\\to\\romstocheck.zip*]
@@ -262,6 +452,13 @@ Example:
* 8: means some files were identified
* 9: means no files were identified
+ Example:
+ .. code-block:: bash
+
+ mame64 unknown.rom -romident
+ Identifying unknown.rom....
+ unknown.rom = 456-a07.17l gradius Gradius (Japan, ROM version)
+
.. _mame-commandline-listdevices:
**-listdevices** / **-ld** [<*pattern*>]
@@ -274,6 +471,23 @@ Example:
provide will be visible with **-listdevices** as well. For instance,
installing a floppy controller into a PC will expose the disk drive slots.
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2e -listdevices
+ Driver apple2e (Apple //e):
+ <root> Apple //e
+ a2bus Apple II Bus
+ a2common Apple II Common Components @ 14.31 MHz
+ a2video Apple II video @ 14.31 MHz
+ aux Apple IIe AUX Slot
+ ext80 Apple IIe Extended 80-Column Card
+ auxbus Apple IIe AUX Bus
+ ay3600 AY-5-3600 Keyboard Encoder
+ ...
+ speaker Filtered 1-bit DAC
+ tape Cassette
+
.. _mame-commandline-listslots:
**-listslots** / **-lslot** [<*pattern*>]
@@ -289,6 +503,28 @@ Example:
The slot name (e.g. **ctrl1**) can be used from the command
line (**-ctrl1** in this case)
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2e -listslots
+ SYSTEM SLOT NAME SLOT OPTIONS SLOT DEVICE NAME
+ ---------------- ---------------- ---------------- ----------------------------
+ apple2e sl1 4play 4play Joystick Card (rev. B)
+ ...
+ aevm80 Applied Engineering Viewmaster 80
+ alfam2 ALF MC1 / Apple Music II
+ ...
+ zipdrive Zip Technologies ZipDrive
+
+ ...
+ aux ext80 Apple IIe Extended 80-Column Card
+ rw3 Applied Engineering RamWorks III
+ std80 Apple IIe Standard 80-Column Card
+
+ gameio compeyes Digital Vision ComputerEyes
+ joy Apple II analog joysticks
+ paddles Apple II paddles
+
.. _mame-commandline-listmedia:
**-listmedia** / **-lm** [<*pattern*>]
@@ -297,13 +533,54 @@ Example:
includes media types (cartridge, cassette, diskette and more) as well as
common file extensions which are supported.
+ Example:
+ .. code-block:: bash
+
+ mame64 coco3 -listmedia
+ SYSTEM MEDIA NAME (brief) IMAGE FILE EXTENSIONS SUPPORTED
+ ---------------- --------------------------- -------------------------------
+ coco3 cassette (cass) .wav .cas
+ printout (prin) .prn
+ cartridge (cart) .ccc .rom
+ floppydisk1 (flop1) .dmk .jvc .dsk .vdk .sdf .os9 .d77 .d88 .1dd .dfi .hfe .imd .ipf .mfi .mfm .td0 .cqm .cqi
+ floppydisk2 (flop2) .dmk .jvc .dsk .vdk .sdf .os9 .d77 .d88 .1dd .dfi .hfe .imd .ipf .mfi .mfm .td0 .cqm .cqi
+ harddisk1 (hard1) .vhd
+ harddisk2 (hard2) .vhd
+
.. _mame-commandline-listsoftware:
**-listsoftware** / **-lsoft** [<*pattern*>]
- Posts to screen all software lists which can be used by the entered
- *pattern* or system. Note that this is simply a copy/paste of the .XML file
- which reside in the HASH folder which are allowed to be used.
+ Displays the contents of all software lists that can be used by the system
+ or systems represented by *pattern*.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 coco3 -listsoftware
+ <?xml version="1.0"?>
+ <!DOCTYPE softwarelists [
+ <!ELEMENT softwarelists (softwarelist*)>
+ <!ELEMENT softwarelist (software+)>
+ <!ATTLIST softwarelist name CDATA #REQUIRED>
+ <!ATTLIST softwarelist description CDATA #IMPLIED>
+ <!ELEMENT software (description, year, publisher, info*, sharedfeat*, part*)>
+ ...
+ <softwarelists>
+ <softwarelist name="coco_cart" description="Tandy Radio Shack Color Computer cartridges">
+ <software name="7cardstd">
+ <description>7 Card Stud</description>
+ <year>1983</year>
+ <publisher>Tandy</publisher>
+ <info name="developer" value="Intelligent Software"/>
+ <info name="serial" value="26-3074"/>
+ <part name="cart" interface="coco_cart">
+ <dataarea name="rom" size="8192">
+ <rom name="7 card stud (1983) (26-3074) (intelligent software).rom" size="8192" crc="f38d8c97" sha1="5cfcb699ce09840dbb52714c8d91b3d86d3a86c3"/>
+ </dataarea>
+ </part>
+ </software>
+ ...
.. _mame-commandline-verifysoftware:
@@ -314,12 +591,49 @@ Example:
verified; however, you can limit this list by specifying a specific driver
name or *pattern* after the **-verifysoftware** command.
+ Example:
+ .. code-block:: bash
+
+ mame64 coco3 -verifysoftware
+ romset coco_cart:7cardstd is good
+ coco_cart:amazing: a mazing world of malcom mortar (1987)(26-3160)(zct systems).rom (16384 bytes) - NEEDS REDUMP
+ romset coco_cart:amazing is best available
+ coco_cart:amazing1: a mazing world of malcom mortar (1987)(26-3160)(zct systems)[a].rom (16384 bytes) - NEEDS REDUMP
+ romset coco_cart:amazing1 is best available
+ romset coco_cart:androne is good
+ ...
+
.. _mame-commandline-getsoftlist:
**-getsoftlist** / **-glist** [<*pattern*>]
- Posts to screen a specific software list which matches with the system name
- provided.
+ Displays the contents of a specific softlist with the filename represented
+ by *pattern*.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 -getsoftlist apple2_flop_orig
+ <?xml version="1.0"?>
+ <!DOCTYPE softwarelists [
+ <!ELEMENT softwarelists (softwarelist*)>
+ <!ELEMENT softwarelist (software+)>
+ <!ATTLIST softwarelist name CDATA #REQUIRED>
+ <!ATTLIST softwarelist description CDATA #IMPLIED>
+ <!ELEMENT software (description, year, publisher, info*, sharedfeat*, part*)>
+ <!ATTLIST software name CDATA #REQUIRED>
+ <!ATTLIST software cloneof CDATA #IMPLIED>
+ <!ATTLIST software supported (yes|partial|no) "yes">
+ <!ELEMENT description (#PCDATA)>
+ <!ELEMENT year (#PCDATA)>
+ <!ELEMENT publisher (#PCDATA)>
+ <!ELEMENT info EMPTY>
+ <!ATTLIST info name CDATA #REQUIRED>
+ <!ATTLIST info value CDATA #IMPLIED>
+ <!ELEMENT sharedfeat EMPTY>
+ <!ATTLIST sharedfeat name CDATA #REQUIRED>
+ <!ATTLIST sharedfeat value CDATA #IMPLIED>
+ ...
.. _mame-commandline-verifysoftlist:
@@ -331,9 +645,27 @@ Example:
by specifying a specific softwarelistname (without .XML) after the
-verifysoftlist command.
+ Example:
+ .. code-block:: bash
+
+ mame64 -verifysoftlist apple2_flop_orig
+ romset apple2_flop_orig:agentusa is good
+ romset apple2_flop_orig:airheart is good
+ romset apple2_flop_orig:aplpanic is good
+ romset apple2_flop_orig:alambush is good
+ romset apple2_flop_orig:ankh is good
+ romset apple2_flop_orig:aplcdspd is good
+ romset apple2_flop_orig:agalxian is good
+ romset apple2_flop_orig:aquatron is good
+ romset apple2_flop_orig:archon is good
+ romset apple2_flop_orig:archon2 is good
+ romset apple2_flop_orig:ardyardv is good
+ romset apple2_flop_orig:autobahn is good
+ ...
.. _osd-commandline-options:
+
OSD-related Options
-------------------
@@ -346,81 +678,244 @@ OSD-related Options
**SCRLOCK** on other operating systems (including Windows and Linux). Use
**FN-Delete** on Macintosh computers with notebook/compact keyboards.
+ Example:
+ .. code-block:: bash
+
+ mame64 ibm5150 -uimodekey DEL
+
.. _mame-commandline-uifontprovider:
**-uifontprovider**
- Chooses provider for UI font rendering.
+ Chooses provider for UI font rendering. The default setting is ``auto``.
+
+.. list-table:: Supported UI font providers per-platform
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - **Microsoft Windows**
+ - win
+ - dwrite
+ - none
+ - auto
+ -
+ - sdl [#UIFPSDLWindows]_.
+ * - **macOS**
+ -
+ -
+ - none
+ - auto
+ - osx
+ - sdl
+ * - **Linux**
+ -
+ -
+ - none
+ - auto
+ -
+ - sdl
+
+.. rubric:: Footnotes
+
+.. [#UIFPSDLWindows] SDL support on Windows requires that you compile MAME with
+ the support in. By default SDL is not included in Windows
+ builds of MAME.
+
+Example:
+ .. code-block:: bash
-| On Windows, you can choose from: ``win``, ``dwrite``, ``none`` or ``auto``.
-| On macOS, you can choose from: ``osx``, ``none`` or ``auto``.
-| On other platforms, you can choose from: ``sdl``, ``none`` or ``auto``.
-|
-| Default setting is ``auto``.
-|
+ mame64 ajax -uifontprovider dwrite
.. _mame-commandline-keyboardprovider:
**-keyboardprovider**
- Chooses how MAME will get keyboard input.
+ Chooses how MAME will get keyboard input. The default is ``auto``.
+
+.. list-table:: Supported keyboard input providers per-platform
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - **Microsoft Windows**
+ - auto [#KBIPAutoWindows]_.
+ - rawinput
+ - dinput
+ - win32
+ - none
+ - sdl [#KBIPSDLWindows]_.
+ * - **SDL (macOS and Linux)**
+ - auto [#KBIPAutoSDL]_.
+ -
+ -
+ -
+ - none
+ - sdl
+ * - **Linux**
+ - auto [#KBIPAutoSDL]_.
+ -
+ -
+ -
+ - none
+ - sdl
+
+.. rubric:: Footnotes
+
+.. [#KBIPAutoWindows] ``auto`` on Windows will try ``rawinput`` with
+ fallback to ``dinput``.
+
+.. [#KBIPSDLWindows] SDL support on Windows requires that you compile MAME with
+ the support in. By default SDL is not included in Windows
+ builds of MAME.
+
+.. [#KBIPAutoSDL] ``auto`` on SDL will default to ``sdl``.
+
+.. Tip:: Note that user-mode keyboard emulation tools such as joy2key will
+ almost certainly require the use of **-keyboardprovider win32** on
+ Windows machines.
-| On Windows, you can choose from: ``auto``, ``rawinput``, ``dinput``, ``win32``, or ``none``
-| On SDL, you can choose from: ``auto``, ``sdl``, ``none``
-|
-| The default is ``auto``.
-|
-| On Windows, ``auto`` will try ``rawinput`` with fallback to ``dinput``.
-| On SDL, ``auto`` will default to ``sdl``.
-|
+Example:
+ .. code-block:: bash
+
+ mame64 c64 -keyboardprovider win32
.. _mame-commandline-mouseprovider:
**\-mouseprovider**
- Chooses how MAME will get mouse input.
+ Chooses how MAME will get mouse input. The default is ``auto``.
+
+.. list-table:: Supported mouse input providers per-platform
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - **Microsoft Windows**
+ - auto [#MIPAutoWindows]_.
+ - rawinput
+ - dinput
+ - win32
+ - none
+ - sdl [#MIPSDLWindows]_.
+ * - **SDL (macOS and Linux)**
+ - auto [#MIPAutoSDL]_.
+ -
+ -
+ -
+ - none
+ - sdl
+ * - **Linux**
+ - auto [#MIPAutoSDL]_.
+ -
+ -
+ -
+ - none
+ - sdl
+
+.. rubric:: Footnotes
+
+.. [#MIPAutoWindows] On Windows, ``auto`` will try ``rawinput`` with fallback
+ to ``dinput``.
+
+.. [#MIPSDLWindows] SDL support on Windows requires that you compile MAME with
+ the support in. By default SDL is not included in Windows
+ builds of MAME.
+
+.. [#MIPAutoSDL] ``auto`` on SDL will default to ``sdl``.
-| On Windows, you can choose from: ``auto``, ``rawinput``, ``dinput``, ``win32``, or ``none``
-| On SDL, you can choose from: ``auto``, ``sdl``, ``none``
-|
-| The default is ``auto``.
-|
-| On Windows, ``auto`` will try ``rawinput`` with fallback to ``dinput``.
-| On SDL, ``auto`` will default to ``sdl``.
-|
+Example:
+ .. code-block:: bash
+
+ mame64 indy_4610 -mouseprovider win32
.. _mame-commandline-lightgunprovider:
**\-lightgunprovider**
- Chooses how MAME will get light gun input.
+ Chooses how MAME will get light gun input. The default is ``auto``.
+
+.. list-table:: Supported light gun input providers per-platform
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - **Microsoft Windows**
+ - auto [#LGIPAutoWindows]_.
+ - rawinput
+ - win32
+ - none
+ -
+ -
+ * - **macOS**
+ - auto [#LGIPAutoSDL]_.
+ -
+ -
+ - none
+ -
+ -
+ * - **Linux**
+ - auto [#LGIPAutoLinux]_.
+ -
+ -
+ - none
+ -
+ - x11
+
+.. rubric:: Footnotes
+
+.. [#LGIPAutoWindows] On Windows, auto will try ``rawinput`` with fallback to
+ ``win32``, or ``none`` if it doesn't find any.
+
+.. [#LGIPAutoSDL] On non-Linux SDL, ``auto`` will default to ``none``.
+
+.. [#LGIPAutoLinux] On SDL/Linux, ``auto`` will default to ``x11``, or ``none``
+ if it doesn't find any.
+
+Example:
+ .. code-block:: bash
-| On Windows, you can choose from: ``auto``, ``rawinput``, ``win32``, or ``none``
-| On SDL, you can choose from: ``auto``, ``x11`` or ``none``
-|
-| The default is ``auto``.
-|
-| On Windows, auto will try ``rawinput`` with fallback to ``win32``, or ``none`` if it doesn't find any.
-| On SDL/Linux, ``auto`` will default to ``x11``, or ``none`` if it doesn't find any.
-| On other SDL, ``auto`` will default to ``none``.
-|
+ mame64 lethalen -lightgunprovider x11
.. _mame-commandline-joystickprovider:
**\-joystickprovider**
- Chooses how MAME will get joystick input.
+ Chooses how MAME will get joystick input. The default is ``auto``.
+
+.. list-table:: Supported joystick input providers per-platform
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - **Microsoft Windows**
+ - auto [#JIPAutoWindows]_.
+ - winhybrid
+ - dinput
+ - xinput
+ - none
+ - sdl
+ * - **SDL**
+ - auto [#JIPAutoSDL]_.
+ -
+ -
+ -
+ - none
+ - sdl
+
+.. rubric:: Footnotes
+
+.. [#JIPAutoWindows] On Windows, auto will default to ``dinput``.
+
+.. [#JIPAutoSDL] On SDL, auto will default to ``sdl``.
+
+.. 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.
+
+Example:
+ .. code-block:: bash
+
+ mame64 mk2 -joystickprovider winhybrid
-| On Windows, you can choose from: ``auto, ``winhybrid``, ``dinput``, ``xinput``, or ``none``
-| On SDL, you can choose from: ``auto``, ``sdl``, ``none``
-|
-| The default is ``auto``.
-|
-| On Windows, auto will default to ``dinput``.
-|
-| 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.
-| On SDL, auto will default to ``sdl``.
-|
+.. Tip:: On Windows, winhybrid is likely to give the best experience by
+ supporting both XInput and DirectInput controllers.
OSD CLI Options
@@ -432,12 +927,37 @@ OSD CLI Options
Create a list of available MIDI I/O devices for use with emulation.
+ Example:
+ .. code-block:: bash
+
+ mame64 -listmidi
+ MIDI input ports:
+
+ MIDI output ports:
+ Microsoft MIDI Mapper (default)
+ Microsoft GS Wavetable Synth
+
.. _mame-commandline-listnetwork:
**\-listnetwork**
Create a list of available Network Adapters for use with emulation.
+ Example 1:
+ .. code-block:: bash
+
+ mame64 -listnetwork
+ No network adapters were found
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 -listnetwork
+ Available network adapters:
+ Local Area Connection
+
+.. Tip:: On Windows, you'll need the TAP driver from OpenVPN for MAME to see
+ any network adapters.
OSD Output Options
@@ -447,12 +967,23 @@ OSD Output Options
**\-output**
- Chooses how MAME will handle processing of output notifiers.
+ Chooses how MAME will handle processing of output notifiers. These are used
+ to connect external outputs such as the LED lights for the Player 1/2 start
+ buttons on certain arcade machines.
You can choose from: ``auto``, ``none``, ``console`` or ``network``
Note that network port is fixed at 8000.
+ Example:
+ .. code-block:: bash
+
+ mame64 asteroid -output console
+ led0 = 1
+ led0 = 0
+ ...
+ led0 = 1
+ led0 = 0
Configuration Options
@@ -487,6 +1018,10 @@ Configuration Options
The default is ON (**-readconfig**).
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2ee -noreadconfig -sl6 diskii -sl7 cffa2 -hard1 TotalReplay.2mg
Core Search Path Options
@@ -500,9 +1035,14 @@ Core Search Path Options
The default is ``.`` (that is, in the current working directory).
+ Example:
+ .. code-block::
+
+ mame64 -homepath c:\mame\lua
+
.. _mame-commandline-rompath:
-**-rompath** / **-rp** / **-biospath** / **-bp** *<path>*
+**-rompath** / **-rp** *<path>*
Specifies one or more paths within which to find ROM or disk images.
Multiple paths can be specified by separating them with semicolons.
@@ -510,6 +1050,11 @@ Core Search Path Options
The default is ``roms`` (that is, a directory ``roms`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -rompath c:\mame\roms;c:\roms\another
+
.. _mame-commandline-hashpath:
**-hashpath** / **-hash_directory** / **-hash** *<path>*
@@ -520,6 +1065,11 @@ Core Search Path Options
The default is ``hash`` (that is, a directory ``hash`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -hashpath c:\mame\hash;c:\roms\softlists
+
.. _mame-commandline-samplepath:
**-samplepath** / **-sp** *<path>*
@@ -530,6 +1080,11 @@ Core Search Path Options
The default is ``samples`` (that is, a directory ``samples`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -samplepath c:\mame\samples;c:\roms\samples
+
.. _mame-commandline-artpath:
**-artpath** *<path>* *<path>*
@@ -540,6 +1095,11 @@ Core Search Path Options
The default is ``artwork`` (that is, a directory ``artwork`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -artpath c:\mame\artwork;c:\emu\shared-artwork
+
.. _mame-commandline-ctrlrpath:
**-ctrlrpath** *<path>*
@@ -550,6 +1110,11 @@ Core Search Path Options
The default is ``ctrlr`` (that is, a directory ``ctrlr`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -ctrlrpath c:\mame\ctrlr;c:\emu\controllers
+
.. _mame-commandline-inipath:
**-inipath** *<path>*
@@ -574,6 +1139,11 @@ Core Search Path Options
directory, followed by the current working directory, and finally the
directory ``ini`` in the current working directory).
+ Example:
+ .. code-block::
+
+ mame64 -inipath c:\users\thisuser\documents\mameini
+
.. _mame-commandline-fontpath:
**-fontpath** *<path>*
@@ -584,6 +1154,11 @@ Core Search Path Options
The default is ``.`` (that is, search in the current working directory).
+ Example:
+ .. code-block::
+
+ mame64 -fontpath c:\mame\;c:\emu\artwork\mamefonts
+
.. _mame-commandline-cheatpath:
**-cheatpath** *<path>*
@@ -594,6 +1169,11 @@ Core Search Path Options
The default is ``cheat`` (that is, a folder called ``cheat`` located in the
current working directory).
+ Example:
+ .. code-block::
+
+ mame64 -cheatpath c:\mame\cheat;c:\emu\cheats
+
.. _mame-commandline-crosshairpath:
**-crosshairpath** *<path>*
@@ -604,6 +1184,11 @@ Core Search Path Options
The default is ``crsshair`` (that is, a directory ``crsshair`` in the
current working directory).
+ Example:
+ .. code-block::
+
+ mame64 -crosshairpath c:\mame\crsshair;c:\emu\artwork\crosshairs
+
.. _mame-commandline-pluginspath:
**-pluginspath** *<path>*
@@ -613,6 +1198,11 @@ Core Search Path Options
The default is ``plugins`` (that is, a directory ``plugins`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -pluginspath c:\mame\plugins;c:\emu\lua
+
.. _mame-commandline-languagepath:
**-languagepath** *<path>*
@@ -623,6 +1213,11 @@ Core Search Path Options
The default is ``language`` (that is, a directory ``language`` in the
current working directory).
+ Example:
+ .. code-block::
+
+ mame64 -languagepath c:\mame\language;c:\emu\mame-languages
+
.. _mame-commandline-swpath:
**-swpath** *<path>*
@@ -632,6 +1227,11 @@ Core Search Path Options
The default is ``sofware`` (that is, a directory ``software`` in the current
working directory).
+ Example:
+ .. code-block::
+
+ mame64 -swpath c:\mame\software;c:\emu\mydisks
+
Core Output Directory Options
-----------------------------
@@ -650,6 +1250,11 @@ Core Output Directory Options
directory). If this directory does not exist, it will be created
automatically.
+ Example:
+ .. code-block::
+
+ mame64 -cfg_directory c:\mame\cfg
+
.. _mame-commandline-nvramdirectory:
**-nvram_directory** *<path>*
@@ -663,6 +1268,11 @@ Core Output Directory Options
working directory)). If this directory does not exist, it will be created
automatically.
+ Example:
+ .. code-block::
+
+ mame64 -nvram_directory c:\mame\nvram
+
.. _mame-commandline-inputdirectory:
**-input_directory** *<path>*
@@ -675,6 +1285,11 @@ Core Output Directory Options
directory). If this directory does not exist, it will be created
automatically.
+ Example:
+ .. code-block::
+
+ mame64 -input_directory c:\mame\inp
+
.. _mame-commandline-statedirectory:
**-state_directory** *<path>*
@@ -687,6 +1302,11 @@ Core Output Directory Options
directory). If this directory does not exist, it will be created
automatically.
+ Example:
+ .. code-block::
+
+ mame64 -state_directory c:\mame\sta
+
.. _mame-commandline-snapshotdirectory:
**-snapshot_directory** *<path>*
@@ -698,6 +1318,11 @@ Core Output Directory Options
working directory). If this directory does not exist, it will be created
automatically.
+ Example:
+ .. code-block::
+
+ mame64 -snapshot_directory c:\mame\snap
+
.. _mame-commandline-diffdirectory:
**-diff_directory** *<path>*
@@ -712,6 +1337,11 @@ Core Output Directory Options
working directory). If this directory does not exist, it will be created
automatically.
+ Example:
+ .. code-block::
+
+ mame64 -diff_directory c:\mame\diff
+
.. _mame-commandline-commentdirectory:
**-comment_directory** *<path>*
@@ -724,6 +1354,10 @@ Core Output Directory Options
current working directory). If this directory does not exist, it will be
created automatically.
+ Example:
+ .. code-block::
+
+ mame64 -comment_directory c:\mame\comments
Core State/Playback Options
@@ -745,6 +1379,11 @@ Core State/Playback Options
states can be loaded by executing the debugger **rewind** (or **rw**)
command.
+ Example:
+ .. code-block::
+
+ mame64 -norewind
+
.. _mame-commandline-rewindcapacity:
**-rewind_capacity** *<value>*
@@ -755,6 +1394,11 @@ Core State/Playback Options
current savestate size disables rewind. Values below 0 are automatically
clamped to 0.
+ Example:
+ .. code-block::
+
+ mame64 -rewind_capacity 30
+
.. _mame-commandline-state:
**-state** *<slot>*
@@ -762,6 +1406,11 @@ Core State/Playback Options
Immediately after starting the specified system, will cause the save state
in the specified <slot> to be loaded.
+ Example:
+ .. code-block::
+
+ mame64 -state 1
+
.. _mame-commandline-noautosave:
**-[no]autosave**
@@ -773,18 +1422,31 @@ Core State/Playback Options
The default is OFF (**-noautosave**).
+ Example:
+ .. code-block::
+
+ mame64 -autosave
+
.. _mame-commandline-playback:
**-playback** / **-pb** *<filename>*
Specifies a file from which to play back a series of inputs. This feature
does not work reliably for all systems, but can be used to watch a
- previously recorded game session from start to finish. In order to make
- things consistent, you should only record and playback with all
- configuration (.cfg), NVRAM (.nv), and memory card files deleted.
+ previously recorded game session from start to finish.
The default is ``NULL`` (no playback).
+ Example:
+ .. code-block::
+
+ mame64 pacman -playback worldrecord
+
+.. Tip:: You may experience desync in playback if the configuration, NVRAM, and
+ memory card files don't match the original; this is why it is suggested
+ you should only record and playback with all configuration (.cfg),
+ NVRAM (.nv), and memory card files deleted.
+
.. _mame-commandline-exitafterplayback:
**-[no]exit_after_playback**
@@ -795,19 +1457,31 @@ Core State/Playback Options
The default is OFF (**-noexit_after_playback**).
+ Example:
+ .. code-block::
+
+ mame64 pacman -playback worldrecord -exit_after_playback
+
.. _mame-commandline-record:
**-record** / **-rec** *<filename>*
Specifies a file to record all input from a session. This can be used to
record a session for later playback. This feature does not work reliably
- for all systems, but can be used to watch a previously recorded session from
- start to finish. In order to make things consistent, you should only record
- and playback with all configuration (.cfg), NVRAM (.nv), and memory card
- files deleted.
+ for all systems, but can be used to record a session from start to finish.
The default is ``NULL`` (no recording).
+ Example:
+ .. code-block::
+
+ mame64 pacman -record worldrecord
+
+.. Tip:: You may experience desync in playback if the configuration, NVRAM, and
+ memory card files don't match the original; this is why it is suggested
+ you should only record and playback with all configuration (.cfg),
+ NVRAM (.nv), and memory card files deleted.
+
.. _mame-commandline-recordtimecode:
**-record_timecode**
@@ -819,6 +1493,11 @@ Core State/Playback Options
By default, no timecode file is saved.
+ Example:
+ .. code-block::
+
+ mame64 pacman -record worldrecord -record_timecode
+
.. _mame-commandline-mngwrite:
**-mngwrite** *<filename>*
@@ -831,6 +1510,11 @@ Core State/Playback Options
The default is ``NULL`` (no recording).
+ Example:
+ .. code-block::
+
+ mame64 pacman -mngwrite pacman-video
+
.. _mame-commandline-aviwrite:
**-aviwrite** *<filename>*
@@ -846,6 +1530,11 @@ Core State/Playback Options
The default is ``NULL`` (no recording).
+ Example:
+ .. code-block::
+
+ mame64 pacman -playback worldrecord -exit_after_playback -aviwrite worldrecord
+
.. _mame-commandline-wavwrite:
**-wavwrite** *<filename>*
@@ -857,6 +1546,11 @@ Core State/Playback Options
.. _mame-commandline-snapname:
+ Example:
+ .. code-block::
+
+ mame64 pacman -wavewrite pacsounds
+
**-snapname** *<name>*
Describes how MAME should name files for snapshots. <name> is a string that
@@ -877,16 +1571,26 @@ Core State/Playback Options
floppy disks, you can also use the ``%d_[media]`` indicator. Replace [media]
with the media switch you want to use.
- A few examples:
+ Example 1:
+ .. code-block::
+
+ mame64 robby -snapname foo\%g%i
- If you use **mame robby -snapname foo/%g%i** snapshots will be saved as
- ``snaps\\foo\\robby0000.png`` , ``snaps\\foo\\robby0001.png`` and so on.
+ Snapshots will be saved as ``snaps\foo\robby0000.png``, ``snaps\foo\robby0001.png`` and so on.
- If you use **mame nes -cart robby -snapname %g/%d_cart** snapshots will be
- saved as ``snaps\\nes\\robby.png``.
+ Example 2:
+ .. code-block::
- If you use **mame c64 -flop1 robby -snapname %g/%d_flop1/%i** snapshots will
- be saved as ``snaps\\c64\\robby\\0000.png``.
+ mame64 nes -cart robby -snapname %g\%d_cart
+
+ Snapshots will be saved as ``snaps\nes\robby.png``.
+
+ Example 3:
+ .. code-block::
+
+ mame64 c64 -flop1 robby -snapname %g\%d_flop1/%i
+
+ Snapshots will be saved as ``snaps\c64\robby\0000.png``.
.. _mame-commandline-snapsize:
@@ -896,11 +1600,19 @@ Core State/Playback Options
will create snapshots at the system's current resolution in raw pixels, and
will create movies at the system's starting resolution in raw pixels. If
you specify this option, then MAME will create both snapshots and movies at
- the size specified, and will bilinear filter the result. Note that this
- size does not automatically rotate if the system is vertically oriented.
+ the size specified, and will bilinear filter the result.
The default is ``auto``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -snapsize 1920x1080
+
+.. Tip:: -snapsize does not automatically rotate if the system is vertically
+ oriented, so for vertical systems you'll want to swap the width and
+ height options.
+
.. _mame-commandline-snapview:
**-snapview** *<viewname>*
@@ -920,6 +1632,12 @@ Core State/Playback Options
The default value is ``internal``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pang -snapview pixel
+
+
.. _mame-commandline-nosnapbilinear:
**-[no]snapbilinear**
@@ -929,6 +1647,11 @@ Core State/Playback Options
The default is ON (**-snapbilinear**).
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -nosnapbilinear
+
.. _mame-commandline-statename:
**-statename** *<name>*
@@ -947,16 +1670,27 @@ Core State/Playback Options
floppy disks, you can also use the ``%d_[media]`` indicator. Replace
``[media]`` with the media switch you want to use.
- A few examples:
+ Example 1:
+ .. code-block::
- If you use **mame robby -statename foo/%g** save states will be stored
- inside ``sta\\foo\\robby\\``.
+ mame64 robby -statename foo\%g
+ All save states will be stored inside sta\foo\robby\
- If you use **mame nes -cart robby -statename %g/%d_cart** save states will
- be stored inside ``sta\\nes\\robby\\``.
+ Example 2:
+ .. code-block::
+
+ mame64 nes -cart robby -statename %g/%d_cart
+ All save states will be stored inside sta\nes\robby\
+
+ Example 3:
+ .. code-block::
+
+ mame64 c64 -flop1 robby -statename %g/%d_flop1
+ All save states will be stored inside sta\c64\robby\
+
+.. Tip:: Note that even on Microsoft Windows, you should use ``/`` as your
+ path seperator for **-statename**
- If you use **mame c64 -flop1 robby -statename %g/%d_flop1** save states will
- be stored inside 'sta\\c64\\robby\\'.
.. _mame-commandline-noburnin:
@@ -976,6 +1710,10 @@ Core State/Playback Options
The default is OFF (**-noburnin**).
+ Example:
+ .. code-block:: bash
+
+ mame64 neogeo -burnin
Core Performance Options
@@ -991,6 +1729,11 @@ Core Performance Options
This is off by default (**-noautoframeskip**).
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius4 -autoframeskip
+
.. _mame-commandline-frameskip:
**-frameskip** / **-fs** *<level>*
@@ -1003,6 +1746,11 @@ Core Performance Options
The default value is **-frameskip 0**, which skips no frames.
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius4 -frameskip 2
+
.. _mame-commandline-secondstorun:
**-seconds_to_run** / **-str** *<seconds>*
@@ -1015,6 +1763,11 @@ Core Performance Options
**-str** option will write a screenshot called ``final.png`` to the system's
snapshot directory.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -seconds_to_run 60
+
.. _mame-commandline-nothrottle:
**-[no]throttle**
@@ -1028,6 +1781,11 @@ Core Performance Options
The default is to enable throttling (**-throttle**).
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -nothrottle
+
.. _mame-commandline-nosleep:
**-[no]sleep**
@@ -1040,6 +1798,11 @@ Core Performance Options
The default is on (**-sleep**).
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius 4 -nosleep
+
.. _mame-commandline-speed:
**-speed** *<factor>*
@@ -1054,6 +1817,11 @@ Core Performance Options
The default is ``1.0`` (normal speed).
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -speed 1.25
+
.. _mame-commandline-norefreshspeed:
**-[no]refreshspeed** / **-[no]rs**
@@ -1067,6 +1835,11 @@ Core Performance Options
The default is off (**-norefreshspeed**).
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -refreshspeed
+
.. _mame-commandline-numprocessors:
**-numprocessors** / **-np** **auto**\ \|\ *<value>*
@@ -1078,6 +1851,11 @@ Core Performance Options
The default is ``auto``.
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius4 -numprocessors 2
+
.. _mame-commandline-bench:
**-bench** *<n>*
@@ -1087,6 +1865,11 @@ Core Performance Options
**-str** *<n>* **-video none -sound none -nothrottle**
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius4 -bench 300
+
.. _mame-commandline-lowlatency:
**-lowlatency**
@@ -1099,6 +1882,12 @@ Core Performance Options
systems (especially newer 3D-based systems or systems that run software
akin to an operating system), so the default is off (**-nolowlatency**).
+ Example:
+ .. code-block:: bash
+
+ mame64 bgaregga -lowlatency
+
+
Core Rotation Options
---------------------
@@ -1114,6 +1903,10 @@ Core Rotation Options
The default is ON (**-rotate**).
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -norotate
.. _mame-commandline-noror:
@@ -1130,6 +1923,16 @@ Core Rotation Options
The default for both of these options is OFF (**-noror -norol**).
+ Example 1:
+ .. code-block:: bash
+
+ mame64 pacman -ror
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 pacman -rol
+
.. _mame-commandline-noautoror:
@@ -1146,6 +1949,20 @@ Core Rotation Options
vertically in one of the directions you can handle. If your screen only
pivots counter-clockwise, use **-autoror**.
+ Example 1:
+ .. code-block:: bash
+
+ mame64 pacman -autoror
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 pacman -autorol
+
+.. Tip:: If you have a display that can be rotated, **-autorol** or
+ **-autoror** will allow you to get a larger display for both horizontal
+ and vertical systems.
+
.. _mame-commandline-noflipx:
**-[no]flipx**
@@ -1160,6 +1977,16 @@ Core Rotation Options
The default for both of these options is OFF (**-noflipx -noflipy**).
+ Example 1:
+ .. code-block:: bash
+
+ mame64 -flipx pacman
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 -flipy suprmrio
+
Core Video Options
------------------
@@ -1203,18 +2030,35 @@ Core Video Options
| The default on all other systems is ``soft``.
|
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius3 -video bgfx
+
.. _mame-commandline-numscreens:
**-numscreens** *<count>*
- Tells MAME how many output windows to create. For most systems, a single
- output window is all you need, but some systems originally used multipl
- screens (*e.g. Darius and PlayChoice-10 arcade machines*). Each screen
- (up to 4) has its own independent settings for physical monitor, aspect
- ratio, resolution, and view, which can be set using the options below.
+ Tells MAME how many output windows or screens to create. For most systems,
+ a single output window is all you need, but some systems originally used
+ multiple screens (*e.g. Darius and PlayChoice-10 arcade machines*). Some
+ systems with front panel controls and/or status lights also may let you put
+ these in different windows/screens. Each screen (up to 4) has its own
+ independent settings for physical monitor, aspect ratio, resolution, and
+ view, which can be set using the options below.
The default is ``1``.
+ Example 1:
+ .. code-block:: bash
+
+ mame64 darius -numscreens 3
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 pc_cntra -numscreens 2
+
.. _mame-commandline-window:
**-[no]window** / **-[no]w**
@@ -1223,6 +2067,11 @@ Core Video Options
The default is OFF (**-nowindow**).
+ Example:
+ .. code-block:: bash
+
+ mame64 coco3 -window
+
.. _mame-commandline-maximize:
**-[no]maximize** / **-[no]max**
@@ -1236,6 +2085,11 @@ Core Video Options
The default is ON (**-maximize**).
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2e -window -nomaximize
+
.. _mame-commandline-keepaspect:
**-[no]keepaspect** / **-[no]ka**
@@ -1266,6 +2120,11 @@ Core Video Options
systems beyond their original aspect ratio will mangle the appearance of the
system in ways that no filtering or shaders can repair.
+ Example:
+ .. code-block:: bash
+
+ mame64 sf2ua -nokeepaspect
+
.. _mame-commandline-waitvsync:
**-[no]waitvsync**
@@ -1300,6 +2159,11 @@ Core Video Options
The default is OFF (**-nowaitvsync**).
+ Example:
+ .. code-block:: bash
+
+ mame64 gradius2 -waitvsync
+
.. _mame-commandline-syncrefresh:
**-[no]syncrefresh**
@@ -1316,6 +2180,12 @@ Core Video Options
The default is OFF (**-nosyncrefresh**).
.. _mame-commandline-prescale:
+ Example:
+ .. code-block:: bash
+
+ mame64 mk -syncrefresh
+
+.. Tip:: **-syncrefresh** can be helpful for G-Sync or FreeSync display users.
**-prescale** *<amount>*
@@ -1328,8 +2198,13 @@ Core Video Options
The default is ``1``.
- This is supported with all video output types (``bgfx``, ``d3d``, etc) on
- Windows and is **ONLY** supported with OpenGL on other platforms.
+ This is supported with all video output types ( ``bgfx``, ``d3d``, etc) on
+ Windows and is supported with BGFX and OpenGL on other platforms.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -video d3d -prescale 3
.. _mame-commandline-filter:
@@ -1348,6 +2223,11 @@ Core Video Options
Use ``bgfx_screen_chains`` in your INI file(s) to adjust filtering with the
BGFX video system.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -nofilter
+
.. _mame-commandline-unevenstretch:
**-[no]unevenstretch**
@@ -1357,6 +2237,11 @@ Core Video Options
The default is ON. (**-unevenstretch**)
+ Example:
+ .. code-block:: bash
+
+ mame64 dkong -nounevenstretch
+
Core Full Screen Options
------------------------
@@ -1370,22 +2255,24 @@ Core Full Screen Options
On modern video cards, there is little reason to switch resolutions unless
you are trying to achieve the "exact" pixel resolutions of the original
- systems, which requires significant tweaking. This option is also useful
+ systems, which requires significant tweaking. This is also true
on LCD displays, since they run with a fixed resolution and switching
resolutions on them is just silly. This option does not work with
- **-video gdi**.
+ **-video gdi** and **-video bgfx**.
The default is OFF (**-noswitchres**).
+ Example:
+ .. code-block:: bash
+
+ mame64 kof97 -video d3d -switchres -resolution 1280x1024
+
Core Per-Window Options
-----------------------
.. _mame-commandline-screen:
-NOTE: **Multiple Screens may fail to work correctly on some Mac machines as of
-right now.**
-
**-screen** *<display>*
**-screen0** *<display>*
@@ -1412,6 +2299,22 @@ right now.**
to the specific window. The **-screen** parameter applies to all windows.
The window-specific options override values from the all window option.
+ Example 1:
+ .. code-block:: bash
+
+ mame64 pc_cntra -numscreens 2 -screen0 \\.\DISPLAY1 -screen1 \\.\DISPLAY2
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 darius -numscreens 3 -screen0 \\.\DISPLAY1 -screen1 \\.\DISPLAY3 -screen2 \\.\DISPLAY2
+
+.. Tip:: Using **-verbose** will tell you which displays you have on your
+ system, where they are connected, and what their current resolutions
+ are.
+
+.. Tip:: **Multiple Screens may fail to work correctly on some Mac machines as
+ of right now.**
.. _mame-commandline-aspect:
@@ -1440,6 +2343,16 @@ right now.**
to the specific window. The **-aspect** parameter applies to all windows.
The window-specific options override values from the all window option.
+ Example 1:
+ .. code-block:: bash
+
+ mame64 contra -aspect 16:9
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 pc_cntra -numscreens 2 -aspect0 16:9 -aspect1 5:4
+
.. _mame-commandline-resolution:
@@ -1473,6 +2386,10 @@ right now.**
applies to all windows. The window-specific options override values from
the all window option.
+ Example:
+ .. code-block:: bash
+
+ mame64 pc_cntra -numscreens 2 -resolution0 1920x1080 -resolution1 1280x1024
.. _mame-commandline-view:
@@ -1499,6 +2416,11 @@ right now.**
specific window. The **-view** parameter applies to all windows. The
window-specific options override values from the all window option.
+ Example:
+ .. code-block:: bash
+
+ mame64 contra -view native
+
Core Artwork Options
--------------------
@@ -1514,12 +2436,32 @@ Core Artwork Options
The default is OFF **-noartwork_crop**.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -artwork_crop
+
+.. Tip:: **-artwork_crop** is great for widescreen displays. You will get a
+ full-sized system display and the artwork will fill the empty space on
+ the sides as much as possible.
+
.. _mame-commandline-fallbackartwork:
**-fallback_artwork**
Specifies fallback artwork if no external artwork or internal driver layout
- is defined.
+ is defined. If external artwork for the system is present or a layout is
+ included in the driver for the system, then that will take precedence.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 coco -fallback_artwork suprmrio
+
+.. Tip:: You can use **fallback_artwork <artwork name>** in
+ ``horizontal.ini`` and ``vertical.ini`` to specify different
+ fallback artwork choices for horizontal and vertical systems.
+
.. _mame-commandline-overrideartwork:
@@ -1527,6 +2469,10 @@ Core Artwork Options
Specifies override artwork for external artwork and internal driver layout.
+ Example:
+ .. code-block:: bash
+
+ mame64 galaga -override_artwork puckman
Core Screen Options
@@ -1540,11 +2486,14 @@ Core Screen Options
This option does not affect the artwork or other parts of the display.
Using the MAME UI, you can individually set the brightness for each system
screen; this option controls the initial value for all visible system
- screens. The standard value is ``1.0``. Selecting lower values
+ screens. The standard and default value is ``1.0``. Selecting lower values
(down to 0.1) will produce a darkened display, while selecting higher values
(up to 2.0) will give a brighter display.
- The default is ``1.0``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -brightness 0.5
.. _mame-commandline-contrast:
@@ -1554,11 +2503,14 @@ Core Screen Options
does not affect the artwork or other parts of the display. Using the MAME
UI, you can individually set the contrast for each system screen; this
option controls the initial value for all visible system screens. The
- standard value is ``1.0``. Selecting lower values (down to 0.1) will
- produce a dimmer display, while selecting higher values (up to 2.0) will
- give a more saturated display.
+ standard and default value is ``1.0``. Selecting lower values (down to 0.1)
+ will produce a dimmer display, while selecting higher values (up to 2.0)
+ will give a more saturated display.
- The default is ``1.0``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -contrast 0.5
.. _mame-commandline-gamma:
@@ -1568,13 +2520,18 @@ Core Screen Options
ramp, for the system screens. This option does not affect the artwork or
other parts of the display. Using the MAME UI, you can individually set
the gamma for each system screen; this option controls the initial value for
- all visible system screens. The standard value is ``1.0``, which gives a
- linear ramp from black to white. Selecting lower values (down to 0.1) will
- increase the nonlinearity toward black, while selecting higher values
- (up to 3.0) will push the nonlinearity toward white.
+ all visible system screens. The standard and default value is ``1.0``,
+ which gives a linear ramp from black to white. Selecting lower values
+ (down to 0.1) will increase the nonlinearity toward black, while
+ selecting higher values (up to 3.0) will push the nonlinearity toward white.
The default is ``1.0``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -gamma 0.8
+
.. _mame-commandline-pausebrightness:
**-pause_brightness** *<value>*
@@ -1583,6 +2540,11 @@ Core Screen Options
The default value is ``0.65``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -pause_brightness 0.33
+
.. _mame-commandline-effect:
**-effect** *<filename>*
@@ -1601,6 +2563,10 @@ Core Screen Options
The default is ``none``, meaning no effect.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -effect scanlines
Core Vector Options
@@ -1612,18 +2578,33 @@ Core Vector Options
Sets the vector beam minimum width.
+ Example:
+ .. code-block:: bash
+
+ mame64 asteroid -beam_width_min 0.1
+
.. _mame-commandline-beamwidthmax:
**-beam_width_max** *<width>*
Sets the vector beam maximum width.
+ Example:
+ .. code-block:: bash
+
+ mame64 asteroid -beam_width_max 2
+
.. _mame-commandline-beamintensityweight:
**-beam_intensity_weight** *<weight>*
Sets the vector beam intensity weight.
+ Example:
+ .. code-block:: bash
+
+ mame64 asteroid -beam_intensity_weight 0.5
+
.. _mame-commandline-flicker:
**-flicker** *<value>*
@@ -1634,6 +2615,11 @@ Core Vector Options
The default is ``0``.
+ Example:
+ .. code-block:: bash
+
+ mame64 asteroid -flicker 0.15
+
Core Video OpenGL Debugging Options
-----------------------------------
@@ -1643,6 +2629,9 @@ 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
possible video performance.
+.. Tip:: Examples are not provided for these options as MAMEdev will provide
+ suitable test options in the case of needing them for debugging.
+
.. _mame-commandline-glforcepow2texture:
**-[no]gl_forcepow2texture**
@@ -1671,7 +2660,7 @@ possible video performance.
**-[no]gl_pbo**
- Enable OpenGL PBO (Pixel Buffer Objects), if available (default ``on``)
+ Enable OpenGL PBO (Pixel Buffer Objects), if available (default ``on`` )
The default is ON. (**-gl_pbo**)
@@ -1687,6 +2676,11 @@ Core Video OpenGL GLSL Options
The default is OFF.
+ Example:
+ .. code-block:: bash
+
+ mame64 galaxian -gl_glsl
+
.. _mame-commandline-glglslfilter:
**-gl_glsl_filter**
@@ -1698,6 +2692,11 @@ Core Video OpenGL GLSL Options
The default is 1. (**-gl_glsl_filter 1**)
+ Example:
+ .. code-block:: bash
+
+ mame64 galaxian -gl_glsl -gl_glsl_filter 0
+
.. _mame-commandline-glslshadermame:
**-glsl_shader_mame0**
@@ -1708,18 +2707,17 @@ Core Video OpenGL GLSL Options
**-glsl_shader_mame9**
+ Set a custom OpenGL GLSL shader effect to the internal systcm screen in the
+ given slot. MAME does not include a vast selection of shaders by default;
+ more can be found online.
- Custom OpenGL GLSL shader set MAME bitmap in the provided slot (0-9); one
- can be applied to each slot.
-
- [todo: better details on usage at some point.
- See http://forums.bannister.org/ubbthreads.php?ubb=showflat&Number=100988#Post100988 ]
-
+ Example:
+ .. code-block:: bash
+ mame64 suprmrio -gl_glsl -glsl_shader_mame0 NTSC/NTSC_chain -glsl_shader_mame1 CRT-geom/CRT-geom
.. _mame-commandline-glslshaderscreen:
-
**-glsl_shader_screen0**
**-glsl_shader_screen1**
@@ -1729,10 +2727,14 @@ Core Video OpenGL GLSL Options
**-glsl_shader_screen9**
- Custom OpenGL GLSL shader screen bitmap in the provided slot (0-9).
+ 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
+ selection of shaders by default; more can be found online.
+
+ Example:
+ .. code-block:: bash
- [todo: better details on usage at some point.
- See http://forums.bannister.org/ubbthreads.php?ubb=showflat&Number=100988#Post100988 ]
+ mame64 suprmrio -gl_glsl -glsl_shader_screen0 gaussx -glsl_shader_screen1 gaussy -glsl_shader_screen2 CRT-geom-halation
.. _mame-commandline-glglslvidattr:
@@ -1744,6 +2746,10 @@ Core Video OpenGL GLSL Options
Default is ``on``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -gl_glsl -gl_glsl_vid_attr off
Core Sound Options
------------------
@@ -1758,6 +2764,11 @@ Core Sound Options
The default is ``48000``.
+ Example:
+ .. code-block:: bash
+
+ mame64 galaga -samplerate 44100
+
.. _mame-commandline-nosamples:
**-[no]samples**
@@ -1766,6 +2777,11 @@ Core Sound Options
The default is ON (**-samples**).
+ Example:
+ .. code-block:: bash
+
+ mame64 qbert -nosamples
+
.. _mame-commandline-volume:
**-volume** / **-vol** *<value>*
@@ -1776,20 +2792,18 @@ Core Sound Options
The default is ``0``.
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -volume -30
+
.. _mame-commandline-sound:
-**-sound** *<``dsound``|``coreaudio``|``sdl``|``xaudio2``|``portaudio``|``none``>*
+**-sound** *<dsound | coreaudio | sdl | xaudio2 | portaudio | none>*
Specifies which sound subsystem to use. Selecting ``none`` disables sound
output altogether (sound hardware is still emulated).
-| On Windows, ``dsound``, ``xaudio2``, ``portaudio`` and ``none`` are available.
-| On macOS, ``coreaudio``, ``sdl``, ``portaudio`` and ``none`` are available.
-| On other operating systems, ``sdl``, ``portaudio`` and ``none`` are available. (Special build options allow ``sdl`` to be used on Windows, or ``portaudio`` to be disabled.)
-|
-| The default is ``dsound`` on Windows. On Mac, ``coreaudio`` is the default. On all other platforms, ``sdl`` is the default.
-|
-
On Windows and Linux, *portaudio* is likely to give the lowest possible
latency, while Mac users will find *coreaudio* provides the best results.
@@ -1798,6 +2812,45 @@ Core Sound Options
depend on the operating system. On Windows, it may be necessary to set
``SDL_AUDIODRIVER=directsound`` if no sound output is produced by default.
+ The default is ``dsound`` on Windows. On Mac, ``coreaudio`` is the default.
+ On all other platforms, ``sdl`` is the default.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -sound portaudio
+
+.. list-table:: Supported sound subsystems per-platform
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - **Microsoft Windows**
+ - dsound
+ - xaudio2
+ - portaudio
+ -
+ - sdl [#SoundWinSDL]_.
+ - none
+ * - **macOS**
+ -
+ -
+ - portaudio
+ - coreaudio
+ - sdl
+ - none
+ * - **Linux** and others
+ -
+ -
+ - portaudio
+ -
+ - sdl
+ - none
+
+
+.. rubric:: Footnotes
+
+.. [#SoundWinSDL] While SDL is not a supported option on official builds for Windows, you can compile MAME with SDL support on Windows.
+
.. _mame-commandline-audiolatency:
**-audio_latency** *<value>*
@@ -1807,7 +2860,18 @@ Core Sound Options
Higher values increase audio delay but may help avoid buffer under-runs and
audio interruptions.
- The default is ``1``.
+ The default is ``1``.
+
+ | For PortAudio, see :ref:`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.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 galaga -audio_latency 1
Core Input Options
@@ -1827,6 +2891,11 @@ Core Input Options
The default is ON (**-coin_lockout**).
+ Example:
+ .. code-block:: bash
+
+ mame64 suprmrio -coin_lockout
+
.. _mame-commandline-ctrlr:
**-ctrlr** *<controller>*
@@ -1837,6 +2906,11 @@ Core Input Options
The default is ``NULL`` (no controller file).
+ Example:
+ .. code-block:: bash
+
+ mame64 dkong -ctrlr xarcade
+
.. _mame-commandline-nomouse:
**-[no]mouse**
@@ -1847,6 +2921,11 @@ Core Input Options
The default is OFF (**-nomouse**).
+ Example:
+ .. code-block:: bash
+
+ mame64 centiped -mouse
+
.. _mame-commandline-nojoystick:
**-[no]joystick** / **-[no]joy**
@@ -1858,6 +2937,11 @@ Core Input Options
The default is OFF (**-nojoystick**).
+ Example:
+ .. code-block:: bash
+
+ mame64 mappy -joystick
+
.. _mame-commandline-nolightgun:
**-[no]lightgun** / **-[no]gun**
@@ -1868,6 +2952,11 @@ Core Input Options
The default is OFF (**-nolightgun**).
+ Example:
+ .. code-block:: bash
+
+ mame64 lethalen -lightgun
+
.. _mame-commandline-nomultikeyboard:
**-[no]multikeyboard** / **-[no]multikey**
@@ -1881,6 +2970,11 @@ Core Input Options
The default is OFF (**-nomultikeyboard**).
+ Example:
+ .. code-block:: bash
+
+ mame64 sf2ceua -multikey
+
.. _mame-commandline-nomultimouse:
**-[no]multimouse**
@@ -1893,6 +2987,11 @@ Core Input Options
The default is OFF (**-nomultimouse**).
+ Example:
+ .. code-block:: bash
+
+ mame64 warlords -multimouse
+
.. _mame-commandline-nosteadykey:
**-[no]steadykey** / **-[no]steady**
@@ -1906,6 +3005,11 @@ Core Input Options
The default is OFF (**-nosteadykey**)
+ Example:
+ .. code-block:: bash
+
+ mame64 sf2ua -steadykey
+
.. _mame-commandline-uiactive:
**-[no]ui_active**
@@ -1914,6 +3018,11 @@ Core Input Options
The default is OFF (**-noui_active**)
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2e -ui_active
+
.. _mame-commandline-nooffscreenreload:
**-[no]offscreen_reload** / **-[no]reload**
@@ -1927,6 +3036,11 @@ Core Input Options
The default is OFF (**-nooffscreen_reload**).
+ Example:
+ .. code-block:: bash
+
+ mame64 lethalen -offscreen_reload
+
.. _mame-commandline-joystickmap:
**-joystick_map** *<map>* / **-joymap** *<map>*
@@ -2004,6 +3118,11 @@ Core Input Options
The default is ``0.3``.
+ Example:
+ .. code-block:: bash
+
+ mame64 sinistar -joystick_deadzone 0.45
+
.. _mame-commandline-joysticksaturation:
**-joystick_saturation** *<value>* / **joy_saturation** *<value>* / **-jsat** *<value>*
@@ -2016,6 +3135,11 @@ Core Input Options
The default is ``0.85``.
+ Example:
+ .. code-block:: bash
+
+ mame64 sinistar -joystick_saturation 1.0
+
.. _mame-commandline-natural:
**\-natural**
@@ -2045,6 +3169,11 @@ Core Input Options
* 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)
+ Example:
+ .. code-block:: bash
+
+ mame64 coco2 -natural
+
.. _mame-commandline-joystickcontradictory:
**-joystick_contradictory**
@@ -2054,6 +3183,11 @@ Core Input Options
The default is OFF (**-nojoystick_contradictory**)
+ Example:
+ .. code-block:: bash
+
+ mame64 pc_smb -joystick_contradictory
+
.. _mame-commandline-coinimpulse:
**-coin_impulse** *[n]*
@@ -2063,6 +3197,10 @@ Core Input Options
Default is ``0``.
+ Example:
+ .. code-block:: bash
+
+ mame64 contra -coin_impulse 1
Core Input Automatic Enable Options
@@ -2070,35 +3208,35 @@ Core Input Automatic Enable Options
.. _mame-commandline-paddledevice:
-**-paddle_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-paddle_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
.. _mame-commandline-adstickdevice:
-**-adstick_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-adstick_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
.. _mame-commandline-pedaldevice:
-**-pedal_device** (``none``|``keyboard``|``mouse``|```lightgun``|``joystick``)
+**-pedal_device** ( ``none`` | ``keyboard`` | ``mouse`` | ```lightgun`` | ``joystick`` )
.. _mame-commandline-dialdevice:
-**-dial_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-dial_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
.. _mame-commandline-trackballdevice:
-**-trackball_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-trackball_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
.. _mame-commandline-lightgundevice:
-**-lightgun_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-lightgun_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
.. _mame-commandline-positionaldevice:
-**-positional_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-positional_device** ( ``none`` | ``keyboard`` | ``mouse`` | ``lightgun`` | ``joystick`` )
.. _mame-commandline-mousedevice:
-**-mouse_device** (``none``|``keyboard``|``mouse``|``lightgun``|``joystick``)
+**-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
@@ -2107,8 +3245,13 @@ Core Input Automatic Enable Options
automatically enable mouse controls just as if you had explicitly specified
**-mouse**.
- Note that these controls override the values of **-[no]mouse**,
- **-[no]joystick**, etc.
+ Example:
+ .. code-block:: bash
+
+ mame64 sbrkout -paddle_device mouse
+
+.. Tip:: Note that these controls override the values of **-[no]mouse**,
+ **-[no]joystick**, etc.
Debugging Options
@@ -2119,12 +3262,18 @@ Debugging Options
**-[no]verbose** / **-[no]v**
Displays internal diagnostic information. This information is very useful
- for debugging problems with your configuration. IMPORTANT: when reporting
- bugs, please run with **mame -verbose** and include the resulting
- information.
+ for debugging problems with your configuration.
The default is OFF (**-noverbose**).
+ Example:
+ .. code-block:: bash
+
+ mame64 polepos -verbose
+
+.. Tip:: IMPORTANT: When reporting bugs to MAMEdev, please run with **-verbose**
+ and include the resulting information.
+
.. _mame-commandline-oslog:
**-[no]oslog**
@@ -2139,16 +3288,31 @@ Debugging Options
The default is OFF (**-nooslog**).
+ Example:
+ .. code-block:: bash
+
+ mame64 mappy -oslog
+
.. _mame-commandline-log:
**-[no]log**
Creates a file called error.log which contains all of the internal log
messages generated by the MAME core and system drivers. This can be used at
- the same time as **-log** to output the log data to both targets as well.
+ the same time as **-oslog** to output the log data to both targets as well.
The default is OFF (**-nolog**).
+ Example 1:
+ .. code-block:: bash
+
+ mame64 qbert -log
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 qbert -oslog -log
+
.. _mame-commandline-debug:
**-[no]debug**
@@ -2159,6 +3323,11 @@ Debugging Options
The default is OFF (**-nodebug**).
+ Example:
+ .. code-block:: bash
+
+ mame64 indy_4610 -debug
+
.. _mame-commandline-debugscript:
**-debugscript** *<filename>*
@@ -2168,6 +3337,11 @@ Debugging Options
The default is ``NULL`` (*no commands*).
+ Example:
+ .. code-block:: bash
+
+ mame64 galaga -debugscript testscript.txt
+
.. _mame-commandline-updateinpause:
**-[no]update_in_pause**
@@ -2178,6 +3352,11 @@ Debugging Options
The default is OFF (**-noupdate_in_pause**).
+ Example:
+ .. code-block:: bash
+
+ mame64 indy_4610 -update_in_pause
+
.. _mame-commandline-watchdog:
**-watchdog** *<duration>* / **-wdog** *<duration>*
@@ -2191,6 +3370,11 @@ Debugging Options
By default there is no watchdog.
+ Example:
+ .. code-block:: bash
+
+ mame64 ibm_5150 -watchdog 30
+
.. _mame-commandline-debuggerfont:
**-debugger_font** *<fontname>* / **-dfont** *<fontname>*
@@ -2201,6 +3385,11 @@ Debugging Options
| The Mac (Cocoa) default font is system fixed-pitch font default (typically ``Monaco``).
| The Qt default font is ``Courier New``.
+ Example:
+ .. code-block:: bash
+
+ mame64 marble -debug -debugger_font "Comic Sans MS"
+
.. _mame-commandline-debuggerfontsize:
**-debugger_font_size** *<points>* / **-dfontsize** *<points>*
@@ -2211,6 +3400,11 @@ Debugging Options
| The Qt default size is ``11`` points.
| The Mac (Cocoa) default size is the system default size.
+ Example:
+ .. code-block:: bash
+
+ mame64 marble -debug -debugger_font "Comic Sans MS" -debugger_font_size 16
+
Core Communication Options
--------------------------
@@ -2222,9 +3416,14 @@ Core Communication Options
Local address to bind to. This can be a traditional ``xxx.xxx.xxx.xxx``
address or a string containing a resolvable hostname.
- The default is value is "``0.0.0.0``" (which binds to all local IPv4
+ The default is value is ``0.0.0.0`` (which binds to all local IPv4
addresses).
+ Example:
+ .. code-block:: bash
+
+ mame64 arescue -comm_localhost 192.168.1.2
+
.. _mame-commandline-commlocalport:
**-comm_localport** *<string>*
@@ -2232,7 +3431,12 @@ Core Communication Options
Local port to bind to. This can be any traditional communications port as
an unsigned 16-bit integer (0-65535).
- The default value is "``15122``".
+ The default value is ``15122``.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 arescue -comm_localhost 192.168.1.2 -comm_localport 30100
.. _mame-commandline-commremotehost:
@@ -2244,6 +3448,11 @@ Core Communication Options
The default is value is "``0.0.0.0``" (which binds to all local IPv4
addresses).
+ Example:
+ .. code-block:: bash
+
+ mame64 arescue -comm_remotehost 192.168.1.2
+
.. _mame-commandline-commremoteport:
**-comm_remoteport** *<string>*
@@ -2253,6 +3462,11 @@ Core Communication Options
The default value is "``15122``".
+ Example:
+ .. code-block:: bash
+
+ mame64 arescue -comm_remotehost 192.168.1.2 -comm_remoteport 30100
+
.. _mame-commandline-commframesync:
**-[no]comm_framesync**
@@ -2261,6 +3475,11 @@ Core Communication Options
The default is OFF (**-nocomm_framesync**).
+ Example:
+ .. code-block:: bash
+
+ mame64 arescue -comm_remotehost 192.168.1.3 -comm_remoteport 30100 -comm_framesync
+
Core Misc Options
-----------------
@@ -2273,6 +3492,11 @@ Core Misc Options
The default is ON (**-drc**).
+ Example:
+ .. code-block:: bash
+
+ mame64 ironfort -nodrc
+
.. _mame-commandline-drcusec:
**\-drc_use_c**
@@ -2281,6 +3505,11 @@ Core Misc Options
The default is OFF (**-nodrc_use_c**).
+ Example:
+ .. code-block:: bash
+
+ mame64 ironfort -drc_use_c
+
.. _mame-commandline-drcloguml:
**\-drc_log_uml**
@@ -2289,6 +3518,11 @@ Core Misc Options
The default is OFF (**-nodrc_log_uml**).
+ Example:
+ .. code-block:: bash
+
+ mame64 ironfort -drc_log_uml
+
.. _mame-commandline-drclognative:
**\-drc_log_native**
@@ -2297,6 +3531,11 @@ Core Misc Options
The default is OFF (**-nodrc_log_native**).
+ Example:
+ .. code-block:: bash
+
+ mame64 ironfort -drc_log_native
+
.. _mame-commandline-bios:
**-bios** *<biosname>*
@@ -2307,6 +3546,11 @@ Core Misc Options
The default is ``default``.
+ Example:
+ .. code-block:: bash
+
+ mame64 mslug -bios unibios33
+
.. _mame-commandline-cheat:
**-[no]cheat** / **-[no]c**
@@ -2320,6 +3564,11 @@ Core Misc Options
The default is OFF (**-nocheat**).
+ Example:
+ .. code-block:: bash
+
+ mame64 dkong -cheat
+
.. _mame-commandline-skipgameinfo:
**-[no]skip_gameinfo**
@@ -2328,6 +3577,11 @@ Core Misc Options
The default is OFF (**-noskip_gameinfo**).
+ Example:
+ .. code-block:: bash
+
+ mame64 samsho5 -skip_gameinfo
+
.. _mame-commandline-uifont:
**-uifont** *<fontname>*
@@ -2339,6 +3593,11 @@ Core Misc Options
The default is ``default`` (use the OSD-determined default font).
+ Example:
+ .. code-block:: bash
+
+ mame64 -uifont "Comic Sans MS"
+
.. _mame-commandline-ui:
**-ui** *<type>*
@@ -2347,12 +3606,22 @@ Core Misc Options
The default is Cabinet (**-ui cabinet**).
+ Example:
+ .. code-block:: bash
+
+ mame64 -ui simple
+
.. _mame-commandline-ramsize:
**-ramsize** *[n]*
Allows you to change the default RAM size (if supported by driver).
+ Example:
+ .. code-block:: bash
+
+ mame64 coco -ramsize 16K
+
.. _mame-commandline-confirmquit:
**\-confirm_quit**
@@ -2362,6 +3631,11 @@ Core Misc Options
The default is OFF (**-noconfirm_quit**).
+ Example:
+ .. code-block:: bash
+
+ mame64 pacman -confirm_quit
+
.. _mame-commandline-uimouse:
**\-ui_mouse**
@@ -2371,11 +3645,20 @@ Core Misc Options
The default is (**-noui_mouse**).
.. _mame-commandline-language:
+ Example:
+ .. code-block:: bash
+
+ mame64 -ui_mouse
**-language** *<language>*
Specify a localization language found in the ``languagepath`` tree.
+ Example:
+ .. code-block:: bash
+
+ mame64 -language Japanese
+
.. _mame-commandline-nvramsave:
**-[no]nvram_save**
@@ -2387,6 +3670,10 @@ Core Misc Options
The default is ON (**-nvram_save**).
+ Example:
+ .. code-block:: bash
+
+ mame64 galaga88 -nonvram_save
Scripting Options
@@ -2402,7 +3689,10 @@ Scripting Options
This works only with systems that support natural keyboard mode.
- Example: **-autoboot_command "load """$""",8,1\\n"**
+ Example:
+ .. code-block:: bash
+
+ mame64 c64 -autoboot_delay 5 -autoboot_command "load """$""",8,1\n"
.. _mame-commandline-autobootdelay:
@@ -2410,12 +3700,22 @@ Scripting Options
Timer delay (in seconds) to trigger command execution on autoboot.
+ Example:
+ .. code-block:: bash
+
+ mame64 c64 -autoboot_delay 5 -autoboot_command "load """$""",8,1\n"
+
.. _mame-commandline-autobootscript:
**-autoboot_script** / **-script** *[filename.lua]*
File containing scripting to execute after machine boot.
+ Example:
+ .. code-block:: bash
+
+ mame64 ibm5150 -autoboot_script myscript.lua
+
.. _mame-commandline-console:
**-[no]console**
@@ -2424,6 +3724,11 @@ Scripting Options
The default of OFF (**-noconsole**).
+ Example:
+ .. code-block:: bash
+
+ mame64 ibm5150 -console
+
.. _mame-commandline-plugins:
**-plugins**
@@ -2432,18 +3737,32 @@ Scripting Options
The default is ON (**-plugins**).
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2e -plugins
+
.. _mame-commandline-plugin:
**-plugin** *[plugin shortname]*
A list of Lua Plugins to enable, comma separated.
+ Example:
+ .. code-block:: bash
+
+ mame64 alcon -plugin cheat,discord,autofire
+
.. _mame-commandline-noplugin:
**-noplugin** *[plugin shortname]*
A list of Lua Plugins to disable, comma separated.
+ Example:
+ .. code-block:: bash
+
+ mame64 alcon -noplugin cheat
HTTP Server Options
@@ -2456,6 +3775,11 @@ HTTP Server Options
The default is OFF (**-nohttp**).
+ Example:
+ .. code-block:: bash
+
+ mame64 -http
+
.. _mame-commandline-httpport:
**-http_port** *[port]*
@@ -2464,6 +3788,11 @@ HTTP Server Options
The default is ``8080``.
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2 -http -http_port 6502
+
.. _mame-commandline-httproot:
**-http_root** *[rootfolder]*
@@ -2471,3 +3800,99 @@ HTTP Server Options
Choose HTTP server document root.
The default is ``web``.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 apple2 -http -http_port 6502 -http_root c:\users\me\appleweb\root
+
+
+PortAudio Options
+-----------------
+
+.. _mame-commandline-pa-api:
+
+**-pa_api** *API*
+
+ Choose which API that PortAudio should use to talk to your sound hardware. You can use **-verbose** to see which APIs are available.
+
+ The default is ``none``.
+
+ Example 1:
+ .. code-block:: bash
+
+ mame64 -sound portaudio -verbose
+ Attempting load of mame.ini
+ ...
+ PortAudio: API MME has 20 devices
+ PortAudio: MME: " - Input"
+ PortAudio: MME: "Microphone (3- USB Camera-B4.09"
+ PortAudio: MME: "Line (AVerMedia Live Gamer HD 2"
+ PortAudio: MME: "Digital Audio Interface (AVerMe"
+ PortAudio: MME: "Headset Microphone (Razer Krake"
+ ...
+ PortAudio: MME: " - Output"
+ PortAudio: MME: "Headset Earphone (Razer Kraken "
+ PortAudio: MME: "Digital Audio (S/PDIF) (High De"
+ PortAudio: MME: "NX-EDG27 (NVIDIA High Definitio"
+ ...
+ PortAudio: API Windows DirectSound has 20 devices
+ PortAudio: Windows DirectSound: "Primary Sound Capture Driver"
+ PortAudio: Windows DirectSound: "Headset Microphone (Razer Kraken 7.1 V2)"
+ PortAudio: Windows DirectSound: "Primary Sound Driver" (default)
+ PortAudio: Windows DirectSound: "Headset Earphone (Razer Kraken 7.1 V2)"
+ PortAudio: Windows DirectSound: "Digital Audio (S/PDIF) (High Definition Audio Device)"
+ PortAudio: Windows DirectSound: "NX-EDG27 (NVIDIA High Definition Audio)"
+ ...
+ PortAudio: API Windows WASAPI has 18 devices
+ PortAudio: Windows WASAPI: "Headset Earphone (Razer Kraken 7.1 V2)"
+ PortAudio: Windows WASAPI: "Digital Audio (S/PDIF) (High Definition Audio Device)"
+ PortAudio: Windows WASAPI: "NX-EDG27 (NVIDIA High Definition Audio)"
+ PortAudio: Windows WASAPI: "Headset Microphone (Razer Kraken 7.1 V2)"
+ ...
+ PortAudio: API Windows WDM-KS has 22 devices
+ PortAudio: Windows WDM-KS: "Output (NVIDIA High Definition Audio)"
+ PortAudio: Windows WDM-KS: "SPDIF Out (HD Audio SPDIF out)"
+ PortAudio: Windows WDM-KS: "Headset Microphone (Razer Kraken 7.1 V2)"
+ PortAudio: Windows WDM-KS: "Headset Earphone (Razer Kraken 7.1 V2)"
+ PortAudio: Windows WDM-KS: "Microphone (VDVAD Wave)"
+ PortAudio: Windows WDM-KS: "Speakers (VDVAD Wave)"
+ ...
+ PortAudio: Sample rate is 48000 Hz, device output latency is 218.67 ms
+ PortAudio: Allowed additional buffering latency is 18.00 ms/864 frames
+
+ Example 2:
+ .. code-block:: bash
+
+ mame64 suprmrio -sound portaudio -pa_api "Windows WASAPI"
+
+.. _mame-commandline-pa-device:
+
+**-pa_device** *device*
+
+ Choose which sound device to output through. This would typically be one of
+ the outputs on your sound card or a USB headset.
+
+ The default is ``none``.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 suprmrio -sound portaudio -pa_api "Windows WASAPI" -pa_device "NX-EDG27 (NVIDIA High Definition Audio)"
+
+.. _mame-commandline-pa-latency:
+
+**-pa_latency** *latency*
+
+ Choose the buffer size for PortAudio output; this is specified in seconds.
+ Lower numbers have less latency but may increase stutter in the sound.
+ Decimal places are supported. Try starting from 0.20 and decrease or
+ increase until you find the best number your hardware and OS are capable of
+ handling.
+
+ The default is ``0``.
+
+ Example:
+ .. code-block:: bash
+
+ mame64 suprmrio -sound portaudio -pa_api "Windows WASAPI" -pa_device "NX-EDG27 (NVIDIA High Definition Audio)" -pa_latency 0.20
diff --git a/docs/source/usingmame/commonissues.rst b/docs/source/usingmame/commonissues.rst
index 86a89442b43..7fba001d86b 100644
--- a/docs/source/usingmame/commonissues.rst
+++ b/docs/source/usingmame/commonissues.rst
@@ -26,6 +26,7 @@ Common Issues and Questions (FAQ)
20. :ref:`ControllerIssues`
21. :ref:`ExternalOPL`
22. :ref:`Autofire`
+23. :ref:`gsync-freesync`
.. _rapid-coins:
@@ -276,3 +277,19 @@ Note that if you set the autofire button to an input button that's also defined
If you set button 3 on your controller to autofire and set button 3 to be powerup as well, you will trigger the powerup action every time you grab a powerup because the powerup button is also being held down along with the autofire button.
It is suggested you choose a button for autofire that is not in use for anything else in the current system.
+
+
+.. _gsync-freesync:
+
+Does MAME support G-Sync or FreeSync? How do I configure MAME to use them?
+--------------------------------------------------------------------------
+
+MAME supports both G-Sync and FreeSync right out of the box for Windows and Linux, however macOS does not support G-Sync or FreeSync.
+
+* Make sure your monitor is capable of at least 120Hz G-Sync/FreeSync. If your monitor is only capable of 60Hz in G-Sync/FreeSync modes, you will hit problems with drivers such as *Pac-Man* that run at 60.60606Hz and may hit problems with others that are very close to but not quite 60Hz.
+* If playing MAME windowed or using the BGFX video system, you'll need to make sure that you have G-Sync/FreeSync turned on for windowed applications as well as full screen in your video driver.
+* Be sure to leave triple buffering turned off.
+* Turning VSync on is suggested in general with G-Sync and FreeSync.
+* Low Latency Mode will not affect MAME performance with G-Sync/FreeSync.
+
+The effects of G-Sync and FreeSync will be most noticeable in drivers that run at refresh rates that are very different from normal PC refresh rates. For instance, the first three *Mortal Kombat* titles run at 54.706841Hz. \ No newline at end of file