summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/CONTRIBUTING.md1
-rw-r--r--docs/man/chdman.12
-rw-r--r--docs/man/mess.61332
-rw-r--r--docs/man/romcmp.13
-rw-r--r--docs/source/advanced/bgfx.rst265
-rw-r--r--docs/source/advanced/ctrlr_config.rst84
-rw-r--r--docs/source/advanced/devicemap.rst121
-rw-r--r--docs/source/advanced/hlsl.rst2
-rw-r--r--docs/source/advanced/multiconfig.rst52
-rw-r--r--docs/source/commandline/commandline-all.rst564
-rw-r--r--docs/source/commandline/commandline-index.rst98
-rw-r--r--docs/source/commandline/index.rst14
-rw-r--r--docs/source/commandline/sdlconfig.rst60
-rw-r--r--docs/source/commandline/windowsconfig.rst59
-rw-r--r--docs/source/conf.py6
-rw-r--r--docs/source/contributing/cxx.rst573
-rw-r--r--docs/source/contributing/index.rst144
-rw-r--r--docs/source/contributing/softlist.rst175
-rw-r--r--docs/source/debugger/exceptionpoint.rst134
-rw-r--r--docs/source/debugger/execution.rst96
-rw-r--r--docs/source/debugger/general.rst42
-rw-r--r--docs/source/debugger/index.rst45
-rw-r--r--docs/source/debugger/registerpoints.rst2
-rw-r--r--docs/source/debugger/watchpoint.rst2
-rw-r--r--docs/source/images/MAMElogo.svg8
-rw-r--r--docs/source/index.rst4
-rw-r--r--docs/source/initialsetup/compilingmame.rst387
-rw-r--r--docs/source/initialsetup/configuringmame.rst5
-rw-r--r--docs/source/license.rst2
-rw-r--r--docs/source/luascript/index.rst235
-rw-r--r--docs/source/luascript/ref-common.rst118
-rw-r--r--docs/source/luascript/ref-core.rst635
-rw-r--r--docs/source/luascript/ref-debugger.rst451
-rw-r--r--docs/source/luascript/ref-devices.rst770
-rw-r--r--docs/source/luascript/ref-input.rst776
-rw-r--r--docs/source/luascript/ref-mem.rst459
-rw-r--r--docs/source/luascript/ref-render.rst1301
-rw-r--r--docs/source/plugins/autofire.rst30
-rw-r--r--docs/source/plugins/console.rst2
-rw-r--r--docs/source/plugins/data.rst10
-rw-r--r--docs/source/plugins/discord.rst2
-rw-r--r--docs/source/plugins/dummy.rst5
-rw-r--r--docs/source/plugins/index.rst4
-rw-r--r--docs/source/plugins/inputmacro.rst22
-rw-r--r--docs/source/security.rst2
-rw-r--r--docs/source/techspecs/device_disasm_interface.rst10
-rw-r--r--docs/source/techspecs/device_memory_interface.rst15
-rw-r--r--docs/source/techspecs/floppy.rst8
-rw-r--r--docs/source/techspecs/index.rst29
-rw-r--r--docs/source/techspecs/inputsystem.rst460
-rw-r--r--docs/source/techspecs/layout_files.rst72
-rw-r--r--docs/source/techspecs/layout_script.rst90
-rw-r--r--docs/source/techspecs/luaengine.rst203
-rw-r--r--docs/source/techspecs/luareference.rst3184
-rw-r--r--docs/source/techspecs/m6502.rst10
-rw-r--r--docs/source/techspecs/memory.rst28
-rw-r--r--docs/source/techspecs/naming.rst61
-rw-r--r--docs/source/techspecs/object_finders.rst4
-rw-r--r--docs/source/techspecs/poly_manager.rst2
-rw-r--r--docs/source/tools/castool.rst4
-rw-r--r--docs/source/tools/chdman.rst456
-rw-r--r--docs/source/tools/floptool.rst4
-rw-r--r--docs/source/tools/imgtool.rst10
-rw-r--r--docs/source/tools/index.rst16
-rw-r--r--docs/source/tools/othertools.rst8
-rw-r--r--docs/source/usingmame/aboutromsets.rst24
-rw-r--r--docs/source/usingmame/assetsearch.rst398
-rw-r--r--docs/source/usingmame/commonissues.rst2
-rw-r--r--docs/source/usingmame/defaultkeys.rst78
-rw-r--r--docs/source/usingmame/index.rst1
-rw-r--r--docs/source/usingmame/mamemenus.rst286
-rw-r--r--docs/source/usingmame/ui.rst132
-rw-r--r--docs/source/usingmame/usingmame.rst17
-rw-r--r--docs/source/whatis.rst4
-rw-r--r--docs/swlist/n64jp.csv236
-rw-r--r--docs/swlist/readme.txt10
-rw-r--r--docs/swlist/x1_flop.csv375
-rw-r--r--docs/swlist/x68k_flop.csv1784
78 files changed, 9040 insertions, 8085 deletions
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
deleted file mode 100644
index 8b137891791..00000000000
--- a/docs/CONTRIBUTING.md
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/man/chdman.1 b/docs/man/chdman.1
index 34fd884eecd..57a1e4615c7 100644
--- a/docs/man/chdman.1
+++ b/docs/man/chdman.1
@@ -39,7 +39,7 @@ detailed list of the valid switches for the option.
Dump the header information from a drive image.
.TP
.B verify \
-\-i \fIfileiname\fR \
+\-i \fIfilename\fR \
[\fB\-ip \fIfilename\fR]
Validate the MD5/SHA1 on a drive image.
.TP
diff --git a/docs/man/mess.6 b/docs/man/mess.6
deleted file mode 100644
index 07293db867f..00000000000
--- a/docs/man/mess.6
+++ /dev/null
@@ -1,1332 +0,0 @@
-.\" -*- nroff -*-
-.\"
-.\" mess.6
-.\"
-.\" Man page created from usage and source information:
-.\" * commands: see src/emu/clifront.c clifront.h
-.\" * options: core entries, see src/emu/emuopts.c emuopts.h
-.\" SDL-specific entries, see src/osd/sdl/sdlmain.c osdsdl.h
-.\" Cesare Falco <c.falco@ubuntu.com>, March 2011
-.\"
-.\" Some text borrowed from the xmame 0.106 man page,
-.\" done by Rene Herrmann <rene.herrmann@berlin.de>, September 2000
-.\" and updated by Andrew Burton <burtona@gol.com>, July 2003
-.\"
-.\" Other info's taken from MESS Wiki as well:
-.\" http://mess.redump.net
-.\"
-.\"
-.TH MESS 6 2015-05-20 0.162 "MESS \- Multi Emulator Super System"
-.\"
-.\"
-.\" NAME chapter
-.SH NAME
-MESS \- Multi Emulator Super System
-.\"
-.\"
-.\" SYNOPSIS chapter
-.SH SYNOPSIS
-.B mess
-.I system
-.RI [ "media software" ]
-.RI [ options ]
-.\"
-.\"
-.\" DESCRIPTION chapter
-.SH DESCRIPTION
-MESS documents the hardware for a wide variety of (mostly vintage) computers,
-video game consoles, and calculators through software emulation. As a nice
-side effect, MESS allows software and games for these hardware platforms
-to run on modern PCs.
-.\"
-.\"
-.\" SOFTWARE chapter
-.SH SOFTWARE
-A \fIsoftware\fR entry may be specified to attach an image file to the
-emulated system. In such a case, the appropriate \fImedia\fR switch
-is also required:
-.TP
-.B \-cart, \-cart1
-Cartrigde, used mainly by game consoles
-.TP
-.B \-cass
-Cassette (tape), widely used by old home computers
-.TP
-.B \-flop, -flop1
-Floppy disk
-.TP
-.B \-cdrom
-CD-Rom
-.\"
-.\"
-.\" OPTIONS chapter
-.SH OPTIONS
-.\"
-.\" *******************************************************
-.SS Core commands
-.\" *******************************************************
-.TP
-.B \-help, \-?
-Displays current MESS version and copyright notice.
-.TP
-.B \-validate, \-valid
-Performs internal validation on every driver in MESS. Run this
-before submitting changes to ensure that you haven't violated any of
-the core system rules.
-.\"
-.\" *******************************************************
-.SS Configuration commands
-.\" *******************************************************
-.TP
-.B \-createconfig, \-cc
-Creates the default \fBmess.ini\fR file in the current directory. All the
-configuration options (not commands) described below can be permanently
-changed by editing this configuration file.
-.TP
-.B \-showconfig, \-sc
-Displays the current configuration settings.
-.TP
-.B \-showusage, \-su
-Displays a summary of all the command line options. For options that
-are not mentioned here, the short summary given by \fB\-showusage\fR
-is usually sufficient.
-.\"
-.\" *******************************************************
-.SS Frontend commands
-.\" *******************************************************
-All the list commands below write info to the screen.
-If you wish to write the info to a textfile instead, use redirection.
-For example,
-.B mess \-listxml > ~/messlist.xml
-writes the full list of supported systems to \fBmesslist.xml\fR in your
-home directory.
-.TP
-.B \-listxml, \-lx \fR[\fIsystem\fR|\fIwildcard\fR]
-List comprehensive details for all of the supported systems. The output
-is quite long, so it is usually better to redirect this into a file.
-The output is in XML format. By default all systems are listed; however,
-you can limit this list by specifying a driver name or wildcard after
-the \-listxml command.
-.TP
-.B \-listfull, \-ll \fR[\fIsystem\fR|\fIwildcard\fR]
-Displays a list of system driver names and descriptions. By default all
-systems are listed; however, you can limit this list by specifying a
-driver name or wildcard after the \-listfull command.
-.TP
-.B \-listsource, \-ls \fR[\fIsystem\fR|\fIwildcard\fR]
-Displays a list of drivers and the names of the source files their system
-drivers live in. Useful for finding which driver a system runs on in
-order to fix bugs. By default all systems are listed; however, you can
-limit this list by specifying a driver name or wildcard after the
-\-listsource command.
-.TP
-.B \-listclones, \-lc \fR[\fIsystem\fR|\fIwildcard\fR]
-Displays a list of clones. By default all clones are listed; however,
-you can limit this list by specifying a driver name or wildcard after
-the \-listclones command.
-.TP
-.B \-listbrothers, \-lb \fR[\fIsystem\fR|\fIwildcard\fR]
-Displays a list of "brothers" or other drivers from same sourcefile.
-By default all systems are listed; however, you can limit this list by
-specifying a driver name or wildcard after the \-listbrothers command.
-.TP
-.B \-listcrc
-Displays a full list of CRCs of all ROM images referenced by all
-drivers within MESS code.
-.TP
-.B \-listroms, \-lr \fIsystem
-Displays a list of ROM images referenced by the specified system.
-.TP
-.B \-listsamples \fIsystem
-Displays a list of samples referenced by the specified system.
-.TP
-.B \-verifyroms \fR[\fIsystem\fR|\fIwildcard\fR]
-Checks for invalid or missing ROM images. By default all drivers that
-have valid ZIP files or directories in the rom path are verified;
-however, you can limit this list by specifying a driver name or
-wildcard after the \-verifyroms command.
-.TP
-.B \-verifysamples \fR[\fIsystem\fR|\fIwildcard\fR]
-Checks for invalid or missing samples. By default all drivers that
-have valid ZIP files or directories in the samplepath are verified;
-however, you can limit this list by specifying a driver name or
-wildcard after the \-verifyroms command.
-.TP
-.B \-romident
-Attempts to identify ROM files, if they are known to MESS, 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:
-.br
-\fB0\fR all files were identified
-.br
-\fB7\fR all files were identified except for some "non\-ROM" files
-.br
-\fB8\fR some files were identified
-.br
-\fB9\fR no files were identified
-.TP
-.B \-listdevices, \-ld
-Output the list of devices referenced by a given system or set of systems.
-.TP
-.B \-listslots, \-lslot
-Output the list of available slots and slot devices for the system.
-.TP
-.B \-listmedia, \-lm
-Output the list of available media for the system.
-.TP
-.B \-listsoftware, \-lsoft
-Output the list of known software for the system.
-.TP
-.B \-verifysoftware, \-vsoft \fR[\fIgamename\fR|\fIwildcard\fR]
-Checks for invalid or missing ROM images in your software lists.
-By default all drivers that have valid ZIP files or directories
-in the rompath are verified; however, you can limit this list by
-specifying a specific driver name or wildcard.
-.TP
-.B \-getsoftlist, \-glist
-Retrieve software list by name.
-.TP
-.B \-verifysoftlist, \-vlist \fR[\fIsoftwarelistname\fR]
-Checks a specified software list for missing ROM images if files exist
-for issued softwarelistname. By default, all drivers that have valid
-ZIP files or directories in the rompath are verified; however, you can
-limit this list by specifying a specific softwarelistname (without .XML).
-.TP
-.B \-listmidi, \-mlist
-List available MIDI I/O devices.
-.TP
-.B \-listnetwork, \-nlist
-List available network adapters.
-.\"
-.\" *******************************************************
-.SS Configuration options
-.\" *******************************************************
-.TP
-.B \-[no]readconfig, \-[no]rc
-Enables or disables the reading of the config files. When enabled
-(which is the default), MESS reads the following config files in order:
-.br
-1. \fBmess.ini\fR
-.br
-the main configuration file
-.br
-2. \fI[driver]\fB.ini\fR
-.br
-based on the source file name of the system driver
-.br
-3. \fBdebug.ini\fR, if the debugger is enabled
-.br
-4. \fBvector.ini\fR, for vector games only
-.br
-5. \fI[driver]\fB.ini\fR
-.br
-based on the source filename of the game driver
-.br
-6. \fI[parent]\fB.ini\fR
-.br
-for clones only, may be called recursively
-.br
-4. \fI[system]\fB.ini\fR
-.br
-note this sometimes resolves to the same of the source driver
-.P
-The settings in the later ini's override those in the earlier ini's.
-The default is ON (\-readconfig).
-.TP
-.B \-[no]writeconfig, \-[no]wc
-Write configuration to \fI[driver]\fR.ini on exit.
-Default is OFF (\-nowriteconfig).
-.\"
-.\" *******************************************************
-.SS Search path options
-.\" *******************************************************
-Be careful to use the path, directory and file options in
-mess.ini ONLY. Otherwise, the outcome may be unpredictable and not
-consistent across releases.
-.TP
-.B \-rompath, \-rp, \-biospath, \-bp \fIpathname
-Specifies a list of paths within which to find ROM or hard disk images.
-Multiple paths can be specified by separating them with semicolons.
-The default is 'roms' (that is, a directory 'roms' in the same directory
-as the MESS executable).
-.TP
-.B \-hashpath \fIpathname
-Specifies a list of paths within which to search for software hash files.
-Multiple paths can be specified by separating them with semicolons.
-The default is 'hash' (that is, a directory 'hash' in the same directory
-as the MESS executable).
-.TP
-.B \-samplepath, \-sp \fIpathname
-Specifies a list of paths within which to find sample files. Multiple
-paths can be specified by separating them with semicolons. The default
-is 'samples' (that is, a directory 'samples' in the same directory as
-the MESS executable).
-.TP
-.B \-artpath, \-artwork_directory \fIpathname
-Specifies a list of paths within which to find artwork files. Multiple
-paths can be specified by separating them with semicolons. The default
-is 'artwork' (that is, a directory 'artwork' in the same directory as
-the MESS executable).
-.TP
-.B \-ctrlrpath, \-ctrlr_directory \fIpathname
-Specifies a list of paths within which to find controller\-specific
-configuration files. Multiple paths can be specified by separating
-them with semicolons. The default is 'ctrlr' (that is, a
-directory 'ctrlr' in the same directory as the MESS executable).
-.TP
-.B \-inipath \fIpathname
-Specifies a list of paths within which to find .ini files. Multiple
-paths can be specified by separating them with semicolons. The default
-is '/etc/mess'.
-.TP
-.B \-fontpath \fIpathname
-Specifies a list of paths within which to find .bdf font files. Multiple
-paths can be specified by separating them with semicolons. The default
-is '.' (that is, search in the same directory as the MESS executable).
-.TP
-.B \-cheatpath \fIpathname
-Specifies a list of paths within which to find cheat files. Multiple
-paths can be specified by separating them with semicolons. The default
-is 'cheat' (that is, a directory 'cheat' in the same directory as
-the MESS executable).
-.TP
-.B \-crosshairpath \fIpathname
-Specifies a list of paths within which to find crosshair files. Multiple
-paths can be specified by separating them with semicolons. The default
-is 'crosshair' (that is, a directory 'crosshair' in the same directory as
-the MESS executable). If the Crosshair is set to default in the menu,
-MESS will look for system/cross#.png and then cross#.png in the
-specified path, where # is the player number. Failing that,
-MESS will use built\-in default crosshairs.
-.TP
-.B \-pluginspath \fIpathname
-Specifies a single path within which to find plugins. The default
-is 'plugins' (that is, a directory 'plugins' in the same directory as
-the MESS executable).
-.TP
-.B \-languagepath \fIpathname
-Specifies a single path within which to find language files. The default
-is 'language' (that is, a directory 'language' in the same directory as
-the MESS executable).
-.\"
-.\" *******************************************************
-.SS Output Directory Options
-.\" *******************************************************
-.TP
-.B \-cfg_directory \fIpathname
-Specifies a single directory where configuration files are stored.
-Configuration files store user configurable settings that are read at
-startup and written when MESS exits. The default is 'cfg' (that is,
-a directory 'cfg' in the same directory as the MESS executable). If this
-directory does not exist, it will be automatically created.
-.TP
-.B \-nvram_directory \fIpathname
-Specifies a single directory where NVRAM files are stored. NVRAM files
-store the contents of EEPROM and non\-volatile RAM (NVRAM) for systems
-which used this type of hardware. This data is read at startup and
-written when MESS exits. The default is 'nvram' (that is, a
-directory 'nvram' in the same directory as the MESS executable). If this
-directory does not exist, it will be automatically created.
-.TP
-.B \-input_directory \fIpathname
-Specifies a single directory where input recording files are stored.
-Input recordings are created via the \-record option and played back via
-the \-playback option. The default is 'inp' (that is, a directory 'inp'
-in the same directory as the MESS executable). If this directory
-does not exist, it will be automatically created.
-.TP
-.B \-state_directory \fIpathname
-Specifies a single directory where save state files are stored. Save
-state files are read and written either upon user request, or when using
-the \-autosave option. The default is 'sta' (that is, a directory 'sta'
-in the same directory as the MESS executable). If this directory does
-not exist, it will be automatically created.
-.TP
-.B \-snapshot_directory \fIpathname
-Specifies a single directory where screen snapshots are stored, when
-requested by the user. The default is 'snap' (that is, a directory 'snap'
-in the same directory as the MESS executable). If this directory
-does not exist, it will be automatically created.
-.TP
-.B \-diff_directory \fIpathname
-Specifies a single directory where hard drive differencing files are
-stored. Hard drive differencing files store any data that is written
-back to a hard disk image, in order to preserve the original image. The
-differencing files are created at startup when a system with a hard disk
-image. The default is 'diff' (that is, a directory 'diff' in the same
-directory as the MESS executable). If this directory does not exist,
-it will be automatically created.
-.TP
-.B \-comment_directory \fIpathname
-Specifies a single directory where debugger comment files are stored.
-Debugger comment files are written by the debugger when comments are
-added to the disassembly for a system. The default is 'comments' (that is,
-a directory 'comments' in the same directory as the MESS executable).
-If this directory does not exist, it will be automatically created.
-.\"
-.\" *******************************************************
-.SS State/playback options
-.\" *******************************************************
-.TP
-.B \-state \fIslot
-Immediately after starting the specified system, will cause the save
-state in the specified \fIslot\fP to be loaded.
-.TP
-.B \-[no]autosave
-When enabled, automatically creates a save state file when exiting MESS
-and automatically attempts to reload it when later starting MESS with
-the same system. This only works for systems that have explicitly enabled
-save state support in their driver. The default is OFF (\-noautosave).
-.TP
-.B \-playback, \-pb \fIfilename
-Specifies a file from which to play back a series of system inputs. This
-feature does not work reliably for all systems, but can be used to watch
-a previously recorded system 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. The
-default is NULL (no playback).
-.TP
-.B \-[no]exit_after_playback
-If play back is enabled (see \-playback option) the program exits when
-end of file is reached. Otherwise the machine will continue to run.
-Default is OFF (\-noexit_after_playback).
-.TP
-.B \-record, \-rec \fIfilename
-Specifies a file to record all input from a system session. This can be
-used to record a system session for later playback. This feature does not
-work reliably for all systems, but can be used to watch a previously
-recorded system 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. The default is NULL
-(no recording).
-.TP
-.B \-[no]record_timecode
-Specify whether 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 file is saved on inp folder.
-Default is OFF (\-norecord_timecode).
-.TP
-.B \-mngwrite \fIfilename
-Writes each video frame to the given file in MNG format, producing
-an animation of the system session.
-Note that \-mngwrite only writes video frames; it does not save any audio
-data. Use \-wavwrite for that, and reassemble the audio/video using
-offline tools. The default is NULL (no recording).
-.TP
-.B \-aviwrite \fIfilename
-Stream video and sound data to the given file
-in AVI format, producing an animation of the system session complete
-with sound. The default is NULL (no recording).
-.TP
-.B \-wavwrite \fIfilename
-Writes the final mixer output to the given file
-in WAV format, producing an audio recording of the system session.
-The default is NULL (no recording).
-.TP
-.B \-snapname \fIstring
-Describes how MESS should name files for snapshots. \fIstring\fP
-provides a template that is used to generate a filename. Three
-simple substitutions are provided: the / character represents the
-path separator on any target platform (even Windows); the literal \fB%g\fP
-represents the driver name of the current system; and the literal \fB%i\fP
-represents an incrementing index. If \fB%i\fP is omitted, then each
-snapshot taken will overwrite the previous one; otherwise, MESS will
-find the next empty value for \fB%i\fP and use that for a filename. The
-default is \fB%g/%i\fP, which creates a separate folder for each system,
-and names the snapshots under it starting with 0000 and increasing
-from there. In addition to the above, for drivers using different
-media, like carts or floppy disks, you can also use the
-\fB%d\fP\fI_[media]\fP indicator. Replace \fI[media]\fP with the media
-switch you want to use. A few examples: if you use
-.B mess nes \-cart robby \-snapname %g/%d_cart
-snapshots will be saved as \fBsnaps/nes/robby.png\fP; if you use
-.B mess c64 \-flop1 robby \-snapname %g/%d_flop1/%i
-snapshots will be saved as \fBsnaps/c64/robby/0000.png\fP.
-.TP
-.B \-snapsize \fIwidth\fRx\fIheight
-Hard\-codes the size for snapshots and movie recording. By default,
-MESS 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 MESS 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 default is 'auto'.
-.TP
-.B \-snapview internal\fR|\fBauto\fR|\fIviewname
-Specifies the view to use when rendering snapshots and movies. By
-default, both use a special 'internal' view, which renders a separate
-snapshot per screen or renders movies only of the first screen. By
-specifying this option, you can override this default behavior and
-select a single view that will apply to all snapshots and movies.
-Note that \fIviewname\fP does not need to be a perfect match; rather, it
-will select the first view whose name matches all the characters
-specified by \fIviewname\fP. For example, \-snapview native will match the
-"Native (15:14)" view even though it is not a perfect match.
-\fIviewname\fP can also be 'auto', which selects the first view with all
-screens present. The default value is 'internal'.
-.TP
-.B \-[no]snapbilinear
-Specify whether snapshot/movie should have bilinear filtering applied.
-Default is ON (\-snapbilinear).
-.TP
-.B \-statename \fIstring
-Describes how MESS should store save state files, relative to the
-state_directory path. \fIstring\fP provides a template that
-is used to generate a relative path. Two simple substitutions are
-provided: the / character represents the path separator on any target
-platform (even Windows); the literal \fB%g\fP represents the driver name of
-the current game. The default is '%g', which creates a separate folder
-for each game. In addition to the above, for drivers using different
-media, like carts or floppy disks, you can also use the
-\fB%d_\fP\fI[media]\fP indicator. Replace \fI[media]\fP with the media
-switch you want to use. A few examples: if you use
-.B mess nes \-cart robby \-statename %g/%d_cart
-save states will be stored inside \fBsta/nes/robby/\fP; if you use
-.B mess c64 \-flop1 robby \-statename %g/%d_flop1
-save states will be stored inside \fBsta/c64/robby/\fP.
-.TP
-.B \-[no]burnin
-Tracks brightness of the screen during play and at the end of
-emulation generates a PNG that can be used to simulate burn\-in
-effects on other systems. The resulting PNG is created such that the
-least\-used areas of the screen are fully white (since burned\-in areas
-are darker, all other areas of the screen must be lightened a touch).
-The intention is that this PNG can be loaded via an artwork file with
-a low alpha (e.g, 0.1\-0.2 seems to work well) and blended over the
-entire screen. The PNG files are saved in the snap directory under
-the system/burnin\-<screen.name>.png. The default is OFF (\-noburnin).
-.\"
-.\" *******************************************************
-.SS Performance options
-.\" *******************************************************
-.TP
-.B \-[no]autoframeskip, \-[no]afs
-Automatically determines the frameskip level while you're playing the
-system, adjusting it constantly in a frantic attempt to keep the system
-running at full speed. Turning this on overrides the value you have set
-for \-frameskip below. The default is OFF (\-noautoframeskip).
-.TP
-.B \-frameskip, \-fs \fIvalue
-Specifies the frameskip value (autoframeskip must be disabled). This is the
-number of frames out of every 12 to drop when running. For example, if you
-say \-frameskip 2, then MESS will display 10 out of every 12 frames. By
-skipping those frames, you may be able to get full speed in a system that
-requires more horsepower than your computer has. The default value is 0,
-which skips no frames.
-.TP
-.B \-seconds_to_run, \-str \fIvalue
-This option can be used for benchmarking and automated testing. It tells
-MESS to stop execution after a fixed number of seconds. By combining
-this with a fixed set of other command line options, you can set up a
-consistent environment for benchmarking MESS performance. In addition,
-upon exit, the \-str option will write a screenshot called final.png
-to the system's snapshot directory.
-.TP
-.B \-[no]throttle
-Configures the default thottling setting. When throttling is on, MESS
-attempts to keep the system running at the system's intended speed. When
-throttling is off, MESS runs the system as fast as it can. Note that the
-fastest speed is more often than not limited by your graphics card,
-especially for older systems. The default is ON (\-throttle).
-.TP
-.B \-[no]sleep
-Allows MESS to give time back to the system when running with \-throttle.
-This allows other programs to have some CPU time, assuming that the
-system isn't taxing 100% of your CPU resources. This option can potentially
-cause hiccups in performance if other demanding programs are running.
-The default is ON (\-sleep).
-.TP
-.B \-speed \fIvalue
-Controls the speed of gameplay, relative to realtime; smaller numbers are
-slower. Default is 1.00.
-.TP
-.B \-[no]refreshspeed, \-[no]rs
-Automatically adjusts the \fB\-speed\fR parameter to keep the effective refresh
-rate below that of the lowest screen refresh rate.
-Default is OFF (\-norefreshspeed).
-.\"
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" OS specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-numprocessors, \-np \fIvalue
-Set number of processors; this overrides the number the system reports.
-.TP
-.B \-bench \fIvalue
-Benchmark for the given number of emulated seconds;
-implies \-video none \-sound none \-nothrottle.
-.\"
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-[no]sdlvideofps
-Show SDL video performance. Default is OFF (\-nosdlvideofps).
-.\"
-.\" *******************************************************
-.SS Rotation options
-.\" *******************************************************
-.TP
-.B \-[no]rotate
-Rotate the system to match its normal state (horizontal/vertical). This
-ensures that both vertically and horizontally oriented systems show up
-correctly without the need to rotate your monitor. If you want to keep
-the system displaying 'raw' on the screen the way the actual machine would
-have, turn this option off. The default is ON (\-rotate).
-.TP
-.B \-[no]ror \-[no]rol
-Rotate the system screen to the right (clockwise) or left
-(counter\-clockwise) relative to either its normal state (if \-rotate
-is specified) or its native state (if \-norotate is specified).
-Default for both is OFF (\-noror \-norol).
-.TP
-.B \-[no]autoror \-[no]autorol
-These options are designed for use with pivoting screens that only
-pivot in a single direction. If your screen only pivots clockwise,
-use \-autorol to ensure that the system will fill the screen either
-horizontally or vertically in one of the directions you can handle.
-If your screen only pivots counter\-clockwise, use \-autoror.
-Default for both is OFF (\-noautoror \-noautorol).
-.TP
-.B \-[no]flipx \-[no]flipy
-Flip (mirror) the system screen either horizontally (\-flipx) or
-vertically (\-flipy). The flips are applied after the \-rotate and
-\-ror/\-rol options are applied.
-Default for both is OFF (\-noflipx \-noflipy).
-.\"
-.\" *******************************************************
-.SS Artwork options
-.\" *******************************************************
-.TP
-.B \-[no]artwork_crop, \-[no]artcrop
-Enable cropping of artwork to the system screen area only. This
-option can also be controlled via the Video Options menu in the user
-interface. The default is OFF (\-noartwork_crop).
-.TP
-.B \-[no]use_backdrops, \-[no]backdrop
-Enables/disables the display of backdrops. The default is ON
-(\-use_backdrops).
-.TP
-.B \-[no]use_overlays, \-[no]overlay
-Enables/disables the display of overlays. The default is ON
-(\-use_overlays).
-.TP
-.B \-[no]use_bezels, \-[no]bezel
-Enables/disables the display of bezels. The default is ON
-(\-use_bezels).
-.TP
-.B \-[no]use_cpanels, \-[no]cpanel
-Enables/disables the display of cpanels. The default is ON
-(\-use_bezels).
-.TP
-.B \-[no]use_marquees, \-[no]marquee
-Enables/disables the display of marquees. The default is ON
-(\-use_bezels).
-.\"
-.\" *******************************************************
-.SS Screen options
-.\" *******************************************************
-.TP
-.B \-brightness \fIvalue
-Controls the default brightness, or black level, of the system screens.
-This option does not affect the artwork or other parts of the display.
-Using the MESS 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 (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.
-.TP
-.B \-contrast \fIvalue
-Controls the contrast, or white level, of the system screens. This option
-does not affect the artwork or other parts of the display. Using the
-MESS 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. The default is 1.0.
-.TP
-.B \-gamma \fIvalue
-Controls the gamma, which produces a potentially nonlinear black to
-white ramp, for the system screens. This option does not affect the
-artwork or other parts of the display. Using the MESS 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. The default is 1.0.
-.TP
-.B \-pause_brightness \fIvalue
-This controls the brightness level when MESS is paused. The default
-value is 0.65.
-.TP
-.B \-effect\fR [\fInone\fR|\fIfilename[.png]\fR]
-Name of a PNG file to use for visual effects, or 'none'. Default is 'none'.
-.\"
-.\" *******************************************************
-.SS Vector rendering options
-.\" *******************************************************
-.TP
-.B \-beam_width_min \fIvalue
-.TP
-.B \-beam_width_max \fIvalue
-Sets the minimum and maximum width of the vectors. This is a scaling factor
-against the standard vector width, which is interpolated between minimum and
-maximum according to the beam's intensity. A value of 1.0 will keep the
-default vector line width. Smaller values will reduce the width, and larger
-values will increase the width. The default is 1.0.
-.TP
-.B \-beam_intensity_weight \fIvalue
-Applies an exponential weight to the minimum and maximum beam width. For
-positive values the interpolated scaling factor will affect lines with higher
-intensity more than lines with lower intensity. The default is 0.0.
-.TP
-.B \-flicker \fIvalue
-Simulates a vector "flicker" effect, similar to a vector monitor that
-needs adjustment. This option requires a float argument in the range of
-0.00\-100.00 (0=none, 100=maximum). The default is 0.
-.\"
-.\" *******************************************************
-.SS Video options
-.\" *******************************************************
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-video\fR [\fIsoft\fR|\fIopengl\fR|\fIbgfx\fR|\fInone\fR]
-Specifies which video subsystem to use for drawing:
-.br
-\fBsoft\fR uses software rendering, which is slower but more compatible.
-.br
-\fBopengl\fR uses OpenGL and your graphics accelerator to speed up many
-aspects of drawing MAME including compositing artwork, overlays, and
-bezels, as well as stretching the image to fit your screen.
-.br
-\fBbgfx\fR uses the bgfx renderer which supports portable shaders and
-multiple graphics APIs including OpenGL, OpenGL ES and DirectX.
-.br
-\fBnone\fR does no drawing and is intended for CPU benchmarking.
-.br
-Default is 'soft' on Linux or 'opengl' on macOS.
-.TP
-.B \-numscreens \fR[\fI1-4\fR]
-Number of screens to create; usually, you want just one. Default is '1'.
-.TP
-.B \-[no]window, \-[no]w
-Run MESS in either full screen or a window. This is a fully\-featured window
-mode where the window resizes as necessary to track what the system does.
-And you can resize it yourself with your OS's standard window controls.
-The default is OFF (\-nowindow).
-.TP
-.B \-[no]maximize, \-[no]max
-Controls initial window size in windowed mode. If it is set on, the
-window will initially be set to the maximum supported size when you
-start MESS. If it is turned off, the window will start out at the
-smallest supported size. This option only has an effect when the
-\-window option is used. The default is ON (\-maximize).
-.TP
-.B \-[no]keepaspect, \-[no]ka
-Forces the correct aspect ratio. This means when you're resizing the window
-in windowed mode the actual system image will resize in discrete steps to
-maintain the proper shape of the system graphics. If you turn this off you can
-resize the window to anything you like and get funny squishing and stretching.
-The same applies for full\-screen. Default is ON (\-keepaspect).
-.TP
-.B \-[no]unevenstretch, \-[no]ues
-Allow non\-integer stretch factors. Video purists should stay far, far away
-from this option, while everyone else will be happy to know that it lets you
-fill the screen properly in full\-screen mode. Default is ON (\-unevenstretch).
-.TP
-.B \-[no]unevenstretchx, \-[no]uesx
-Act as \-[no]unevenstretch on horizontal basis only.
-.TP
-.B \-[no]intoverscan, \-[no]ios
-Allow overscan on integer scaled targets.
-.TP
-.B \-intscalex, \-sx
-Set horizontal integer scale factor.
-.TP
-.B \-intscaley, \-sy
-Set vertical integer scale factor.
-.TP
-.B \-[no]centerh
-Center horizontally within the view area. Default is ON (\-centerh).
-.TP
-.B \-[no]centerv
-Center vertically within the view area. Default is ON (\-centerv).
-.TP
-.B \-[no]waitvsync, \-[no]vs
-Enable waiting for the start of VBLANK before flipping screens;
-reduces tearing effects. Default is OFF (\-nowaitvsync).
-.TP
-.B \-[no]syncrefresh, \-[no]srf
-Enable using the start of VBLANK for throttling instead of the game time.
-Default is OFF (\-nosyncrefresh).
-.\"
-.\" *******************************************************
-.SS Software video rendering subsystem options
-.\" *******************************************************
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.B NOTE:
-All the options in this group are available only with softare video
-rendering subsystem, i.e \fB\-video soft\fR.
-.TP
-.B \-prescale\fR [\fIvalue\fR]
-Scale screen rendering by this amount in software. Default is 1.
-.TP
-.B \-scalemode, \-sm \fR[\fInone\fR|\fIasync\fR|\fIyv12\fR|\fIyuy2\fR|\fIyv12x2\fR|\fIyuy2x2\fR]
-Hardware scaling mode.
-.br
-\fBnone\fR use software rendering.
-.br
-\fBasync\fR async overlay.
-.br
-\fByv12\fR yv12 overlay.
-.br
-\fByuy2\fR yuy2 overlay.
-.br
-\fByv12x2\fR yv12 overlay using x2 prescaling.
-.br
-\fByuy2x2\fR yuy2 overlay using x2 prescaling.
-.br
-Default is NONE.
-.\"
-.\" *******************************************************
-.SS OpenGL video rendering subsystem options
-.\" *******************************************************
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.B NOTE:
-All the options in this group are available only with OpenGL video
-rendering subsystem, i.e \fB\-video opengl\fR.
-.TP
-.B \-[no]filter, \-[no]glfilter, \-[no]flt
-Enable bilinear filtering on screen output. Default is ON (\-filter).
-.TP
-.B \-prescale\fR [\fIvalue\fR]
-Scale screen rendering by this amount in software. Default is 1.
-.TP
-.B \-[no]gl_forcepow2texture
-Force power of two textures. Default is OFF (\-nogl_forcepow2texture).
-.TP
-.B \-[no]gl_notexturerect
-Don't use OpenGL GL_ARB_texture_rectangle. Turn off if
-corruption occurs in OpenGL mode, at cost of some performance
-loss. Default is ON (\-gl_notexturerect).
-.TP
-.B \-[no]gl_vbo
-Enable OpenGL VBO, if available, for a performance increase.
-Turn off if corruption occurs. Default is ON (\-gl_vbo).
-.TP
-.B \-[no]gl_pbo
-Enable OpenGL PBO, if available, for a performance increase.
-Turn off if corruption occurs. Default is ON (\-gl_pbo).
-.TP
-.B \-[no]gl_glsl
-Enable OpenGL GLSL, if available, for a performance increase.
-Default is OFF (\-nogl_glsl).
-.TP
-.B \-gl_glsl_filter \fIvalue
-Enable OpenGL GLSL filtering instead of FF filtering 0=plain, 1=bilinear.
-Default is 1: bilinear.
-.TP
-.BR \-glsl_shader_mame[0\-9]
-Preferred custom OpenGL GLSL shader set mame bitmap (from 0 to 9).
-.TP
-.BR \-glsl_shader_screen[0\-9]
-Preferred custom OpenGL GLSL shader screen bitmap (from 0 to 9).
-.TP
-.B \-gl_glsl_vid_attr
-Enable OpenGL GLSL handling of brightness and contrast. Better RGB system
-performance for free. Default is ON.
-.TP
-.B \-screen
-Explicit name for all screens; 'auto' here will try to make a best guess.
-.TP
-.B \-aspect, \-screen_aspect
-Aspect ratio for all screens; 'auto' here will try to make a best guess.
-.TP
-.B \-resolution, \-r
-Preferred resolution for all screens;
-format is \fIwidth\fRx\fIheight\fR[@\fIrefreshrate\fR] or 'auto'.
-.TP
-.B \-view
-Preferred view for all screens
-.TP
-.B \-screen[0\-3]
-Explicit name of the first|second|third|fourth screen; 'auto' here will try
-to make a best guess.
-.TP
-.B \-aspect[0\-3]
-Aspect ratio of the first|second|third|fourth screen; 'auto' here will try
-to make a best guess.
-.TP
-.B \-resolution[0\-3], \-r[0\-3]
-Preferred resolution for the first|second|third|fourth screen;
-format is \fIwidth\fRx\fIheight\fR[@\fIrefreshrate\fR] or 'auto'.
-.TP
-.B \-view[0\-3]
-Preferred view for the first|second|third|fourth screen.
-.\"
-.\" *******************************************************
-.SS BGFX post\-processing options
-.\" *******************************************************
-.B NOTE:
-All the options in this group are available only when BGFX video
-post\-processing is enabled, i.e \fB\-video bgfx\fR. For full info on BGFX
-please visit official MAME documentation page:
-.br
-http://docs.mamedev.org/advanced/bgfx.html
-.TP
-.B \-bgfx_path \fIpathname
-This is where your BGFX shader files are stored.
-The default is 'bgfx' (that is, a directory "bgfx" in the same directory
-as the MESS executable).
-.TP
-.B \-bgfx_backend \fIauto\fR|\fIopengl\fR
-Selects a rendering backend for BGFX to use. The default is 'auto',
-which will let MESS choose the best selection for you.
-.TP
-.B \-bgfx_debug
-Enables BGFX debugging features. Most users will not need to use this.
-.TP
-.B \-bgfx_screen_chains \fIdefault\fR|\fIunfiltered\fR|\fIhlsl\fR[,...]
-This dictates how to handle BGFX rendering on a per\-display basis.
-For each display specify one of the possible choices:
-.br
-\fBdefault\fR default bilinear filterered output
-.br
-\fBunfiltered\fR nearest neighbor unfiltered output
-.br
-\fBhlsl\fR HLSL display simulation through shaders
-.br
-Separate directives for each window with a comma (,) and for each physical
-screen with a colon (:). For example, for an emulated game with 3 displays
-emulated on 3 windows on your monitor,
-.B \-bgfx_screen_chains default,unfiltered,default
-specifies to apply default filter on what is been rendered on the first
-and third window and leave the content of the second window unfiltered.
-.TP
-.B \-bgfx_shadow_mask \fIfilename
-This specifies the shadow mask effect PNG file. Default is 'slot-mask.png'.
-.TP
-.B \-bgfx_avi_name \fIfilename
-This specifies a filename for BGFX output logging.
-.\"
-.\" *******************************************************
-.SS Full screen options
-.\" *******************************************************
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-[no]switchres
-Affects full screen mode only. Chooses if MESS can try to change the screen
-resolution (color depth is normally left alone) when in full\-screen mode. If
-it's off, you always get your desktop resolution in full\-screen mode (which can
-be useful for LCDs). Default is OFF (\-noswitchres).
-.TP
-.B \-[no]useallheads
-Split full screen image across monitors. Default is OFF (\-nouseallhead).
-.\"
-.\" *******************************************************
-.SS Sound options
-.\" *******************************************************
-.TP
-.B \-sound\fR [\fIsdl\fR|\fIportaudio\fR|\fIcoreaudio\fR|\fIdsound\fR|\fIxaudio2\fR|\fInone\fR]
-Specifies which sound subsystem to use for audio output:
-.br
-\fBsdl\fR uses the Simple DirectMedia Layer audio output system
-(not available on Windows by default).
-.br
-\fBportaudio\fR uses the PortAudio library which supports low-latency
-output and multiple audio APIs.
-.br
-\fBcoreaudio\fR uses the Core Audio API which supports low-latency
-output and AudioUnit effects (only available on macOS).
-.br
-\fBdsound\fR uses the DirectSound API (only available on Windows).
-.br
-\fBxaudio2\fR uses the XAudio2 API which supports low-latency output
-(only available on Windows).
-.br
-\fBnone\fR produces no audio output.
-.br
-Default is 'dsound' on Windows, 'coreaudio' on macOS or 'sdl' on other
-platforms.
-.TP
-.B \-samplerate, \-sr \fIvalue
-Sets the audio sample rate. Smaller values (e.g. 11025) cause lower
-audio quality but faster emulation speed. Higher values (e.g. 48000)
-cause higher audio quality but slower emulation speed. The default is
-48000.
-.TP
-.B \-[no]samples
-Use samples if available. The default is ON (\-samples).
-.TP
-.B \-[no]compressor
-Enable audio compressor. It temporarily reduces the overall volume when
-the audio output is overdriven. The default is ON (\-compressor).
-.TP
-.B \-volume, \-vol \fIvalue
-Sets the startup volume. It can later be changed with the user interface
-(see Keys section). The volume is an attenuation in dB:
-for example, '\-volume \-12' will start with \-12dB attenuation.
-The default is 0.
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-audio_latency \fIvalue
-This controls the amount of latency built into the audio streaming.
-The exact behavior depends on the selected audio output module (see
-the \-sound option). Smaller values provide less audio delay while
-requiring better system performance. Higher values increase audio
-delay but may help avoid buffer under-runs and audio interruptions.
-The default is 1.
-.\"
-.\" *******************************************************
-.SS Input options
-.\" *******************************************************
-.TP
-.B \-[no]coin_lockout, \-[no]coinlock
-Enables simulation of the "coin lockout" feature that is implemented
-on a number of arcade game PCBs. It was up to the operator whether or not
-the coin lockout outputs were actually connected to the coin
-mechanisms. If this feature is enabled, then attempts to enter a coin
-while the lockout is active will fail and will display a popup message
-in the user interface. If this feature is disabled, the coin lockout
-signal will be ignored. The default is ON (\-coin_lockout).
-.TP
-.B \-ctrlr \fIcontroller
-Enables support for special controllers. Configuration files are
-loaded from the ctrlrpath. They are in the same format as the .cfg
-files that are saved, but only control configuration data is read
-from the file. The default is NULL (no controller file).
-.TP
-.B \-[no]mouse
-Controls whether or not MESS looks for a mouse controller to use. Note
-that in many cases, lightguns are treated as mice by the operating
-system, so you may need to enable this to enable lightgun support. When
-this is enabled, you will not be able to use your mouse while running
-MESS. If you want to get control of your computer back, you will need
-to either pause MESS or quit. The default is OFF (\-nomouse).
-.TP
-.B \-[no]joystick, \-[no]joy
-Controls whether or not MESS looks for joystick/gamepad controllers.
-The default is ON (\-joystick).
-.TP
-.B \-[no]lightgun, \-[no]gun
-Controls whether or not MESS makes use of lightgun controllers.
-Note that most lightguns map to the mouse, so using \-lightgun and
-\-mouse together may produce strange results. The default is OFF
-(\-nolightgun).
-.TP
-.B \-[no]multikeyboard, \-[no]multikey
-Determines whether MESS differentiates between multiple keyboards.
-Some systems may report more than one keyboard; by default, the data
-from all of these keyboards is combined so that it looks like a single
-keyboard. Turning this option on will enable MESS to report keypresses
-on different keyboards independently. The default is OFF
-(\-nomultikeyboard).
-.TP
-.B \-[no]multimouse
-Determines whether MESS differentiates between multiple mice. Some
-systems may report more than one mouse device; by default, the data
-from all of these mice is combined so that it looks like a single
-mouse. Turning this option on will enable MESS to report mouse
-movement and button presses on different mice independently. The
-default is OFF (\-nomultimouse).
-.TP
-.B \-[no]steadykey, \-[no]steady
-Some systems require two or more buttons to be pressed at exactly the
-same time to make special moves. Due to limitations in the PC keyboard
-hardware, it can be difficult or even impossible to accomplish that
-using the standard keyboard handling. This option selects a different
-handling that makes it easier to register simultaneous button presses,
-but has the disadvantage of making controls less responsive. The
-default is OFF (\-nosteadykey).
-.TP
-.B \-[no]ui_active
-Enable MESS user interface on top of emulated keyboard (if present).
-User interface may be toggled during execution by pressing the key
-defined with \-ui_modekey.
-Default is OFF (\-noui_active).
-.TP
-.B \-[no]offscreen_reload, \-[no]reload
-Controls whether or not MESS treats a second button input from a
-lightgun as a reload signal. In this case, MESS will report the gun's
-position as (0,MAX) with the trigger held, which is equivalent to an
-offscreen reload. This is only needed for systems that required you to
-shoot offscreen to reload, and then only if your gun does not support
-off screen reloads. The default is OFF (\-nooffscreen_reload).
-.TP
-.B \-joystick_map, \-joymap \fImap
-Controls how joystick values map to digital joystick controls.
-See /usr/share/doc/mame\-common/config.txt for full details on
-joymap format.
-.TP
-.B \-joystick_deadzone, \-joy_deadzone, \-jdz \fIvalue
-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.
-.TP
-.B \-joystick_saturation, \-joy_saturation, \-jsat \fIvalue
-If you play with an analog joystick, the ends can drift a little,
-and may not match in the +/\- directions. joystick_saturation tells how
-far along an axis movement change will be accepted before it reaches
-the maximum range. 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.85.
-.TP
-.B \-[no]natural, \-[no]nat
-Allows user to specify whether or not to use a natural keyboard.
-This allows you to start your game or system in a 'native' mode, depending
-on your region, allowing compatibility for non\-"QWERTY" style keyboards.
-The default is OFF (\-nonatural).
-.TP
-.B \-[no]joystick_contradictory, \-[no]joy_contradictory
-Enable contradictory direction digital joystick input at the same time.
-Default is OFF (\-nojoystick_contradictory).
-.TP
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-uimodekey, \-umk \fIvalue
-Specifies the key used to toggle between full and partial UI mode.
-.TP
-.B \-uifontprovider \fIauto\fR|\fIsdl\fR|\fInone
-Provider for ui font.
-.TP
-.B \-output \fIconsole\fR|\fInetwork\fR|\fInone
-Provider for output.
-.TP
-.B \-keyboardprovider \fIauto\fR|\fIsdl\fR|\fInone
-Provider for keyboard input.
-.TP
-.B \-mouseprovider \fIauto\fR|\fIsdl\fR|\fInone
-Provider for mouse input.
-.TP
-.B \-lightgunprovider \fIauto\fR|\fInone
-Provider for lightgun input.
-.TP
-.B \-joystickprovider \fIauto\fR|\fIsdl\fR|\fInone
-Provider for joystick input.
-.TP
-.B \-[no]keymap
-Enable keymap for non\-QWERTY keyboards. Used in conjunction with
-\fB\-keymap_file\fR. Default is OFF (\-nokeymap).
-.TP
-.B \-keymap_file \fIkeymap_file
-Specifies the full path to the keymap file to be used. A few
-keymap files are available in /usr/share/games/mess/keymaps.
-.TP
-.B \-joy_idx[0\-8] \fIjoystick
-With these options you can assign a joystick to a
-specific index in MESS. Even if the kernel will list the joysticks
-in a different order on the next boot, MESS will still see the joystick
-as e.g. "Joystick 2". Use mame \-v to see which joysticks are recognized.
-Default is 'auto'.
-.TP
-.B \-[no]sixaxis
-Use special handling for PS3 Sixaxis controllers.
-Default is OFF (\-nosixaxis).
-.TP
-.B \-lightgun_index[1\-8]
-Map lightgun to specific index in MESS.
-.TP
-.B \-videodriver, \-vd x11\fR|\fBdirectfb\fR|\fBauto
-SDL video driver to use; auto selects SDL default.
-.TP
-.B \-audiodriver, \-ad alsa\fR|\fBarts\fR|\fBauto
-SDL audio driver to use; auto selects SDL default.
-.TP
-.B \-gl_lib alsa\fR|\fBarts\fR|\fBauto
-Alternative libGL.so to use; auto selects SDL default.
-.\"
-.\" *******************************************************
-.SS Input automatic enable options
-.\" *******************************************************
-.TP
-.B \-paddle_device, \-paddle \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-adstick_device, \-adstick \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-pedal_device, \-pedal \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-dial_device, \-dial \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-trackball_device, \-trackball \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-lightgun_device \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-positional_device \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-.TP
-.B \-mouse_device \fR[\fInone\fR|\fIkeyboard\fR|\fImouse\fR|\fIlightgun\fR|\fIjoystick\fR]
-Each of these options controls automatically enabling the mouse, or
-joystick 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 system that has a paddle control will 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.
-.\"
-.\" *******************************************************
-.SS Debugging options
-.\" *******************************************************
-.TP
-.B \-[no]log
-Creates a file called error.log which contains all of the internal
-log messages generated by the MESS core and system drivers. The default
-is OFF (\-nolog).
-.TP
-.B \-[no]verbose, \-[no]v
-Displays internal diagnostic information. This information is very
-useful for debugging problems with your configuration.
-Please use the \-verbose option and include the resulting information
-when reporting bugs. The default is OFF (\-noverbose).
-.TP
-.B \-[no]update_in_pause
-Enables updating the screen bitmap while the system is paused. This is
-useful for debuggin in some scenarios (and gets in the way in others).
-Default is OFF (\-noupdate_in_pause).
-.TP
-.B \-[no]debug, \-[no]d
-Activates the integrated debugger. By default, the debugger is entered
-by pressing the tilde (~) key during emulation. It is also entered
-immediately at startup. The default is OFF (\-nodebug).
-.TP
-.B \-debugscript \fIfilename
-Specifies a file that contains a list of debugger commands to execute
-immediately upon startup. The default is NULL (no commands).
-.\"
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.\" SDL specific
-.\" +++++++++++++++++++++++++++++++++++++++++++++++++++++++
-.TP
-.B \-debugger \fIdebugger_name
-Name of the debugger to use. Default is AUTO.
-.TP
-.B \-debugger_font, \-dfont \fIfont_name
-Specifies the font to use for debugging. Default is AUTO.
-.TP
-.B \-debugger_font_size, \-dfontsize \fIsize
-Specifies the font size to use for debugging.
-.TP
-.B \-[no]oslog
-Outputs the error.log data to the system debugger. This can be used at
-the same time as \-log to output the log data to both targets as well.
-Default is OFF (\-nooslog).
-.\"
-.\" *******************************************************
-.SS Misc options
-.\" *******************************************************
-.TP
-.B \-[no]drc
-Enable DRC cpu core if available. Default is ON (\-drc).
-.TP
-.B \-[no]drc_use_c
-Force DRC use C backend. Default is OFF (\-nodrc_use_c).
-.TP
-.B \-[no]drc_log_uml
-Write DRC UML disassembly log. Default is OFF (\-nodrc_log_uml).
-.TP
-.B \-[no]drc_log_native
-Write DRC native disassembly log. Default is OFF (\-no_drc_log_native).
-.TP
-.B \-bios \fIbiosname
-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. The default is 'default'.
-.TP
-.B \-[no]cheat, \-[no]c
-Activates the cheat menu with autofire options and other tricks from
-the cheat database, if present.
-The default is OFF (\-nocheat).
-.TP
-.B \-[no]skip_gameinfo
-Forces MESS to skip displaying the system info screen. The default is OFF
-(\-noskip_gameinfo).
-.TP
-.B \-uifont \fIfontname
-Specifies the name of a BDF font file to use for the UI font. If this
-font cannot be found or cannot be loaded, the system will fall back
-to its built\-in UI font. On some platforms \fIfontname\fP can be a system
-font name instead of a BDF font file. The default is 'default' (use
-the OSD\-determined default font).
-.TP
-.B \-ui \fIsimple\fR|\fIcabinet
-Type of UI.
-.TP
-.B \-ramsize, \-ram \fIvalue
-Size of RAM (if supported by driver).
-.TP
-.B \-[no]confirm_quit
-Display confirm quit screen on exit. Default is ON (\-confirm_quit).
-.TP
-.B \-[no]ui_mouse
-Display UI mouse cursor. Default is OFF (\-noui_mouse).
-.TP
-.B \-autoboot_command, \-ab \fIcommand
-Command string to execute after machine boot (in quotes ""). To issue
-a quote to the emulation, use \fB"""\fP in the string.
-Using \fB\\n\fP will issue a create a new line, issuing what was
-typed prior as a command. Example:
-\fB\-autoboot_command "load """$""",8,1\\n"\fP.
-.TP
-.B \-autoboot_delay \fR[\fIvalue\fP]
-Timer delay (in seconds) to trigger command execution on autoboot.
-Default is 2.
-.TP
-.B \-autoboot_script, \-script \fR[\fIfilename.lua\fP]
-File containing scripting to execute after machine boot.
-.TP
-.B \-[no]http
-Enable local http server. Default is OFF (\-nohttp).
-.TP
-.B \-http_port \fIport
-Internal webserver listener port.
-.TP
-.B \-http_path \fIpath
-Path to web files. Default is /usr/share/games/mess/web.
-.TP
-.B \-[no]console
-Enable emulator LUA console. Default is OFF (\-noconsole).
-.TP
-.B \-[no]plugins
-Enable LUA plugin support. Default is ON (\-plugins).
-.TP
-.B \-plugin \fIvalue
-List of plugins to enable.
-.TP
-.B \-noplugin \fIvalue
-List of plugins to disable.
-.TP
-.B \-language, \-lang \fIvalue
-Display language. Default is 'English'.
-.TP
-.B \-newui, \-nu
-Use the new MESS UI.
-.TP
-.B \-watchdog \fIvalue
-Specifies a number of seconds after which MESS should automatically exit
-if it detects that the emulation has locked up.
-.\"
-.\"
-.\" SEE ALSO chapter
-.SH SEE ALSO
-castool(1), chdman(1), floptool(1), imgtool(1)
-.\"
-.\"
-.\" LEGAL NOTICE chapter
-.SH LEGAL NOTICE
-Please visit the MAME website for some important legal information:
-.PP
-http://mamedev.org/legal.html
diff --git a/docs/man/romcmp.1 b/docs/man/romcmp.1
index a3de1153d6f..3430f7ab18e 100644
--- a/docs/man/romcmp.1
+++ b/docs/man/romcmp.1
@@ -38,6 +38,9 @@ ROM set is a clone of another ROM set.
.TP
.B \-d
Enables a slower, more comprehensive comparison.
+.TP
+.B \-h
+Prints hashes (CRC-32, SHA-1) and 16-bit sums for all files.
.\"
.\" EXAMPLES chapter
.SH EXAMPLES
diff --git a/docs/source/advanced/bgfx.rst b/docs/source/advanced/bgfx.rst
index 06b35521ace..bb6e4205fa3 100644
--- a/docs/source/advanced/bgfx.rst
+++ b/docs/source/advanced/bgfx.rst
@@ -1,121 +1,218 @@
BGFX Effects for (nearly) Everyone
==================================
-By default, MAME outputs an idealized version of the video as it would be on the way to the arcade cabinet's monitor, with minimal modification of the output (primarily to stretch the game image back to the aspect ratio the monitor would traditionally have, usually 4:3) -- this works well, but misses some of the nostalgia factor. Arcade monitors were never ideal, even in perfect condition, and the nature of a CRT display distorts that image in ways that change the appearance significantly.
+.. contents:: :local:
-Modern LCD monitors simply do not look the same, and even computer CRT monitors cannot match the look of an arcade monitor without help.
-That's where the new BGFX renderer with HLSL comes into the picture.
+Introduction
+------------
-HLSL simulates most of the effects that a CRT arcade monitor has on the video, making the result look a lot more authentic. However, HLSL requires some effort on the user's part: the settings you use are going to be tailored to your PC's system specs, and especially the monitor you're using. Additionally, there were hundreds of thousands of monitors out there in arcades. Each was tuned and maintained differently, meaning there is no one correct appearance to judge by either. Basic guidelines will be provided here to help you, but you may also wish to ask for opinions on popular MAME-centric forums.
+By default, MAME outputs an idealized version of the video as it would be on the
+way to the arcade cabinet’s monitor, with minimal modification of the output
+(primarily to stretch the game image back to the aspect ratio the monitor would
+traditionally have, usually 4:3). This works well, but misses some of the
+nostalgia factor. Arcade monitors were never ideal, even in perfect condition,
+and the nature of a CRT display distorts that image in ways that change the
+appearance significantly.
+
+Modern LCD monitors simply do not look the same, and even computer CRT monitors
+cannot match the look of an arcade monitor without help.
+
+That’s where the new BGFX renderer with HLSL comes into the picture.
+
+HLSL simulates most of the effects that a CRT arcade monitor has on the video,
+making the result look a lot more authentic. However, HLSL requires some effort
+on the user’s part: the settings you use are going to be tailored to your PC’s
+system specs, and especially the monitor you’re using. Additionally, there were
+hundreds of thousands of monitors out there in arcades. Each was tuned and
+maintained differently, meaning there is no one correct appearance to judge by
+either. Basic guidelines will be provided here to help you, but you may also
+wish to ask for opinions on popular MAME-centric forums.
Resolution and Aspect Ratio
---------------------------
-Resolution is a very important subject for HLSL settings. You will want MAME to be using the native resolution of your monitor to avoid additional distortion and lag created by your monitor upscaling the display image.
+Resolution is a very important subject for HLSL settings. You will want MAME to
+be using the native resolution of your monitor to avoid additional distortion
+and lag caused by your monitor upscaling the display image.
-While most arcade machines used a 4:3 ratio display (or 3:4 for vertically oriented monitors like Pac-Man), it's difficult to find a consumer display that is 4:3 at this point. The good news is that that extra space on the sides isn't wasted. Many arcade cabinets used bezel artwork around the main display, and should you have the necessary artwork files, MAME will display that artwork. Turn the artwork view to Cropped for best results.
+While most arcade machines used a 4:3 ratio display (or 3:4 for vertically
+oriented monitors like Pac-Man), it’s difficult to find a consumer display that
+is 4:3 at this point. The good news is that that extra space on the sides isn’t
+wasted. Many arcade cabinets used bezel artwork around the main display, and
+should you have the necessary artwork files, MAME will display that artwork.
+Turn the **Zoom to Screen Area** setting in the video options menu to scale and
+crop the artwork so the emulated screen fills your display in one direction.
-Some older LCD displays used a native resolution of 1280x1024 and were a 5:4 aspect ratio. There's not enough extra space to display artwork, and you'll end up with some very slight pillarboxing, but the results will be still be good and on-par with a 4:3 monitor.
+Some older LCD displays used a native resolution of 1280×1024 and were a 5:4
+aspect ratio. There’s not enough extra space to display artwork, and you’ll end
+up with some very slight pillarboxing, but the results will be still be good and
+on-par with a 4:3 monitor.
Getting Started with BGFX
-------------------------
-You will need to have followed the initial MAME setup instructions elsewhere in this manual before beginning. Official MAME distributions include BGFX as of MAME 0.172, so you don't need to download any additional files.
+You will need to have followed the initial MAME setup instructions elsewhere in
+this manual before beginning. Official MAME distributions include BGFX as of
+MAME 0.172, so you don’t need to download any additional files.
-Open your ``mame.ini`` in your text editor of choice (e.g. Notepad), and make sure the following options are set correctly:
+Open your ``mame.ini`` file in your text editor of choice (e.g. Notepad), and
+make sure the following options are set correctly:
* ``video bgfx``
-Now, you may want to take a moment to look below at the Configuration Settings section to see how to set up these next options.
+Now, you may want to take a moment to look below at the Configuration Settings
+section to see how to set up these next options.
-As referenced in :ref:`advanced-multi-CFG`, MAME has a order in which it processes INI files. The BGFX settings can be edited in ``mame.ini``, but to take full advantage of the power of MAME's config files, you'll want to copy the BGFX settings from ``mame.ini`` to one of the other config files and make changes there.)
+As explained in :ref:`advanced-multi-CFG`, MAME has a order in which it
+processes INI files. The BGFX settings can be edited in ``mame.ini``, but to
+take full advantage of the power of MAME’s configuration files, you’ll want to
+copy the BGFX settings from ``mame.ini`` to one of the other configuration files
+and make changes there.
-In particular, you will want the ``bgfx_screen_chains`` to be specific to each game.
+In particular, you will want the ``bgfx_screen_chains`` to be specific to each
+game.
+
+Save your INI file(s) and you’re ready to begin.
-Save your .INI file(s) and you're ready to begin.
Configuration Settings
----------------------
-| **bgfx_path**
-|
-| This is where your BGFX shader files are stored. By default, this will be the BGFX folder in your MAME installation.
-|
-| **bgfx_backend**
-|
-| Selects a rendering backend for BGFX to use. Possible choices include ``d3d9``, ``d3d11``, ``d3d12``, ``opengl``, ``metal``, and ```vulkan``. The default is ``**auto**``, which will let MAME choose the best selection for you.
-|
-| ``d3d9`` -- Direct3D 9.0 Renderer (Requires Windows XP or higher)
-| ``d3d11`` -- Direct3D 11.0 Renderer (Requires Windows Vista with D3D11 update or Windows 7 or higher)
-| ``d3d12`` -- Direct3D 12.0 Renderer (Requires Windows 10)
-| ``opengl`` -- OpenGL Renderer (Requires OpenGL drivers, may work better on some poorly designed video cards, supported on Linux/Mac OS X)
-| ``metal`` -- Metal Apple Graphics API (Requires OS X 10.11 El Capitan or newer)
-| ``vulkan`` -- Vulkan Renderer
-|
-| **bgfx_debug**
-|
-| Enables BGFX debugging features. Most users will not need to use this.
-|
-| **bgfx_screen_chains**
-|
-| This dictates how to handle BGFX rendering on a per-display basis. Possible choices include ``hlsl``, ``unfiltered``, and ``default``.
-|
-| ``default`` -- **default** bilinear filterered output
-| ``unfiltered`` -- nearest neighbor unfiltered output
-| ``hlsl`` -- HLSL display simulation through shaders
-|
-| We make a distinction between emulated device screens (which we'll call a **screen**) and physical displays (which we'll call a **window**, set by ``-numscreens``) here. We use colons (:) to seperate windows, and commas (,) to seperate screens. Commas always go on the outside of the chain (see House Mannequin example)
-|
-| On a combination of a single window, single screen case, such as Pac-Man on one physical PC monitor, you can specify one entry like:
-|
-| **bgfx_screen_chains hlsl**
-|
-| Things get only slightly more complicated when we get to multiple windows and multiple screens.
-|
-| On a single window, multiple screen game, such as Darius on one physical PC monitor, specify multiple entries (one per window) like:
-|
-| bgfx_screen_chains hlsl,hlsl,hlsl
-|
-| This also works with single screen games where you are mirroring the output to more than one physical display. For instance, you could set up Pac-Man to have one unfiltered output for use with video broadcasting while a second display is set up HLSL for playing on.
-|
-| On a mulitple window, multiple screen game, such as Darius on three physical PC monitors, specify multiple entries (one per window) like:
-|
-| ``bgfx_screen_chains hlsl:hlsl:hlsl``
-|
-| Another example game would be Taisen Hot Gimmick, which used two CRTs to show individual player hands to just that player. If using two windows (two physical displays):
-|
-| ``bgfx_screen_chains hlsl:hlsl``
-|
-| One more special case is that Nichibutsu had a special cocktail mahjongg cabinet that used a CRT in the middle along with two LCD displays to show each player their hand. We would want the LCDs to be unfiltered and untouched as they were, while the CRT would be improved through HLSL. Since we want to give each player their own full screen display (two physical monitors) along with the LCD, we'll go with:
-|
-| **-numscreens 2 -view0 "Player 1" -view1 "Player 2" -video bgfx -bgfx_screen_chains hlsl,unfiltered,unfiltered:hlsl,unfiltered,unfiltered**
-|
-| This sets up the view for each display respectively, keeping HLSL effect on the CRT for each window (physical display) while going unfiltered for the LCD screens.
-|
-| If using only one window (one display), keep in mind the game still has three screens, so we would use:
-|
-| ``bgfx_screen_chains hlsl,unfiltered,unfiltered``
-|
-|
-| Note that the commas are on the outside edges, and any colons are in the middle.
-|
-| ``bgfx_shadow_mask``
-|
-| This specifies the shadow mask effect PNG file. By default this is ``**slot-mask.png**``.
-|
-|
+bgfx_path
+ This is where your BGFX shader files are stored. By default, this will be
+ the *bgfx* folder in your MAME installation folder.
+bgfx_backend
+ Selects a rendering backend for BGFX to use. Possible choices include
+ ``d3d9``, ``d3d11``, ``d3d12``, ``opengl``, ``gles``, ``metal``, and
+ ```vulkan``. The default is ``**auto**``, which will let MAME choose the
+ best selection for you.
+
+ * ``d3d9`` -- Direct3D 9.0 Renderer (Requires Windows XP or higher)
+ * ``d3d11`` -- Direct3D 11.0 Renderer (Requires Windows Vista with
+ Direct3D 11 update, or Windows 7 or higher)
+ * ``d3d12`` -- Direct3D 12.0 Renderer (Requires Windows 10 or higher)
+ * ``opengl`` -- OpenGL Renderer (Requires OpenGL drivers, may work better on
+ some video cards, supported on Linux and macOS)
+ * ``gles`` -- OpenGL ES Renderer (Supported with some low-power GPUs)
+ * ``metal`` -- Apple Metal Graphics API (Requires macOS 10.11 El Capitan or
+ newer)
+ * ``vulkan`` -- Vulkan Renderer (Requires Windows or Linux with compatible
+ GPU drivers.
+bgfx_debug
+ Enables BGFX debugging features. Most users will not need to use this.
+bgfx_screen_chains
+ This dictates how to handle BGFX rendering on a per-display basis. Possible
+ choices include ``hlsl``, ``unfiltered``, and ``default``.
+
+ * ``default`` -- **default** bilinear filtered output
+ * ``unfiltered`` -- nearest neighbor sampled output
+ * ``hlsl`` -- display simulation through shaders
+ * ``crt-geom`` -- lightweight CRT simulation
+ * ``crt-geom-deluxe`` -- more detailed CRT simulation
+ * ``lcd-grid`` -- LCD matrix simulation
+
+ We make a distinction between emulated screens (which we’ll call a *screen*)
+ and output windows or monitors (which we’ll call a *window*, set by the
+ ``-numscreens`` option) here. Use colons (:) to separate windows, and
+ commas (,) to separate screens in the ``-bgfx_screen_chains`` setting value.
+
+ For the simple single window, single screen case, such as Pac-Man on one
+ physical PC monitor, you can specify one entry like::
+
+ bgfx_screen_chains hlsl
+
+ Things get only slightly more complicated when we get to multiple windows
+ and multiple screens.
+
+ On a single window, multiple screen game, such as Darius on one physical PC
+ monitor, specify screen chains (one per window) like::
+
+ bgfx_screen_chains hlsl,hlsl,hlsl
+
+ This also works with single screen games where you are mirroring the output
+ to more than one physical display. For instance, you could set up Pac-Man
+ to have one unfiltered output for use with video broadcasting while a second
+ display is set up HLSL for playing on.
+
+ On a multiple window, multiple screen game, such as Darius on three physical
+ PC monitors, specify multiple entries (one per window) like::
+
+ bgfx_screen_chains hlsl:hlsl:hlsl
+
+ Another example game would be Taisen Hot Gimmick, which used two CRTs to
+ show individual player hands to just that player. If using two windows (two
+ physical displays)::
+
+ bgfx_screen_chains hlsl:hlsl
+
+ One more special case is that Nichibutsu had a special cocktail mahjong
+ cabinet that used a CRT in the middle along with two LCD displays to show
+ each player their hand. We would want the LCDs to be unfiltered and
+ untouched as they were, while the CRT would be improved through HLSL. Since
+ we want to give each player their own full screen display (two physical
+ monitors) along with the LCD, we’ll go with::
+
+ -numscreens 2 -view0 "Player 1" -view1 "Player 2" -video bgfx -bgfx_screen_chains hlsl,unfiltered:hlsl,unfiltered
+
+ This sets up the view for each display respectively, keeping HLSL effect on
+ the CRT for each window (physical display) while going unfiltered for the
+ LCD screens.
+
+ If using only one window (one display), keep in mind the game still has
+ three screens, so we would use::
+
+ bgfx_screen_chains hlsl,unfiltered,unfiltered
+
+ Note that the commas are on the outside edges, and any colons are in the
+ middle.
+bgfx_shadow_mask
+ This specifies the shadow mask effect PNG file. By default this is
+ **slot-mask.png**.
Tweaking BGFX HLSL Settings inside MAME
---------------------------------------
-*Warning: Currently BGFX HLSL settings are not saved or loaded from any configuration files. This is expected to change in the future.*
+Start by loading MAME with the game of your choice (e.g. **mame pacman**).
+
+The tilde key (**~**) brings up the on-screen display options. Use up and down
+to go through the various settings, while left and right will allow you to
+change that setting. Results will be shown in real time as you’re changing
+these settings.
+
+Note that settings are individually changeable on a per-screen basis.
+
+BGFX slider settings are saved per-system in CFG files. If the
+``bgfx_screen_chains`` setting has been set (either in an INI file or on the
+command line), it will set the initial effects. If the ``bgfx_screen_chains``
+setting has not been set, MAME will use the effects you chose the last time you
+ran the system.
+
+
+Using the included pillarbox filters
+------------------------------------
+
+MAME includes example BGFX shaders and layouts for filling unused space on a
+16:9 widescreen display with a blurred version of the emulated video. The all
+the necessary files are included, and just need to be enabled.
+
+For systems using 4:3 horizontal monitors, use these options::
+
+ -override_artwork bgfx/border_blur -view Horizontal -bgfx_screen_chains crt-geom,pillarbox_left_horizontal,pillarbox_right_horizontal
-Start by loading MAME with the game of your choice (e.g. **mame pacman**)
+For systems using 3:4 vertical monitors, use these options::
-The tilde key (**~**) brings up the on-screen display options. Use up and down to go through the various settings, while left and right will allow you to change that setting. Results will be shown in real time as you're changing these settings.
+ -override_artwork bgfx/border_blur -view Vertical -bgfx_screen_chains crt-geom,pillarbox_left_vertical,pillarbox_right_vertical
-Note that settings are individually changable on a per-screen basis.
+* You can use a different setting in place of ``crt-geom`` for the effect to
+ apply to the primary screen image in the centre (e.g. ``default``, ``hlsl`` or
+ ``lcd-grid``).
+* If you’ve previously changed the view for the system in MAME, the correct
+ pillarboxed view will not be selected by default. Use the video options menu
+ to select the correct view.
+* You can add these settings to an INI file to have them apply to certain
+ systems automatically (e.g. **horizont.ini** or **vertical.ini**, or the INI
+ file for a specific system).
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst
index f05a3d164b7..7fb531b604c 100644
--- a/docs/source/advanced/ctrlr_config.rst
+++ b/docs/source/advanced/ctrlr_config.rst
@@ -41,8 +41,9 @@ Basic structure
Controller configuration files follow a similar format to the system
configuration files that MAME uses to save things like input settings and
-bookkeeping data. This example shows the overall structure of a controller
-configuration file:
+bookkeeping data (created in the folder specified using the
+:ref:`cfg_directory option <mame-commandline-cfgdirectory>`). This example
+shows the overall structure of a controller configuration file:
.. code-block:: XML
@@ -127,26 +128,26 @@ left and right arrows will be replaced with the numeric 8, 2, 4 and 6 keys on
the numeric keypad, respectively.
Note that substitutions specified using ``remap`` elements only apply to inputs
-that use MAME’s default assignment for the control type. That is, they only
-apply to default assignments for control types set in the “Inputs (general)”
-menu. They *do not* apply to default input assignments set in driver/device I/O
-port definitions (using the ``PORT_CODE`` macro).
+that use MAME’s default assignment for the input type. That is, they only apply
+to default assignments for control types set in the “Input Assignments
+(general)” menus. They *do not* apply to default control assignments set in
+driver/device I/O port definitions (using the ``PORT_CODE`` macro).
MAME applies ``remap`` elements found inside any applicable ``system`` element.
.. _ctrlrcfg-typeoverride:
-Overriding defaults by control type
------------------------------------
+Overriding defaults by input type
+---------------------------------
Use ``port`` elements with ``type`` attributes but without ``tag`` attributes to
-override the default host input assignments for a controls:
+override the default control assignments for emulated inputs by type:
.. code-block:: XML
<input>
- <port type="UI_CONFIGURE">
+ <port type="UI_MENU">
<newseq type="standard">KEYCODE_TAB OR KEYCODE_1 KEYCODE_5</newseq>
</port>
<port type="UI_CANCEL">
@@ -169,7 +170,7 @@ override the default host input assignments for a controls:
This sets the following default input assignments:
-Config Menu (User Interface)
+Show/Hide Menu (User Interface)
Tab key, or 1 and 2 keys pressed simultaneously
UI Cancel (User Interface)
Escape key, or 2 and 6 keys pressed simultaneously
@@ -183,10 +184,10 @@ P1 Button 4 (Player 1 Controls)
X key, or joystick 1 button 4
Note that this will only apply for inputs that use MAME’s default assignment for
-the control type. That is, ``port`` elements without ``tag`` attributes only
-override default assignments for control types set in the “Inputs (general)”
-menu. They *do not* override default input assignments set in driver/device I/O
-port definitions (using the ``PORT_CODE`` macro).
+the input type. That is, ``port`` elements without ``tag`` attributes only
+override default assignments for control types set in the “Input Assignments
+(general)” menus. They *do not* override default control assignments set in
+driver/device I/O port definitions (using the ``PORT_CODE`` macro).
MAME applies ``port`` elements without ``tag`` attributes found inside any
applicable ``system`` element.
@@ -194,22 +195,22 @@ applicable ``system`` element.
.. _ctrlrcfg-ctrloverride:
-Overriding defaults for specific controls
------------------------------------------
+Overriding defaults for specific inputs
+---------------------------------------
Use ``port`` elements with ``tag``, ``type``, ``mask`` and ``defvalue``
-attributes to override defaults for specific controls. These ``port`` elements
+attributes to override defaults for specific inputs. These ``port`` elements
should only occur inside ``system`` elements that apply to particular systems or
source files (i.e. they should not occur inside ``system`` elements where the
-``name`` attribute has the value ``default``). The default host input
-assignments can be overridden, as well as the toggle setting for digital
-controls.
+``name`` attribute has the value ``default``). The default control assignments
+can be overridden, as well as the toggle setting for digital inputs.
The ``tag``, ``type``, ``mask`` and ``defvalue`` are used to identify the
affected input. You can find out the values to use for a particular input by
-changing its assigned host input, exiting MAME, and checking the values in the
-system configuration file. Note that these values are not guaranteed to be
-stable, and may change between MAME versions.
+changing its control assignment, exiting MAME, and checking the values in the
+system configuration file (created in the folder specified using the
+:ref:`cfg_directory option <mame-commandline-cfgdirectory>`). Note that these
+values are not guaranteed to be stable, and may change between MAME versions.
Here’s an example that overrides defaults for 280-ZZZAP:
@@ -225,5 +226,38 @@ Here’s an example that overrides defaults for 280-ZZZAP:
</input>
</system>
-This sets the host inputs to steer left and right to the K and J keys,
+This sets the controls to steer left and right to the K and J keys,
respectively, and disables the toggle setting for the gear shift input.
+
+
+.. _ctrlrcfg-mapdevice:
+
+Assigning input device numbers
+------------------------------
+
+Use ``mapdevice`` elements with ``device`` and ``controller`` attributes to
+assign stable numbers to input devices. Note that all devices explicitly
+configured in this way must be connected when MAME starts for this to work as
+expected.
+
+Set the ``device`` attribute to the device ID of the input device, and set the
+``controller`` attribute to the desired input device token (device type and
+number).
+
+Here’s an example numbering two light guns and two XInput game controllers:
+
+.. code-block:: XML
+
+ <system name="default">
+ <input>
+ <mapdevice device="VID_D209&amp;PID_1601" controller="GUNCODE_1" />
+ <mapdevice device="VID_D209&amp;PID_1602" controller="GUNCODE_2" />
+ <mapdevice device="XInput Player 1" controller="JOYCODE_1" />
+ <mapdevice device="XInput Player 2" controller="JOYCODE_2" />
+ </input>
+ </system>
+
+MAME applies ``mapdevice`` elements found inside the first applicable ``system``
+element only. To avoid confusion, it’s simplest to place the ``system`` element
+applying to all systems (``name`` attribute set to ``default``) first in the
+file, and use it to assign input device numbers.
diff --git a/docs/source/advanced/devicemap.rst b/docs/source/advanced/devicemap.rst
index 38dcc3a2641..9cfd88e6c56 100644
--- a/docs/source/advanced/devicemap.rst
+++ b/docs/source/advanced/devicemap.rst
@@ -1,26 +1,52 @@
+.. _devicemap:
+
Stable Controller IDs
-===============================
+=====================
+
+By default, MAME does not assign stable numbers to input devices. For instance,
+a game pad controller may be assigned to “Joy 1” initially, but after
+restarting, the same game pad may be reassigned to “Joy 3”.
+
+The reason is that MAME assigns numbers to input devices in the based on
+enumeration order. Factors that can cause this to change include disconnecting
+and reconnecting USB or Bluetooth devices, changing ports/hubs, and even just
+restarting the computer. Input device numbers can be quite unpredictable.
-By default, the mapping between devices and controller IDs is not stable. For instance, a gamepad controller may be assigned to "Joy 1" initially, but after a reboot, it may get re-assigned to "Joy 3".
+This is where the ``mapdevice`` configuration setting comes into the picture.
+By adding this setting to a :ref:`controller configuration file <ctrlrcfg>`, you
+can ensure that a given input device is always assigned the same number in MAME.
-The reason is that MAME enumerates attached devices and assigns controller IDs based on the enumeration order. Factors that can cause controller IDs to change include plugging / unplugging USB devices, changing ports / hubs and even system reboots.
-It is quite cumbersome to ensure that controller IDs are always correct.
+Using mapdevice
+---------------
-That's where the "mapdevice" configuration setting comes into the picture. This setting allows you to map a device id to a controller ID, ensuring that the specified device always maps to the same controller ID in MAME.
+The ``mapdevice`` XML element is added to the ``input`` XML element in the
+controller configuration file. It requires two attributes, ``device`` and
+``controller``. Note that ``mapdevice`` elements only take effect in the
+controller configuration file (set using the :ref:`-ctrlr option
+<mame-commandline-ctrlr>`) – they are ignored in system configuration files and
+the default configuration file.
-Usage of mapdevice
-------------------
-The "mapdevice" xml element is specified under the input xml element in the controller configuration file. It requires two attributes, "device" and "controller".
-NOTE: This setting only take effect when added to the **ctrlr** config file.
+The ``device`` attribute specifies the device ID of the input device to match.
+It may also be a substring of the device ID. To obtain the device ID for an
+input device, select it in the :ref:`menus-inputdevices`, and then select **Copy
+Device ID**. The device ID will be copied to the clipboard. You can also see
+input device IDs by turning on verbose logging (more on this later). The format
+of device IDs depends the type of device, selected input provider module and
+operating system. Your input device IDs may look very different to the examples
+here.
-The "device" attribute specifies the id of the device to match. It may also be a substring of the id. To see the list of available devices, enable verbose output and available devices will then be listed to the console at startup (more on this below).
+The ``controller`` attribute specifies the input token for the input device type
+(i.e. ``JOYCODE``, ``GUNCODE``, ``MOUSECODE``) and number to assign to the
+device, separated by an underscore. Numbering starts from 1. For example the
+token for the first joystick device will be ``JOYCODE_1``, the second will be
+``JOYCODE_2``, and so on.
-The "controller" attribute specifies the MAME controller ID. It is made up of a controller class (i.e. ``JOYCODE``, ``GUNCODE``, ``MOUSECODE``) and controller index. For example: ``JOYCODE_1``.
Example
-------
-Here's an example:
+
+Here’s an example:
| <mameconfig version="10">
| <system name="default">
@@ -40,37 +66,68 @@ Here's an example:
In the above example, we have four device mappings specified:
-The first two mapdevice entries map player 1 and 2 lightguns to Gun 1 and Gun 2, respectively. We use a substring of the full raw device names to match each devices. Note that, since this is XML, we needed to escape the ``&`` using ``&amp;``.
+* The first two ``mapdevice`` elements map player 1 and 2 light guns to Gun 1
+ and Gun 2, respectively. We use a substring of the full device IDs to match
+ each devices. Note that, since this is XML, we needed to escape the
+ ampersands (``&``) as ``&amp;``.
+* The last two ``mapdevices`` elements map player 1 and player 2 gamepad
+ controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput
+ game controllers.
-The last two mapdevices entries map player 1 and player 2 gamepad controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput devices.
Listing Available Devices
-------------------------
-How did we obtain the device id's in the above example? Easy!
-Run MAME with -v parameter to enable verbose output. It will then list available devices include the corresponding "device id" to the console.
+There are two ways to obtain device IDs: by copying them from the
+:ref:`menus-inputdevices`, or by :ref:`turning on verbose logging
+<mame-commandline-verbose>` and finding the messages logged when input devices
+are added.
+
+To reach the Input Devices menu from the system selection menu, select **General
+Settings**, and the select **Input Devices**. To reach the input devices menu
+from the :ref:`main menu <menus-main>`, select **Input Settings**, then select
+**Input Devices**. From the Input Devices menu, select a device, then select
+**Copy Device ID** to copy its device ID to the clipboard.
+
+To use verbose logging, run MAME with the ``-v`` or ``-verbose`` option on the
+command line. Search the output for messages starting with “Input: Adding…”
+that show recognised input devices and their respective IDs.
Here an example:
-| Input: Adding Gun #0:
-| Input: Adding Gun #1:
-| Input: Adding Gun #2: HID-compliant mouse (**device id: \\?\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
-| Input: Adding Gun #3: HID-compliant mouse (**device id: \\?\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
-| Input: Adding Gun #4: HID-compliant mouse (**device id: \\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
-| Input: Adding Gun #5: HID-compliant mouse (**device id: \\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
-| Input: Adding Gun #6: HID-compliant mouse (**device id: \\?\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
+| Input: Adding lightgun #1:
+| Input: Adding lightgun #2:
+| Input: Adding lightgun #3: HID-compliant mouse (**device id: \\\\?\\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
+| Input: Adding lightgun #4: HID-compliant mouse (**device id: \\\\?\\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
+| Input: Adding lightgun #5: HID-compliant mouse (**device id: \\\\?\\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
+| Input: Adding lightgun #6: HID-compliant mouse (**device id: \\\\?\\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
+| Input: Adding lightgun #7: HID-compliant mouse (**device id: \\\\?\\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**)
| Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows).
-| Input: Adding Joy #0: ATRAK Device #1 (**device id: ATRAK Device #1**)
+| Input: Adding joystick #1: ATRAK Device #1 (**device id: ATRAK Device #1**)
| Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows).
-| Input: Adding Joy #1: ATRAK Device #2 (**device id: ATRAK Device #2**)
-| Input: Adding Joy #2: XInput Player 1 (**device id: XInput Player 1**)
-| Input: Adding Joy #3: XInput Player 2 (**device id: XInput Player 2**)
+| Input: Adding joystick #2: ATRAK Device #2 (**device id: ATRAK Device #2**)
+| Input: Adding joystick #3: XInput Player 1 (**device id: XInput Player 1**)
+| Input: Adding joystick #4: XInput Player 2 (**device id: XInput Player 2**)
|
-Furthermore, when devices are mapped using mapdevice, you'll see that in the verbose logging too, such as:
+Furthermore, when devices are reassigned using ``mapdevice`` elements in the
+controller configuration file, you’ll see that in the verbose log output, too,
+such as:
-| Input: Remapped Gun #0: HID-compliant mouse (device id: \\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
-| Input: Remapped Gun #1: HID-compliant mouse (device id: \\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
-| Input: Remapped Joy #0: XInput Player 1 (device id: XInput Player 1)
-| Input: Remapped Joy #1: XInput Player 2 (device id: XInput Player 2)
+| Input: Remapped lightgun #1: HID-compliant mouse (device id: \\\\?\\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Input: Remapped lightgun #2: HID-compliant mouse (device id: \\\\?\\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd})
+| Input: Remapped joystick #1: XInput Player 1 (device id: XInput Player 1)
+| Input: Remapped joystick #2: XInput Player 2 (device id: XInput Player 2)
|
+
+
+Limitations
+-----------
+
+You can only assign stable numbers to devices if MAME receives stable, unique
+device IDs from the input device provider and operating system. This is not
+always the case. For example the SDL joystick provider is not capable of
+providing unique IDs for many USB game controllers.
+
+If not all configured devices are connected when MAME starts, the devices that
+are connected may not be numbered as expected.
diff --git a/docs/source/advanced/hlsl.rst b/docs/source/advanced/hlsl.rst
index 3e22203df78..218e3be0564 100644
--- a/docs/source/advanced/hlsl.rst
+++ b/docs/source/advanced/hlsl.rst
@@ -129,7 +129,7 @@ Configuration Settings
|
| **cubic_distortion** (*Cubic Distortion Amount*)
|
-| This setting determines strength of the qubic distortion of the screen image.
+| This setting determines strength of the cubic distortion of the screen image.
|
| Both distortion factors can be negative to compensate each other. e.g. distortion 0.5 and cubic_distortion -0.5
|
diff --git a/docs/source/advanced/multiconfig.rst b/docs/source/advanced/multiconfig.rst
index abae10f5a78..d81853d4734 100644
--- a/docs/source/advanced/multiconfig.rst
+++ b/docs/source/advanced/multiconfig.rst
@@ -27,12 +27,7 @@ Order of Config Loading
Systems with no monitors, multiple monitors with different orientations, or
monitors connected to slot devices will usually load ``horizont.ini``.
-5. System type INI file (``arcade.ini``, ``console.ini``, ``computer.ini``, or
- ``othersys.ini``). Both Pac-Man and Street Fighter Alpha are arcade games,
- so ``arcade.ini`` will be loaded here, while Atari 2600 will load
- ``console.ini`` as it is a home game console.
-
-6. Monitor type INI file (``vector.ini`` for vector monitors, ``raster.ini`` for
+5. Monitor type INI file (``vector.ini`` for vector monitors, ``raster.ini`` for
CRT raster monitors, or ``lcd.ini`` for LCD/EL/plasma matrix monitors).
Pac-Man and Street Fighter Alpha use raster CRTs, so ``raster.ini`` is loaded
here, while Tempest uses a vector monitor, so ``vector.ini`` is loaded here.
@@ -43,7 +38,7 @@ Order of Config Loading
monitors or with other kinds of monitors will not load an INI file for this
step.
-7. Driver source file INI file. MAME will attempt to load
+6. Driver source file INI file. MAME will attempt to load
``source/``\ *<sourcefile>*\ ``.ini`` where *<sourcefile>* is the base name
of the source code file where the system driver is defined. A system's
source file can be found using **mame -listsource <pattern>** at the command
@@ -54,16 +49,16 @@ Order of Config Loading
``cave.cpp`` source file, so they will all load ``source/cave.ini`` at this
step.
-8. BIOS set INI file (if applicable). For example The Last Soldier uses the
+7. BIOS set INI file (if applicable). For example The Last Soldier uses the
Neo-Geo MVS BIOS, so it will load ``neogeo.ini``. Systems that don't use a
BIOS set won't load an INI file for this step.
-9. Parent system INI file. For example The Last Soldier is a clone of The Last
+8. Parent system INI file. For example The Last Soldier is a clone of The Last
Blade / Bakumatsu Roman - Gekka no Kenshi, so it will load ``lastblad.ini``.
Parent systems will not load an INI file for this step.
-10. System INI file. Using the previous example, The Last Soldier will load
- ``lastsold.ini``.
+9. System INI file. Using the previous example, The Last Soldier will load
+ ``lastsold.ini``.
Examples of Config Loading Order
@@ -75,12 +70,11 @@ Examples of Config Loading Order
2. ``mame.ini`` (global)
3. (debugger not enabled, no extra INI file loaded)
4. ``vertical.ini`` (screen orientation)
- 5. ``arcade.ini`` (system type)
- 6. ``raster.ini`` (monitor type)
- 7. ``source/jack.ini`` (driver source file)
- 8. (no BIOS set)
- 9. ``zzyzzyxx.ini`` (parent system)
- 10. ``brix.ini`` (system)
+ 5. ``raster.ini`` (monitor type)
+ 6. ``source/jack.ini`` (driver source file)
+ 7. (no BIOS set)
+ 8. ``zzyzzyxx.ini`` (parent system)
+ 9. ``brix.ini`` (system)
* Super Street Fighter 2 Turbo (**mame ssf2t**)
@@ -88,12 +82,11 @@ Examples of Config Loading Order
2. ``mame.ini`` (global)
3. (debugger not enabled, no extra INI file loaded)
4. ``horizont.ini`` (screen orientation)
- 5. ``arcade.ini`` (system type)
- 6. ``raster.ini`` (monitor type)
- 7. ``source/cps2.ini`` (driver source file)
- 8. (no BIOS set)
- 9. (no parent system)
- 10. ``ssf2t.ini`` (system)
+ 5. ``raster.ini`` (monitor type)
+ 6. ``source/cps2.ini`` (driver source file)
+ 7. (no BIOS set)
+ 8. (no parent system)
+ 9. ``ssf2t.ini`` (system)
* Final Arch (**mame finlarch**)
@@ -101,12 +94,11 @@ Examples of Config Loading Order
2. ``mame.ini`` (global)
3. (debugger not enabled, no extra INI file loaded)
4. ``horizont.ini`` (screen orientation)
- 5. ``arcade.ini`` (system type)
- 6. ``raster.ini`` (monitor type)
- 7. ``source/stv.ini`` (driver source file)
- 8. ``stvbios.ini`` (BIOS set)
- 9. ``smleague.ini`` (parent system)
- 10. ``finlarch.ini`` (system)
+ 5. ``raster.ini`` (monitor type)
+ 6. ``source/stv.ini`` (driver source file)
+ 7. ``stvbios.ini`` (BIOS set)
+ 8. ``smleague.ini`` (parent system)
+ 9. ``finlarch.ini`` (system)
*Remember command line parameters take precedence over all else!*
@@ -118,5 +110,3 @@ Some users may have a wall-mounted or otherwise rotatable monitor, and may wish
to actually play vertical games with the rotated display. The easiest way to
accomplish this is to put your rotation modifiers into ``vertical.ini``, where
they will only affect vertical games.
-
-[todo: more practical examples]
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index 3f008300f04..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.
+
+ The default is ``auto`` which will use ``taptun`` if available, falling back
+ to ``pcap``.
+
+Example:
+ .. code-block:: bash
+
+ mame -networkprovider pcap apple2ee -sl3 uthernet
-.. Tip:: On Windows, winhybrid is likely to give the best experience by
- supporting both XInput and DirectInput controllers.
+.. _mame-commandline-cliverbs:
-OSD CLI Options
----------------
+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,9 +1369,11 @@ 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,8 +1498,10 @@ 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
---------------------------
@@ -1533,7 +1674,7 @@ Core State/Playback Options
Example:
.. code-block:: bash
- mame pacman -wavewrite pacsounds
+ mame pacman -wavwrite pacsounds
.. _mame-commandline-snapname:
@@ -1706,6 +1847,8 @@ Core State/Playback Options
mame neogeo -burnin
+.. _mame-commandline-perf:
+
Core Performance Options
------------------------
@@ -1762,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
@@ -1862,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)
@@ -1878,6 +2021,8 @@ Core Performance Options
mame bgaregga -lowlatency
+.. _mame-commandline-rotation:
+
Core Rotation Options
---------------------
@@ -1978,6 +2123,8 @@ Core Rotation Options
mame -flipy suprmrio
+.. _mame-commandline-videooptions:
+
Core Video Options
------------------
@@ -1990,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
@@ -2187,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:
@@ -2222,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**)
@@ -2232,6 +2379,8 @@ Core Video Options
mame dkong -nounevenstretch
+.. _mame-commandline-fullscreen:
+
Core Full Screen Options
------------------------
@@ -2257,6 +2406,8 @@ Core Full Screen Options
mame kof97 -video d3d -switchres -resolution 1280x1024
+.. _mame-commandline-windowoptions:
+
Core Per-Window Options
-----------------------
@@ -2422,6 +2573,8 @@ Core Per-Window Options
mame contra -view native
+.. _mame-commandline-artwork:
+
Core Artwork Options
--------------------
@@ -2475,6 +2628,8 @@ Core Artwork Options
mame galaga -override_artwork puckman
+.. _mame-commandline-screenoptions:
+
Core Screen Options
-------------------
@@ -2569,6 +2724,8 @@ Core Screen Options
mame pacman -effect scanlines
+.. _mame-commandline-vectoroptions:
+
Core Vector Options
-------------------
@@ -2649,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
@@ -2693,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
@@ -2735,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.
@@ -2756,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:
@@ -2765,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
------------------
@@ -2828,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
@@ -2904,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
@@ -2916,6 +3068,8 @@ Core Sound Options
mame galaga -audio_latency 1
+.. _mame-commandline-inputoptions:
+
Core Input Options
------------------
@@ -2961,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**).
@@ -2974,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:
@@ -2991,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**).
@@ -3134,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:
@@ -3193,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:
@@ -3225,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:
@@ -3254,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**)
@@ -3270,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
@@ -3290,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.
@@ -3317,6 +3519,8 @@ Core Input Options
mame contra -coin_impulse 1
+.. _mame-commandline-inputenable:
+
Core Input Automatic Enable Options
-----------------------------------
@@ -3352,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
-----------------
@@ -3570,6 +3787,8 @@ Debugging Options
mame marble -debug -debugger_font "Comic Sans MS" -debugger_font_size 16
+.. _mame-commandline-commoptions:
+
Core Communication Options
--------------------------
@@ -3645,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
-----------------
@@ -3663,7 +3884,7 @@ Core Misc Options
.. _mame-commandline-drcusec:
-**\-drc_use_c**
+**\-[no]drc_use_c**
Force DRC to use the C code backend.
@@ -3676,7 +3897,7 @@ Core Misc Options
.. _mame-commandline-drcloguml:
-**\-drc_log_uml**
+**\-[no]drc_log_uml**
Write DRC UML disassembly log.
@@ -3689,7 +3910,7 @@ Core Misc Options
.. _mame-commandline-drclognative:
-**\-drc_log_native**
+**\-[no]drc_log_native**
Write DRC native disassembly log.
@@ -3705,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``.
@@ -3768,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
@@ -3788,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.
@@ -3802,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:
@@ -3841,6 +4062,8 @@ Core Misc Options
mame galaga88 -nonvram_save
+.. _mame-commandline-scripting:
+
Scripting Options
-----------------
@@ -3849,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.
@@ -3930,8 +4153,11 @@ Scripting Options
mame alcon -noplugin cheat
+.. _mame-commandline-webserver:
+
HTTP Server Options
-------------------
+
.. _mame-commandline-http:
**-[no]http**
@@ -3969,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*
@@ -4031,7 +4259,7 @@ PortAudio Options
mame suprmrio -sound portaudio -pa_api "Windows WASAPI"
-.. _mame-commandline-pa-device:
+.. _mame-commandline-padevice:
**-pa_device** *device*
@@ -4045,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*
diff --git a/docs/source/commandline/commandline-index.rst b/docs/source/commandline/commandline-index.rst
index b0cd9a51170..50500066d6f 100644
--- a/docs/source/commandline/commandline-index.rst
+++ b/docs/source/commandline/commandline-index.rst
@@ -1,33 +1,36 @@
.. _index-commandline:
-Commandline Index
-=================
+Command-line Index
+==================
-This is a complete index of all commandline options and commands for MAME, suitable for quickly finding a given command.
+This is a complete index of all command-line options and verbs for MAME,
+suitable for quickly finding a given option.
-Universal Commandline Options
------------------------------
-This section contains configuration options that are applicable to *all* MAME sub-builds (both SDL and Windows native).
+Universal Command-line Options
+------------------------------
+This section contains configuration options that are applicable to *all* MAME
+configurations (including both SDL and Windows native).
-Core Commands
-~~~~~~~~~~~~~
+
+Core Verbs
+~~~~~~~~~~
| :ref:`help <mame-commandline-help>`
| :ref:`validate <mame-commandline-validate>`
-Configuration Commands
-~~~~~~~~~~~~~~~~~~~~~~
+Configuration Verbs
+~~~~~~~~~~~~~~~~~~~
| :ref:`createconfig <mame-commandline-createconfig>`
| :ref:`showconfig <mame-commandline-showconfig>`
| :ref:`showusage <mame-commandline-showusage>`
-Frontend Commands
-~~~~~~~~~~~~~~~~~
+Frontend Verbs
+~~~~~~~~~~~~~~
| :ref:`listxml <mame-commandline-listxml>`
| :ref:`listfull <mame-commandline-listfull>`
@@ -36,6 +39,7 @@ Frontend Commands
| :ref:`listbrothers <mame-commandline-listbrothers>`
| :ref:`listcrc <mame-commandline-listcrc>`
| :ref:`listroms <mame-commandline-listroms>`
+| :ref:`listbios <mame-commandline-listbios>`
| :ref:`listsamples <mame-commandline-listsamples>`
| :ref:`verifyroms <mame-commandline-verifyroms>`
| :ref:`verifysamples <mame-commandline-verifysamples>`
@@ -53,15 +57,19 @@ OSD-related Options
~~~~~~~~~~~~~~~~~~~
| :ref:`uimodekey <mame-commandline-uimodekey>`
+| :ref:`controller_map <mame-commandline-controllermap>`
+| :ref:`background_input <mame-commandline-backgroundinput>`
| :ref:`uifontprovider <mame-commandline-uifontprovider>`
| :ref:`keyboardprovider <mame-commandline-keyboardprovider>`
| :ref:`mouseprovider <mame-commandline-mouseprovider>`
| :ref:`lightgunprovider <mame-commandline-lightgunprovider>`
| :ref:`joystickprovider <mame-commandline-joystickprovider>`
+| :ref:`midiprovider <mame-commandline-midiprovider>`
+| :ref:`networkprovider <mame-commandline-networkprovider>`
-OSD CLI Options
-~~~~~~~~~~~~~~~
+OSD CLI Verbs
+~~~~~~~~~~~~~
| :ref:`listmidi <mame-commandline-listmidi>`
| :ref:`listnetwork <mame-commandline-listnetwork>`
@@ -117,9 +125,8 @@ Core State/Playback Options
| :ref:`state <mame-commandline-state>`
| :ref:`[no]autosave <mame-commandline-noautosave>`
| :ref:`playback <mame-commandline-playback>`
-| :ref:`exit_after_playback <mame-commandline-exitafterplayback>`
+| :ref:`[no]exit_after_playback <mame-commandline-exitafterplayback>`
| :ref:`record <mame-commandline-record>`
-| :ref:`record_timecode <mame-commandline-recordtimecode>`
| :ref:`mngwrite <mame-commandline-mngwrite>`
| :ref:`aviwrite <mame-commandline-aviwrite>`
| :ref:`wavwrite <mame-commandline-wavwrite>`
@@ -143,7 +150,7 @@ Core Performance Options
| :ref:`[no]refreshspeed <mame-commandline-norefreshspeed>`
| :ref:`numprocessors <mame-commandline-numprocessors>`
| :ref:`bench <mame-commandline-bench>`
-| :ref:`lowlatency <mame-commandline-lowlatency>`
+| :ref:`[no]lowlatency <mame-commandline-lowlatency>`
Core Rotation Options
@@ -212,6 +219,7 @@ Core Vector Options
| :ref:`beam_width_min <mame-commandline-beamwidthmin>`
| :ref:`beam_width_max <mame-commandline-beamwidthmax>`
| :ref:`beam_intensity_weight <mame-commandline-beamintensityweight>`
+| :ref:`beam_dot_size <mame-commandline-beamdotsize>`
| :ref:`flicker <mame-commandline-flicker>`
@@ -227,11 +235,10 @@ Core Video OpenGL Debugging Options
Core Video OpenGL GLSL Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-| :ref:`gl_glsl <mame-commandline-glglsl>`
+| :ref:`[no]gl_glsl <mame-commandline-glglsl>`
| :ref:`gl_glsl_filter <mame-commandline-glglslfilter>`
| :ref:`glsl_shader_mame[0-9] <mame-commandline-glslshadermame>`
| :ref:`glsl_shader_screen[0-9] <mame-commandline-glslshaderscreen>`
-| :ref:`gl_glsl_vid_attr <mame-commandline-glglslvidattr>`
Core Sound Options
@@ -261,8 +268,9 @@ Core Input Options
| :ref:`joystick_map <mame-commandline-joystickmap>`
| :ref:`joystick_deadzone <mame-commandline-joystickdeadzone>`
| :ref:`joystick_saturation <mame-commandline-joysticksaturation>`
-| :ref:`natural <mame-commandline-natural>`
-| :ref:`joystick_contradictory <mame-commandline-joystickcontradictory>`
+| :ref:`joystick_threshold <mame-commandline-joystickthreshold>`
+| :ref:`[no]natural <mame-commandline-natural>`
+| :ref:`[no]joystick_contradictory <mame-commandline-joystickcontradictory>`
| :ref:`coin_impulse <mame-commandline-coinimpulse>`
@@ -286,9 +294,11 @@ Core Debugging Options
| :ref:`[no]oslog <mame-commandline-oslog>`
| :ref:`[no]log <mame-commandline-log>`
| :ref:`[no]debug <mame-commandline-debug>`
+| :ref:`debugger <mame-commandline-debugger>`
| :ref:`debugscript <mame-commandline-debugscript>`
| :ref:`[no]update_in_pause <mame-commandline-updateinpause>`
| :ref:`watchdog <mame-commandline-watchdog>`
+| :ref:`debugger_port <mame-commandline-debuggerport>`
| :ref:`debugger_font <mame-commandline-debuggerfont>`
| :ref:`debugger_font_size <mame-commandline-debuggerfontsize>`
@@ -307,23 +317,23 @@ Core Misc Options
~~~~~~~~~~~~~~~~~
| :ref:`[no]drc <mame-commandline-drc>`
-| :ref:`drc_use_c <mame-commandline-drcusec>`
-| :ref:`drc_log_uml <mame-commandline-drcloguml>`
-| :ref:`drc_log_native <mame-commandline-drclognative>`
+| :ref:`[no]drc_use_c <mame-commandline-drcusec>`
+| :ref:`[no]drc_log_uml <mame-commandline-drcloguml>`
+| :ref:`[no]drc_log_native <mame-commandline-drclognative>`
| :ref:`bios <mame-commandline-bios>`
| :ref:`[no]cheat <mame-commandline-cheat>`
| :ref:`[no]skip_gameinfo <mame-commandline-skipgameinfo>`
| :ref:`uifont <mame-commandline-uifont>`
| :ref:`ui <mame-commandline-ui>`
| :ref:`ramsize <mame-commandline-ramsize>`
-| :ref:`confirm_quit <mame-commandline-confirmquit>`
-| :ref:`ui_mouse <mame-commandline-uimouse>`
+| :ref:`[no]confirm_quit <mame-commandline-confirmquit>`
+| :ref:`[no]ui_mouse <mame-commandline-uimouse>`
| :ref:`language <mame-commandline-language>`
| :ref:`[no]nvram_save <mame-commandline-nvramsave>`
Scripting Options
------------------
+~~~~~~~~~~~~~~~~~
| :ref:`autoboot_command <mame-commandline-autobootcommand>`
| :ref:`autoboot_delay <mame-commandline-autobootdelay>`
@@ -335,15 +345,26 @@ Scripting Options
HTTP Server Options
--------------------
+~~~~~~~~~~~~~~~~~~~
| :ref:`http <mame-commandline-http>`
| :ref:`http_port <mame-commandline-httpport>`
| :ref:`http_root <mame-commandline-httproot>`
-Windows-Specific Commandline Options
-------------------------------------
+PortAudio Options
+~~~~~~~~~~~~~~~~~
+
+| :ref:`pa_api <mame-commandline-paapi>`
+| :ref:`pa_device <mame-commandline-padevice>`
+| :ref:`pa_latency <mame-commandline-palatency>`
+
+
+Windows-Specific Command-line Options
+-------------------------------------
+
+This section contains configuration options that are specific to the native
+(non-SDL) Windows version of MAME.
Windows Performance Options
@@ -368,16 +389,18 @@ Windows Input Device Options
| :ref:`[no]dual_lightgun <mame-wcommandline-duallightgun>`
-SDL-Specific Commandline Options
---------------------------------
-This section contains configuration options that are specific to any build supported by SDL (including Windows where compiled as SDL instead of native).
+SDL-Specific Command-line Options
+---------------------------------
+
+This section contains configuration options that are specific to any build
+supported by SDL (including Windows when built with SDL instead of native).
SDL Performance Options
~~~~~~~~~~~~~~~~~~~~~~~
-| :ref:`sdlvideofps <mame-scommandline-sdlvideofps>`
+| :ref:`[no]sdlvideofps <mame-scommandline-sdlvideofps>`
SDL Video Options
@@ -403,10 +426,15 @@ SDL Keyboard Mapping
SDL Joystick Mapping
~~~~~~~~~~~~~~~~~~~~
-| :ref:`joyidx <mame-scommandline-joyidx>`
| :ref:`sixaxis <mame-scommandline-sixaxis>`
+SDL Lightgun Mapping
+~~~~~~~~~~~~~~~~~~~~
+
+| :ref:`lightgun_index <mame-scommandline-lightgunindex>`
+
+
SDL Low-level Driver Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/source/commandline/index.rst b/docs/source/commandline/index.rst
index 4237c7f30f4..a03fe113708 100644
--- a/docs/source/commandline/index.rst
+++ b/docs/source/commandline/index.rst
@@ -1,11 +1,11 @@
-MAME Commandline Usage and OS-Specific Configuration
-----------------------------------------------------
+MAME Command-line Usage and OS-Specific Configuration
+-----------------------------------------------------
.. toctree::
- :titlesonly:
+ :titlesonly:
- commandline-all
- windowsconfig
- sdlconfig
+ commandline-all
+ windowsconfig
+ sdlconfig
- commandline-index
+ commandline-index
diff --git a/docs/source/commandline/sdlconfig.rst b/docs/source/commandline/sdlconfig.rst
index 0da5f4c526e..eea4b959e60 100644
--- a/docs/source/commandline/sdlconfig.rst
+++ b/docs/source/commandline/sdlconfig.rst
@@ -1,8 +1,8 @@
-SDL-Specific Commandline Options
-================================
+SDL-Specific Command-line Options
+=================================
-
-This section contains configuration options that are specific to any build supported by SDL (including Windows where compiled as SDL instead of native).
+This section contains configuration options that are specific to any build
+supported by SDL (including Windows when built with SDL instead of native).
@@ -11,9 +11,11 @@ Performance Options
.. _mame-scommandline-sdlvideofps:
-**-sdlvideofps**
+**-[no]sdlvideofps**
- Enable output of benchmark data on the SDL video subsystem, including your system's video driver, X server (if applicable), and OpenGL stack in **-video opengl** mode.
+ Enable output of benchmark data on the SDL video subsystem, including your
+ system’s video driver, X server (if applicable), and OpenGL stack in
+ **-video opengl** mode.
Video Options
@@ -23,13 +25,13 @@ Video Options
**-[no]centerh**
- Center horizontally within the view area. Default is ON (**-centerh**).
+ Center horizontally within the view area. Default is ON (**-centerh**).
.. _mame-scommandline-centerv:
**-[no]centerv**
- Center vertically within the view area. Default is ON (**-centerv**).
+ Center vertically within the view area. Default is ON (**-centerv**).
Video Soft-Specific Options
@@ -39,7 +41,8 @@ Video Soft-Specific Options
**-scalemode**
- Scale mode: none, async, yv12, yuy2, yv12x2, yuy2x2 (**-video soft** only). Default is *none*.
+ Scale mode: none, async, yv12, yuy2, yv12x2, yuy2x2 (**-video soft** only).
+ Default is *none*.
SDL Keyboard Mapping
@@ -49,54 +52,59 @@ SDL Keyboard Mapping
**-keymap**
- Enable keymap. Default is OFF (**-nokeymap**)
+ Enable keymap. Default is OFF (**-nokeymap**)
.. _mame-scommandline-keymapfile:
**-keymap_file** *<file>*
- Keymap Filename. Default is ``keymap.dat``.
+ Keymap file name. Default is ``keymap.dat``.
SDL Joystick Mapping
--------------------
-.. _mame-scommandline-joyidx:
+.. _mame-scommandline-sixaxis:
-|
-| **-joy_idx1** *<name>*
-| **-joy_idx2** *<name>*
-| ...
-| **-joy_idx8** *<name>*
-|
+**-sixaxis**
-Name of joystick mapped to a given joystick slot, default is *auto*.
+ Use special handling for PlayStation 3 SixAxis controllers. May cause
+ undesirable behaviour with other controllers. Only affects the ``sdljoy``
+ joystick provider. Default is OFF (**-nosixaxis**)
-.. _mame-scommandline-sixaxis:
+SDL Lightgun Mapping
+--------------------
-**-sixaxis**
+.. _mame-scommandline-lightgunindex:
+
+|
+| **-lightgun_index1** *<name>*
+| **-lightgun_index2** *<name>*
+| ...
+| **-lightgun_index8** *<name>*
+|
- Use special handling for PS3 SixAxis controllers. Default is OFF (**-nosixaxis**)
+Device name or ID mapped to a given lightgun slot.
SDL Low-level Driver Options
-~---------------------------
+----------------------------
.. _mame-scommandline-videodriver:
**-videodriver** *<driver>*
- SDL video driver to use ('x11', 'directfb', ... or '*auto*' for SDL default)
+ SDL video driver to use ('x11', 'directfb', ... or '*auto*' for SDL default)
.. _mame-scommandline-audiodriver:
**-audiodriver** *<driver>*
- SDL audio driver to use ('alsa', 'arts', ... or '*auto*' for SDL default)
+ SDL audio driver to use ('alsa', 'arts', ... or '*auto*' for SDL default)
.. _mame-scommandline-gllib:
**-gl_lib** *<driver>*
- Alternative **libGL.so** to use; '*auto*' for system default
+ Alternative **libGL.so** to use; '*auto*' for system default
diff --git a/docs/source/commandline/windowsconfig.rst b/docs/source/commandline/windowsconfig.rst
index 85f555e9a21..1c41476854c 100644
--- a/docs/source/commandline/windowsconfig.rst
+++ b/docs/source/commandline/windowsconfig.rst
@@ -1,7 +1,8 @@
-Windows-Specific Commandline Options
-====================================
+Windows-Specific Command-line Options
+=====================================
-This section contains configuration options that are specific to the native (non-SDL) Windows version of MAME.
+This section contains configuration options that are specific to the native
+(non-SDL) Windows version of MAME.
@@ -12,7 +13,10 @@ Performance options
**-priority** *<priority>*
- Sets the thread priority for the MAME threads. By default the priority is left alone to guarantee proper cooperation with other applications. The valid range is -15 to 1, with 1 being the highest priority. The default is *0* (*NORMAL priority*).
+ Sets the thread priority for the MAME threads. By default the priority is
+ left alone to guarantee proper cooperation with other applications. The
+ valid range is -15 to 1, with 1 being the highest priority. The default is
+ *0* (*NORMAL priority*).
.. _mame-wcommandline-profile:
@@ -28,25 +32,46 @@ Full screen options
**-[no]triplebuffer** / **-[no]tb**
- Enables or disables "triple buffering". Normally, MAME just draws directly to the screen, without any fancy buffering. But with this option enabled, MAME creates three buffers to draw to, and cycles between them in order. It attempts to keep things flowing such that one buffer is currently displayed, the second buffer is waiting to be displayed, and the third buffer is being drawn to. **-triplebuffer** will override **-waitvsync**, if the buffer is successfully created. This option does not work with **-video gdi**. The default is OFF (**-notriplebuffer**).
+ Enables or disables “triple buffering”. Normally, MAME just draws directly
+ to the screen, without any fancy buffering. But with this option enabled,
+ MAME creates three buffers to draw to, and cycles between them in order. It
+ attempts to keep things flowing such that one buffer is currently displayed,
+ the second buffer is waiting to be displayed, and the third buffer is being
+ drawn to. **-triplebuffer** will override **-waitvsync**, if the buffer is
+ successfully created. This option does not work with **-video gdi**. The
+ default is OFF (**-notriplebuffer**).
.. _mame-wcommandline-fullscreenbrightness:
**-full_screen_brightness** *<value>* / **-fsb** *<value>*
- Controls the brightness, or black level, of the entire display. The standard 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. Note that not all video cards have hardware to support this option. This option does not work with **-video gdi**. The default is ``1.0``.
+ Controls the brightness, or black level, of the entire display. The
+ standard value is 1.0. Lower values (down to 0.1) will produce a darkened
+ display, while higher values (up to 2.0) will give a brighter display. Note
+ that not all video cards have hardware to support this option. This option
+ does not work with **-video gdi**. The default is *1.0*.
.. _mame-wcommandline-fullscreencontrast:
**-full_screen_contrast** *<value>* / **-fsc** *<value>*
- Controls the contrast, or white level, of the entire display. 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. Note that not all video cards have hardware to support this option. This option does not work with **-video gdi**. The default is ``1.0``.
+ Controls the contrast, or white level, of the entire display. The standard
+ value is 1.0. Lower values (down to 0.1) will produce a dimmer display,
+ while higher values (up to 2.0) will give a more saturated display. Note
+ that not all video cards have hardware to support this option. This option
+ does not work with **-video gdi**. The default is *1.0*.
.. _mame-wcommandline-fullscreengamma:
**-full_screen_gamma** *<value>* / **-fsg** *<value>*
- Controls the gamma, which produces a potentially nonlinear black to white ramp, for the entire display. 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. Note that not all video cards have hardware to support this option. This option does not work with **-video gdi**. The default is ``1.0``.
+ Controls the gamma, which produces a potentially nonlinear black to white
+ ramp, for the entire display. The standard value is 1.0, which gives a
+ linear ramp from black to white. Lower values (down to 0.1) will increase
+ the nonlinearity toward black, while higher values (up to 3.0) will push the
+ nonlinearity toward white. Note that not all video cards have hardware to
+ support this option. This option does not work with **-video gdi**. The
+ default is *1.0*.
@@ -57,4 +82,20 @@ Input device options
**-[no]dual_lightgun** / **-[no]dual**
- Controls whether or not MAME attempts to track two lightguns connected at the same time. This option requires -lightgun. This option is a hack for supporting certain older dual lightgun setups. If you have multiple lightguns connected, you will probably just need to enable -mouse and configure each lightgun independently. The default is *OFF* (**-nodual_lightgun**).
+ Controls whether or not MAME attempts to track two lightguns that appear as
+ a single mouse. This option requires the :ref:`lightgun option
+ <mame-commandline-nolightgun>` to be on and the :ref:`lightgunprovider
+ option <mame-commandline-lightgunprovider>` to be set to *win32*.
+
+ This option supports certain older dual lightgun setups that work by setting
+ the mouse pointer location at the moment a lightgun trigger is activated.
+ The primary and secondary triggers on the first lightgun correspond to the
+ first and second mouse buttons, and the primary and secondary triggers on
+ the second lightgun correspond to the third and fourth mouse buttons.
+
+ If you have multiple lightguns connected, you will probably just need to
+ enable the :ref:`lightgun option <mame-commandline-nolightgun>`, use the
+ default :ref:`lightgunprovider option <mame-commandline-lightgunprovider>`
+ of *rawinput*, and configure each lightgun individually.
+
+ The default is OFF (**-nodual_lightgun**).
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 95dc1d19bbf..3ab96db14b5 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -56,16 +56,16 @@ master_doc = 'index'
# General information about the project.
project = u'MAME Documentation'
-copyright = u'1997-2021, MAMEdev and contributors'
+copyright = u'1997-2024, MAMEdev and contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '0.238'
+version = '0.264'
# The full version, including alpha/beta/rc tags.
-release = '0.238'
+release = '0.264'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/source/contributing/cxx.rst b/docs/source/contributing/cxx.rst
new file mode 100644
index 00000000000..918c72032d2
--- /dev/null
+++ b/docs/source/contributing/cxx.rst
@@ -0,0 +1,573 @@
+.. _contributing-cxx:
+
+C++ Coding Guidelines
+=====================
+
+.. contents:: :local:
+
+
+.. _contributing-cxx-intro:
+
+Introduction
+------------
+
+**In terms of coding conventions, the style present within an existing
+source file should be favoured over the standards found below.**
+
+When a new source file is being created, the following coding
+conventions should be observed if creating a new file within the MAME
+core (``src/emu`` and ``src/lib``). If the source file is outside the
+core, deference can be given to a contributor’s preferred style,
+although it is strongly encouraged to code with the understanding that
+the file may need to be comprehensible by more than one person as time
+marches forward.
+
+
+.. _contributing-cxx-definitions:
+
+Definitions
+-----------
+
+Snake case
+ All lowercase letters with words separated by underscores:
+ ``this_is_snake_case``
+Screaming snake case
+ All uppercase letters with words separated by underscores:
+ ``SCREAMING_SNAKE_CASE``
+Camel case:
+ Lowercase initial letter, first letter of each subsequent word
+ capitalised, with no separators between words: ``exampleCamelCase``
+Llama case:
+ Uppercase initial letter, first letter of each subsequent word
+ capitalised, with no separators between words: ``LlamaCaseSample``
+
+
+.. _contributing-cxx-fileformat:
+
+Source file format
+------------------
+
+MAME C++ source files are encoded as UTF-8 text, assuming fixed-width
+characters, with tab stops at four-space intervals. Source files should
+end with a terminating end-of-line. Any valid printable Unicode text is
+permitted in comments. Outside comments and strings, only the printable
+ASCII subset of Unicode is permitted.
+
+The ``srcclean`` tool is used to enforce file format rules before each
+release. You can build this tool and apply it to the files you modify
+before opening a pull request to avoid conflicts or surprising changes
+later.
+
+
+.. _contributing-cxx-naming:
+
+Naming conventions
+------------------
+
+Preprocessor macros
+ Macro names should use screaming snake case. Macros are always
+ global and name conflicts can cause confusing errors – think
+ carefully about what macros really need to be in headers and name
+ them carefully.
+Include guards
+ Include guard macros should begin with ``MAME_``, and end with a
+ capitalised version of the file name, with separators replaced by
+ underscores.
+Constants
+ Constants should use screaming snake case, whether they are constant
+ globals, constant data members, enumerators or preprocessor
+ constants.
+Functions
+ Free functions names should use snake case. (There are some utility
+ function that were previously implemented as preprocessor macros
+ that still use screaming snake case.)
+Classes
+ Class names should use snake case. Abstract class names should end
+ in ``_base``. Public member functions (including static member
+ functions) should use snake case.
+Device classes
+ Concrete driver ``driver_device`` implementation names
+ conventionally end in ``_state``, while other concrete device class
+ names end in ``_device``. Concrete ``device_interface`` names
+ conventionally begin with ``device_`` and end with ``_interface``.
+Device types
+ Device types should use screaming snake case. Remember that device
+ types are names in the global namespace, so choose explicit,
+ unambiguous names.
+Enumerations
+ The enumeration name should use snake case. The enumerators should
+ use screaming snake case.
+Template parameters
+ Template parameters should use llama case (both type and value
+ parameters).
+
+Identifiers containing two consecutive underscores or starting with an
+underscore followed by an uppercase letter are always reserved and
+should not be used.
+
+Type names and other identifiers with a leading underscore should be
+avoided within the global namespace, as they are explicitly reserved
+according to the C++ standard. Additionally, identifiers suffixed with
+``_t`` should be avoided within the global namespace, as they are also
+reserved according to POSIX standards. While MAME violates this policy
+occasionally – most notably with ``device_t`` – it’s considered to be an
+unfortunate legacy decision that should be avoided in any new code.
+
+
+.. _contributing-cxx-literals:
+
+Variables and literals
+----------------------
+
+Octal literals are discouraged from use outside of specific cases. They
+lack the obvious letter-based prefixes found in hexadecimal and binary
+literals, and therefore can be difficult to distinguish at a glance from
+a decimal literal to coders who are unfamiliar with octal notation.
+
+Lower-case hexadecimal literals are preferred, e.g. ``0xbadc0de`` rather
+than ``0xBADC0DE``. For clarity, try not to exceed the bit width of the
+variable which will be used to store it.
+
+Binary literals have rarely been used in the MAME source code due to the
+``0b`` prefix not being standardised until C++14, but there is no policy
+to avoid their use.
+
+Integer suffix notation should be used when specifying 64-bit literals,
+but is not strictly required in other cases. It can, however, clarify
+the intended use of a given literal at a glance. Uppercase long integer
+literal suffixes should be used to avoid confusion with the digit 1,
+e.g. ``7LL`` rather than ``7ll``.
+
+Digit grouping should be used for longer numeric literals, as it aids in
+recognising order of magnitude or bit field positions at a glance.
+Decimal literals should use groups of three digits, and hexadecimal
+literals should use groups of four digits, outside of specific
+situations where different grouping would be easier to understand, e.g.
+``4'433'619`` or ``0xfff8'1fff``.
+
+Types that do not have a specifically defined size should be avoided if
+they are to be registered with MAME’s save-state system, as it harms
+portability. In general, this means avoiding the use of ``int`` for
+these members.
+
+It's encouraged, but not required, for class data members to be prefixed
+with ``m_`` for non-static instance members and ``s_`` for static
+members. This does not apply to nested classes or structs.
+
+
+.. _contributing-cxx-braceindent:
+
+Bracing and indentation
+-----------------------
+
+Tabs are used for initial indentation of lines, with one tab used per
+nested scope level. Statements split across multiple lines should be
+indented by two tabs. Spaces are used for alignment at other places
+within a line.
+
+Either K&R or Allman-style bracing is preferred. There is no specific
+preference for bracing on single-line statements, although bracing
+should be consistent for a given ``if/else`` block, as shown:
+
+.. code-block:: C++
+
+ if (x == 0)
+ {
+ return;
+ }
+ else
+ {
+ call_some_function();
+ x--;
+ }
+
+When using a series of ``if``/``else`` or ``if``/``else if``/``else``
+blocks with comments at the top indentation level, avoid extraneous
+newlines. The use of additional newlines may lead to ``else if`` or
+``else`` blocks being missed due to the newlines pushing the blocks
+outside the visible editor height:
+
+.. code-block:: C++
+
+ // Early-out if our hypothetical counter has run out.
+ if (x == 0)
+ {
+ return;
+ }
+ // We should do something if the counter is running.
+ else
+ {
+ call_some_function();
+ x--;
+ }
+
+Indentation for ``case`` statements inside a ``switch`` body can either
+be on the same level as the ``switch`` statement or inward by one level.
+There is no specific style which is used across all core files, although
+indenting by one level appears to be used most often.
+
+
+.. _contributing-cxx-spacing:
+
+Spacing
+-------
+
+Consistent single-spacing between binary operators, variables, and
+literals is strongly preferred. The following examples exhibit
+reasonably consistent spacing:
+
+.. code-block:: C++
+
+ uint8_t foo = (((bar + baz) + 3) & 7) << 1;
+ uint8_t foo = ((bar << 1) + baz) & 0x0e;
+ uint8_t foo = bar ? baz : 5;
+
+The following examples exhibit extremes in either direction, although
+having extra spaces is less difficult to read than having too few:
+
+.. code-block:: C++
+
+ uint8_t foo = ( ( ( bar + baz ) + 3 ) & 7 ) << 1;
+ uint8_t foo = ((bar<<1)+baz)&0x0e;
+ uint8_t foo = (bar?baz:5);
+
+A space should be used between a fundamental C++ statement and its
+opening parenthesis, e.g.:
+
+.. code-block:: C++
+
+ switch (value) ...
+ if (a != b) ...
+ for (int i = 0; i < foo; i++) ...
+
+
+.. _contributing-cxx-scoping:
+
+Scoping
+-------
+
+Variables should be scoped as narrowly as is reasonably possible. There
+are many instances of C89-style local variable declaration in the MAME
+codebase, but this is largely a hold-over from MAME’s early days, which
+pre-date the C99 specification.
+
+The following two snippets exhibit the legacy style of local variable
+declaration, followed by the more modern and preferred style:
+
+.. code-block:: C++
+
+ void example_device::some_function()
+ {
+ int i;
+ uint8_t data;
+
+ for (i = 0; i < std::size(m_buffer); i++)
+ {
+ data = m_buffer[i];
+ if (data)
+ {
+ some_other_function(data);
+ }
+ }
+ }
+
+.. code-block:: C++
+
+ void example_device::some_function()
+ {
+ for (int i = 0; i < std::size(m_buffer); i++)
+ {
+ const uint8_t data = m_buffer[i];
+ if (data)
+ {
+ some_other_function(data);
+ }
+ }
+ }
+
+Enumerated values, structs, and classes used only by one specific device
+should be declared within the device's class itself. This avoids
+pollution of the global namespace and makes the device-specific use of
+them more obvious at a glance.
+
+
+.. _contributing-cxx-const:
+
+Const Correctness
+-----------------
+
+Const-correctness has not historically been a strict requirement of code
+that goes into MAME, but there’s increasing value in it as the amount of
+code refactoring increases and technical debt decreases.
+
+When writing new code, it’s worth taking the time to determine if a
+local variable can be declared ``const``. Similarly, it's encouraged to
+consider which member functions of a new class can be ``const``
+qualified.
+
+In a similar vein, arrays of constants should be declared ``constexpr``
+and should use screaming snake case, as outlined towards the top of this
+document. Lastly, arrays of C-style strings should be declared as both
+a const array of const strings, as so:
+
+.. code-block:: C++
+
+ static const char *const EXAMPLE_NAMES[4] =
+ {
+ "1-bit",
+ "2-bit",
+ "4-bit",
+ "Invalid"
+ };
+
+
+.. _contributing-cxx-comments:
+
+Comments
+--------
+
+While ``/* ANSI C comments */`` are often found in the codebase, there
+has been a gradual shift towards ``// C++-style comments`` for
+single-line comments. This is very much a guideline, and coders are
+encouraged to use whichever style is most comfortable.
+
+Unless specifically quoting content from a machine or ancillary
+materials, comments should be in English so as to match the predominant
+language that the MAME team shares worldwide.
+
+Commented-out code should typically be removed prior to authoring a pull
+request, as it has a tendency to rot due to the fast-moving nature of
+MAME’s core API. If there is a desire known beforehand for the code to
+eventually be included, it should be bookended in ``if (0)`` or
+``if (false)``, as code removed through a preprocessor macro will rot at
+the same rate.
+
+
+.. _contributing-cxx-helpers:
+
+MAME-Specific Helpers
+---------------------
+
+When at all possible, use helper functions and macros for bit
+manipulation operations.
+
+The ``BIT(value, bit)`` helper can be used to extract the state of a bit
+at a given position from an integer value. The resulting value will be
+aligned to the least significant bit position, i.e. will be either 0 or
+1.
+
+An overload of the same function, ``BIT(value, bit, width)`` can be used
+to extract a bit field of a specified width from an integer value,
+starting at the specified bit position. The result will also be
+right-justified and will be of the same type as the incoming value.
+
+There are, additionally, a number of helpers for functionality such as
+counting leading zeroes/ones, population count, and signed/unsigned
+integer multiplication and division for both 32-bit and 64-bit results.
+Not all of these helpers have wide use in the MAME codebase, but using
+them in new code is strongly preferred when that code is performance-
+critical, as they utilise inline assembly or compiler intrinsics per-
+platform when available.
+
+``count_leading_zeros_32/64(T value)``
+ Accepts an unsigned 32/64-bit value and returns an unsigned 8-bit
+ value containing the number of consecutive zeros starting from the
+ most significant bit.
+``count_leading_ones_32/64(T value)``
+ Same functionality as above, but examining consecutive one-bits.
+``population_count_32/64(T value)``
+ Accepts an unsigned 32/64-bit value and returns the number of
+ one-bits found, i.e. the Hamming weight of the value.
+``rotl_32/64(T value, int shift)``
+ Performs a circular/barrel left shift of an unsigned 32/64-bit value
+ with the specified shift value. The shift value will be masked to
+ the valid bit range for a 32-bit or 64-bit value.
+``rotr_32/64(T value, int shift)``
+ Same functionality as above, but with a right shift.
+
+For documentation on helpers related to multiplication and division,
+refer to ``src/osd/eminline.h``.
+
+
+.. _contributing-cxx-logging:
+
+Logging
+-------
+
+MAME has multiple logging function for different purposes. Two of the
+most frequently used logging functions are ``logerror`` and
+``osd_printf_verbose``:
+
+* Devices inherit a ``logerror`` member function. This automatically
+ includes the fully-qualified tag of the invoking device in log
+ messages. Output is sent to MAME’s debugger’s rotating log buffer if
+ the debugger is enabled. If the
+ :ref:`-log option <mame-commandline-log>` is enabled, it’s also
+ written to the file ``error.log`` in the working directory. If the
+ :ref:`-oslog option <mame-commandline-oslog>` is enabled, it’s
+ additionally sent to the OS diagnostic output (the host debugger
+ diagnostic log on Windows if a host debugger is attached, or standard
+ error otherwise).
+* The output of the ``osd_printf_verbose`` function is sent to standard
+ error if the :ref:`-verbose option <mame-commandline-verbose>` is
+ enabled.
+
+The ``osd_printf_verbose`` function should be used for logging that is
+useful for diagnosing user issues, while ``logerror`` should be used for
+messages more relevant to developers (either developing MAME itself, or
+developing software for emulated systems using MAME’s debugger).
+
+For debug logging, a channel-based logging system exists via the header
+``logmacro.h``. It can be used as a generic logging system as follows,
+without needing to make use of its ability to mask out specific
+channels:
+
+.. code-block:: C++
+
+ // All other headers in the .cpp file should be above this line.
+ #define VERBOSE (1)
+ #include "logmacro.h"
+ ...
+ void some_device::some_reg_write(u8 data)
+ {
+ LOG("%s: some_reg_write: %02x\n", machine().describe_context(), data);
+ }
+
+The above example also makes use of a helper function which is available
+in all derivatives of ``device_t``: ``machine().describe_context()``.
+This function will return a string that describes the emulation context
+in which the function is being run. This includes the fully-qualified
+tag of the currently executing device (if any). If the relevant device
+implements ``device_state_interface``, it will also include the current
+program-counter value reported by the device.
+
+For more fine-grained control, specific bit masks can be defined and
+used via the ``LOGMASKED`` macro:
+
+.. code-block:: C++
+
+ // All other headers in the .cpp file should be above this line.
+ #define LOG_FOO (1 << 1U)
+ #define LOG_BAR (1 << 2U)
+
+ #define VERBOSE (LOG_FOO | LOG_BAR)
+ #include "logmacro.h"
+ ...
+ void some_device::some_reg_write(u8 data)
+ {
+ LOGMASKED(LOG_FOO, "some_reg_write: %02x\n", data);
+ }
+
+ void some_device::another_reg_write(u8 data)
+ {
+ LOGMASKED(LOG_BAR, "another_reg_write: %02x\n", data);
+ }
+
+Note that the least significant bit position for user-supplied masks is
+1, as bit position 0 is reserved for ``LOG_GENERAL``.
+
+By default, ``LOG`` and ``LOGMASKED`` will use the device-supplied
+``logerror`` function. However, this can be redirected as desired. The
+most common use case would be to direct output to the standard output
+instead, which can be accomplished by explicitly defining
+``LOG_OUTPUT_FUNC`` as so:
+
+.. code-block:: C++
+
+ #define LOG_OUTPUT_FUNC osd_printf_info
+
+A developer should always ensure that ``VERBOSE`` is set to 0 and that
+any definition of ``LOG_OUTPUT_FUNC`` is commented out prior to opening
+a pull request.
+
+
+.. _contributing-cxx-structure:
+
+Structural organization
+-----------------------
+
+All C++ source files must begin with a two comments listing the
+distribution license and copyright holders in a standard format.
+Licenses are specified by their SPDX short identifier if available.
+Here is an example of the standard format:
+
+.. code-block:: C++
+
+ // license:BSD-3-Clause
+ // copyright-holders:David Haywood, Tomasz Slanina
+
+Header includes should generally be grouped from most-dependent to
+least-dependent, and sorted alphabetically within said groups:
+
+* The project prefix header, ``emu.h``, must be the first thing in a
+ translation unit
+* Local project headers (i.e. headers found in the same source
+ directory)
+* Headers in ``src/devices``
+* Headers in ``src/emu``
+* Headers in ``src/lib/formats``
+* Headers in ``src/lib/util``
+* Headers from the OSD layer
+* C++ standard library headers
+* C standard library headers
+* OS-specific headers
+* Layout headers
+
+Finally, task-specific headers such as ``logmacro.h`` - described in the
+previous section - should be included last. A practical example
+follows:
+
+.. code-block:: C++
+
+ #include "emu.h"
+
+ #include "cpu/m68000/m68000.h"
+ #include "machine/mc68328.h"
+ #include "machine/ram.h"
+ #include "sound/dac.h"
+ #include "video/mc68328lcd.h"
+ #include "video/sed1375.h"
+
+ #include "emupal.h"
+ #include "screen.h"
+ #include "speaker.h"
+
+ #include "pilot1k.lh"
+
+ #define VERBOSE (0)
+ #include "logmacro.h"
+
+In most cases, the class declaration for a system driver should be
+within the corresponding source file along with the implementation. In
+such cases, the class declaration and all contents of the source file,
+excluding the ``GAME``, ``COMP``, or ``CONS`` macro, should be enclosed
+in an anonymous namespace (this produces better compiler diagnostics,
+allows more aggressive optimisation, reduces the chance of duplicate
+symbols, and reduces linking time).
+
+Within a class declaration, there should be one section for each member
+access level (``public``, ``protected`` and ``private``) if practical.
+This may not be possible in cases where private constants and/or types
+need to be declared before public members. Members should use the least
+public access level necessary. Overridden virtual member functions
+should generally use the same access level as the corresponding member
+function in the base class.
+
+Class member declarations should be grouped to aid understanding:
+
+* Within a member access level section, constants, types, data members,
+ instance member functions and static member functions should be
+ grouped.
+* In device classes, configuration member functions should be grouped
+ separately from live signal member functions.
+* Overridden virtual member functions should be grouped according to the
+ base classes they are inherited from.
+
+For classes with multiple overloaded constructors, constructor
+delegation should be used where possible to avoid repeated member
+initialiser lists.
+
+Constants which are used by a device or machine driver should be in the
+form of explicitly-sized enumerated values within the class declaration,
+or be relegated to ``#define`` macros within the source file. This
+helps avoid polluting the preprocessor.
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst
new file mode 100644
index 00000000000..df18b248374
--- /dev/null
+++ b/docs/source/contributing/index.rst
@@ -0,0 +1,144 @@
+.. _contributing:
+
+Contributing to MAME
+====================
+
+So you want to contribute to MAME but aren’t sure where to start? Well
+the great news is that there’s always plenty to do for people with a
+variety of skill sets.
+
+
+.. _contributing-testing:
+
+Testing and reporting bugs
+--------------------------
+
+One thing MAME can always do with is more testing and bug reports. If
+you’re familiar with a system that MAME emulates and notice something
+wrong, or if you find a bug in MAME’s user interface, you can head over
+to `MAME Testers <https://mametesters.org/>`_ and, assuming it isn’t
+already reported, register an account and open an issue. Be sure to
+read the `FAQ <https://mametesters.org/faq.html>`_ and
+`rules <https://mametesters.org/rules.html>`_ first to ensure you start
+out on the right foot. Please note that MAME Testers only accepts
+user-facing bugs in tagged release versions.
+
+For other kinds of issues, we have
+`GitHub Issues <https://github.com/mamedev/mame/issues/>`_. There’s a
+bit more leeway here. For example we accept developer-facing issues
+(e.g. bugs in internal APIs, or build system inadequacies), feature
+requests, and major regressions before they make it into a released
+version. Please respect the fact that the issue tracker is *not* a
+discussion or support forum, it’s only for reporting reproducible
+issues. Don’t open issues to ask questions or request support. Also,
+keep in mind that the ``master`` branch is unstable. If the current
+revision doesn’t compile at all or is completely broken, we’re probably
+already aware of it and don’t need issues opened for that. Wait a while
+and see if there’s an update. You might want to comment on the commit
+in question with the compiler error message, particularly if you’re
+compiling in an unorthodox but supported configuration.
+
+When opening an issue, remember to provide as much information as
+possible to help others understand, reproduce, and diagnose the issue.
+Things that are helpful to include:
+
+* The incorrect behaviour, and expected or correct behaviour. Be
+ specific: just saying it “doesn’t work” usually isn’t enough detail.
+* Environment details, including your operating system, CPU
+ architecture, system locale, and display language, if applicable. For
+ video output bugs, note your video hardware (GPU), driver version, and
+ the MAME video output module you’re using. For input handling bugs,
+ include the input peripherals and MAME input modules you’re using.
+* The exact version of MAME you’re using, including a git commit digest
+ if it isn’t a tagged release version, and any non-standard build
+ options.
+* The exact system and software being emulated (may not be applicable
+ for issues with parts of MAME’s UI, like the system selection menu).
+ Include things like the selected BIOS version, and emulated peripheral
+ (slot device) configuration.
+* Steps to reproduce the issue. Assume the person reading is familiar
+ with MAME itself, but not necessarily familiar with the emulated
+ system and software in question. For emulation issues, input
+ recordings and/or saved state files for reproducing the issue can be
+ invaluable.
+* An original reference for the correct behaviour. If you have access
+ to the original hardware for the emulated system, it helps to make a
+ recording of the correct behaviour for comparison.
+
+
+.. _contributing-code:
+
+Contributing to MAME’s source code
+----------------------------------
+
+MAME itself is written in C++, but that isn’t the sum total of the
+source code. The source code also includes:
+
+* The documentation hosted on this site (and also included in releases
+ as a PDF), written in
+ `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+ markup.
+* The supplied :ref:`plugins <plugins>`, written in
+ `Lua 5.3 <https://www.lua.org/manual/5.3/>`_.
+* Internal layouts for emulated machines that need to display more than
+ a simple video screen. These are an XML application
+ :ref:`described here <layfile>`.
+* The software lists, describing known software media for systems that
+ MAME emulates. MAME software lists are an XML application.
+* The user interface translations, in GNU gettext PO format. They can
+ be edited with a good text editor, or a dedicated tool like
+ `Poedit <https://poedit.net/>`_.
+
+Our primary source code repository is
+`hosted on GitHub <https://github.com/mamedev/mame/>`_. We prefer to
+receive source code contributions in the form of
+`pull requests <https://github.com/mamedev/mame/pulls>`_. You’ll need
+to learn the basics of git distributed version control and familiarise
+yourself with the git tools. The basic process for creating a pull
+request is as follows:
+
+* Sign up for an account on GitHub.
+* Create a fork of the mamedev/mame repository.
+* Create a new branch off the ``master`` branch in your forked
+ repository.
+* Clone your forked repository, and check out your new branch.
+* Make your changes, and build and test them locally.
+* Commit your changes, and push your branch to GitHub.
+* Optionally enable GitHub Actions for your forked repository, allowing
+ your changes to be built on Windows, macOS and Linux.
+* Open a pull request to merge your changes into the ``master`` branch
+ in the mamedev/mame repository.
+
+Please keep the following in mind (note that not all points are relevant
+to all kinds of changes):
+
+* Make your commit messages descriptive. Please include what the change
+ affects, and what it’s supposed to achieve. A person reading the
+ commit log shouldn’t need to resort to examining the diff to get a
+ basic idea of what a commit is supposed to do. The default commit
+ messages provided by GitHub are completely useless, as they don’t give
+ any indication of what a change is supposed to do.
+* Test your changes. Ensure that a full build of MAME completes, and
+ that the code you changed works. It’s a good idea to build with
+ ``DEBUG=1`` to check that assertions compile and don’t trigger.
+* Use an enlightening pull request title and description. The title
+ should give a one-line summary of what the overall change affects and
+ what it’s supposed to do. The description should contain more detail.
+ Don’t leave the description empty and describe the change in comments,
+ as this makes searching and filtering more difficult.
+* Be aware that GitHub Actions has opaque resource limits. It isn’t
+ clear when you’re close to the limits, and we’ve had contributors
+ banned from GitHub Actions for violating the limits. Even if you
+ appeal the ban, they still won’t tell you what the actual limits are,
+ justifying this by saying that if you know the limits, you can take
+ steps to evade them. If you enable GitHub Actions, consider not
+ pushing individual commits if you don’t need them to be automatically
+ built, or cancelling workflow runs when you don’t need the results.
+
+We have guidelines for specific parts of the source:
+
+.. toctree::
+ :titlesonly:
+
+ cxx
+ softlist
diff --git a/docs/source/contributing/softlist.rst b/docs/source/contributing/softlist.rst
new file mode 100644
index 00000000000..afcfa78ffb0
--- /dev/null
+++ b/docs/source/contributing/softlist.rst
@@ -0,0 +1,175 @@
+.. _contributing-softlist:
+
+Guidelines for Software Lists
+=============================
+
+.. contents:: :local:
+
+
+.. _contributing-softlist-intro:
+
+Introduction
+------------
+
+MAME’s software lists describe known software media for emulated
+systems in a form that can be used to identify media image files for
+known software, verify media image file integrity, and load media
+image files for emulation. Software lists are implemented as XML
+files in the ``hash`` folder. The XML structure is described in the
+file ``hash/softwarelist.dtd``.
+
+Philosophically, software list items should represent the original
+media, rather than a specific dump of the media. Ideally, it should be
+possible for anyone with the media to dump it and produce the same image
+file. Of course, this isn’t always possible in practice – in particular
+it’s problematic for inherently analog media, like home computer
+software stored on audio tape cassettes.
+
+MAME strives to document the best available media images. It is not our
+intention to propagate corrupted, truncated, defaced, watermarked, or
+otherwise bad media images. Where possible, file structures matching
+the original media structure are preferred. For example we prefer
+individual files for separate ROM chips in cartridge media, and we use
+disk images rather than archives of files extracted from the original
+disks.
+
+
+.. _contributing-softlist-itempart:
+
+Items and parts
+---------------
+
+A software list is a collection of *items* and each item may have
+multiple *parts*. An item represents a piece of software, as
+distributed as a complete package. A part represents a single piece of
+media within the package. Parts can be mounted individually in
+emulated media devices. For example a piece of software distributed on
+three floppy disks will be a single item, while each floppy disk will be
+one part within that item.
+
+Sometimes, logically separate parts of a single physical piece of media
+are represented as separate parts within a software item. For example
+each side of an audio tape cassette is represented as a separate part.
+However individual ROM chips within a cartridge may be separate files,
+but they are *not* separate parts, as the cartridge is mounted as a
+whole.
+
+Each item is a ``software`` element. The ``software`` element may have
+the following attributes:
+
+name (required)
+ The short name identifying the item. This is used for file names,
+ command line arguments, database keys, URL fragments, and many other
+ purposes. It should be terse but still recognisable. It must be
+ unique within the software list. Valid characters are lowercase
+ English letters, decimal digits and underscores. The maximum
+ allowed length is sixteen characters.
+cloneof (optional)
+ The short name of the parent item if the item is a clone. The
+ parent must be within the same software list – parent/clone
+ relationships spanning multiple software lists are not supported.
+supported (optional)
+ One of the values ``yes`` (fully usable in emulation), ``no`` (not
+ usable in emulation), or ``partial`` (usable in emulation with
+ limitations). If the attribute is not present, it is equivalent to
+ ``yes``. Examples of partially supported software include games
+ that are playable with graphical glitches, and office software where
+ some but not all functionality works.
+
+Each part is a ``part`` element within the ``software`` element. The
+``part`` element must have the following attributes:
+
+name (required)
+ The short name identifying the part. This is used for command line
+ arguments, database keys, URL fragments, and many other purposes.
+ It must be unique within the item. It is also used as the display
+ name if a separate display name is not provided. Valid characters
+ are lowercase English letters, decimal digits and underscores. The
+ maximum allowed length is sixteen characters.
+interface (required)
+ This attribute is used to identify suitable emulated media devices
+ for mounting the software part. Applicable values depend on the
+ emulated system.
+
+
+.. _contributing-softlist-metadata:
+
+Metadata
+--------
+
+Software lists support various kinds of metadata. All software list
+items require the following metadata elements to be present:
+
+description
+ This is the primary display name for the software item. It should
+ be the original name of the software, transliterated into English
+ Latin script if necessary. It must be unique within the software
+ list. If extra text besides the title itself is required for
+ disambiguation, use lowercase outside of proper nouns, initialisms
+ and verbatim quotes.
+year
+ The year of release or copyright year for the software. If unknown,
+ use an estimate with a question mark. Items can be filtered by year
+ in the software selection menu.
+publisher
+ The publisher of the software. This may be the same as the
+ developer if the software was self-published. Items can be filtered
+ by published in the software selection menu.
+
+Most user-visible software item metadata is provided using ``info``
+elements. Each ``info`` element must have a ``name`` attribute and a
+``value`` attribute. The ``name`` attribute identifies the type of
+metadata, and the ``value`` attribute is the metadata value itself.
+Note that ``name`` attributes do not need to be unique within an item.
+Multiple ``info`` elements with the same ``name`` may be present if
+appropriate. This is frequently seen for software sold using different
+titles in different regions.
+
+MAME displays metadata from ``info`` elements in the software selection
+menu. The following ``name`` attributes are recognised specifically,
+and can show localised names:
+
+alt_title
+ Used for alternate titles. Examples are different tiles used in
+ different languages, scripts or regions, or different titles used
+ on the title screen and packaging. MAME searches alternate titles
+ as well as the description.
+author
+ Author of the software. Items can be filtered by author in the
+ software selection menu.
+barcode
+ Barcode number identifying the software package (typically an EAN).
+developer
+ Developer responsible for implementing the software. Items can be
+ filtered by developer in the software selection menu.
+distributor
+ Party responsible for distributing the software to retailers (or
+ customers in the case of direct sales). Items can be filtered by
+ distributor in the software selection menu.
+install
+ Installation instructions.
+isbn
+ ISBN for software included with a commercial book.
+oem
+ Original equipment manufacturer, typically used with customised
+ versions of software distributed by a hardware vendor.
+original_publisher
+ The original publisher, for items representing software re-released
+ by a different publisher.
+partno
+ Distributor’s part number for the software.
+pcb
+ Printed circuit board identifier, typically for cartridge media.
+programmer
+ Programmer who wrote the code for the software.
+release
+ Fine-grained release date for the software, if known. Use
+ YYYYMMDD format with no punctuation. If only the month is known,
+ use “xx” for the day digits. For example ``199103xx`` or
+ ``19940729``.
+serial
+ Number identifying the software within a series of releases.
+usage
+ Usage instructions.
+version
+ Version number of the software.
diff --git a/docs/source/debugger/exceptionpoint.rst b/docs/source/debugger/exceptionpoint.rst
new file mode 100644
index 00000000000..52a8ee67a19
--- /dev/null
+++ b/docs/source/debugger/exceptionpoint.rst
@@ -0,0 +1,134 @@
+.. _debugger-exceptionpoint-list:
+
+Exception Point Debugger Commands
+=================================
+
+:ref:`debugger-command-epset`
+ sets a new exception point
+:ref:`debugger-command-epclear`
+ clears a specific exception point or all exception points
+:ref:`debugger-command-epdisable`
+ disables a specific exception point or all exception points
+:ref:`debugger-command-epenable`
+ enables a specific exception point or all exception points
+:ref:`debugger-command-eplist`
+ lists exception points
+
+Exception points halt execution and activate the debugger when
+a CPU raises a particular exception number.
+
+
+.. _debugger-command-epset:
+
+epset
+-----
+
+**ep[set] <type>[,<condition>[,<action>]]**
+
+Sets a new exception point for exceptions of type **<type>**. The
+optional **<condition>** parameter lets you specify an expression that
+will be evaluated each time the exception point is hit. If the result
+of the expression is true (non-zero), the exception point will actually
+halt execution at the start of the exception handler; otherwise,
+execution will continue with no notification. The optional **<action>**
+parameter provides a command that is executed whenever the exception
+point is hit and the **<condition>** is true. Note that you may need to
+embed the action within braces ``{ }`` in order to prevent commas and
+semicolons from being interpreted as applying to the ``epset`` command
+itself.
+
+The numbering of exceptions depends upon the CPU type. Causes of
+exceptions may include internally or externally vectored interrupts,
+errors occurring within instructions and system calls.
+
+Each exception point that is set is assigned an index which can be used
+in other exception point commands to reference this exception point.
+
+Examples:
+
+``ep 2``
+ Set an exception that will halt execution whenever the visible CPU
+ raises exception number 2.
+
+Back to :ref:`debugger-exceptionpoint-list`
+
+
+.. _debugger-command-epclear:
+
+epclear
+-------
+
+**epclear [<epnum>[,…]]**
+
+The epclear command clears exception points. If **<epnum>** is
+specified, only the requested exception points are cleared, otherwise
+all exception points are cleared.
+
+Examples:
+
+``epclear 3``
+ Clear exception point index 3.
+
+``epclear``
+ Clear all exception points.
+
+Back to :ref:`debugger-exceptionpoint-list`
+
+
+.. _debugger-command-epdisable:
+
+epdisable
+---------
+
+**epdisable [<epnum>[,…]]**
+
+The epdisable command disables exception points. If **<epnum>** is
+specified, only the requested exception points are disabled, otherwise
+all exception points are disabled. Note that disabling an exception
+point does not delete it, it just temporarily marks the exception
+point as inactive.
+
+Examples:
+
+``epdisable 3``
+ Disable exception point index 3.
+
+``epdisable``
+ Disable all exception points.
+
+Back to :ref:`debugger-exceptionpoint-list`
+
+
+.. _debugger-command-epenable:
+
+epenable
+--------
+
+**epenable [<epnum>[,…]]**
+
+The epenable command enables exception points. If **<epnum>** is
+specified, only the requested exception points are enabled, otherwise
+all exception points are enabled.
+
+Examples:
+
+``epenable 3``
+ Enable exception point index 3.
+
+``epenable``
+ Enable all exception points.
+
+Back to :ref:`debugger-exceptionpoint-list`
+
+
+.. _debugger-command-eplist:
+
+eplist
+------
+
+**eplist**
+
+The eplist command lists all the current exception points, along with
+their index and any conditions or actions attached to them.
+
+Back to :ref:`debugger-exceptionpoint-list`
diff --git a/docs/source/debugger/execution.rst b/docs/source/debugger/execution.rst
index 8a99f52f85a..b4de833b43f 100644
--- a/docs/source/debugger/execution.rst
+++ b/docs/source/debugger/execution.rst
@@ -12,10 +12,16 @@ Execution Debugger Commands
(Shift-F11)
:ref:`debugger-command-go`
resume execution (F5)
+:ref:`debugger-command-gbt`
+ resume execution until next true branch is executed
+:ref:`debugger-command-gbf`
+ resume execution until next false branch is executed
:ref:`debugger-command-gex`
resume execution until exception is raised
:ref:`debugger-command-gint`
resume execution until interrupt is taken (F7)
+:ref:`debugger-command-gni`
+ resume execution until next further instruction
:ref:`debugger-command-gtime`
resume execution until the given delay has elapsed
:ref:`debugger-command-gvblank`
@@ -137,6 +143,64 @@ Examples:
Back to :ref:`debugger-execution-list`
+.. _debugger-command-gbf:
+
+gbf
+---
+
+**gbf [<condition>]**
+
+Resumes execution. Control will not be returned to the debugger until
+a breakpoint or watchpoint is triggered, or until a conditional branch
+or skip instruction is not taken, following any delay slots.
+
+The optional **<condition>** parameter lets you specify an expression
+that will be evaluated each time a conditional branch is encountered.
+If the result of the expression is true (non-zero), execution will be
+halted after the branch if it is not taken; otherwise, execution will
+continue with no notification.
+
+Examples:
+
+``gbf``
+ Resume execution until a breakpoint/watchpoint is triggered, or
+ until the next false branch.
+``gbf {pc != 1234}``
+ Resume execution until the next false branch, disregarding the
+ instruction at address 1234.
+
+Back to :ref:`debugger-execution-list`
+
+
+.. _debugger-command-gbt:
+
+gbt
+---
+
+**gbt [<condition>]**
+
+Resumes execution. Control will not be returned to the debugger until
+a breakpoint or watchpoint is triggered, or until a conditional branch
+or skip instruction is taken, following any delay slots.
+
+The optional **<condition>** parameter lets you specify an expression
+that will be evaluated each time a conditional branch is encountered.
+If the result of the expression is true (non-zero), execution will be
+halted after the branch if it is taken; otherwise, execution will
+continue with no notification.
+
+Examples:
+
+``gbt``
+ Resume execution until a breakpoint/watchpoint is triggered, or
+ until the next true branch.
+``gbt {pc != 1234}``
+ Resume execution until the next true branch, disregarding the
+ instruction at address 1234.
+
+Back to :ref:`debugger-execution-list`
+
+
.. _debugger-command-gex:
gex
@@ -196,6 +260,34 @@ Examples:
Back to :ref:`debugger-execution-list`
+.. _debugger-command-gni:
+
+gni
+---
+
+**gni [<count>]**
+
+Resumes execution. Control will not be returned to the debugger until a
+breakpoint or watchpoint is triggered. A temporary unconditional breakpoint
+is set at the program address **<count>** instructions sequentially past the
+current one. When this breakpoint is hit, it is automatically removed.
+
+The **<count>** parameter is optional and defaults to 1 if omitted. If
+**<count>** is specified as zero, the command does nothing. **<count>** is
+not permitted to exceed 512 decimal.
+
+Examples:
+
+``gni``
+ Resume execution until a breakpoint/watchpoint is triggered, including
+ the temporary breakpoint set at the address of the following instruction.
+``gni 2``
+ Resume execution until a breakpoint/watchpoint is triggered. A temporary
+ breakpoint is set two instructions past the current one.
+
+Back to :ref:`debugger-execution-list`
+
+
.. _debugger-command-gtime:
gtime
@@ -209,7 +301,7 @@ specified in milliseconds.
Example:
-``gtime #10000```
+``gtime #10000``
Resume execution for ten seconds of emulated time.
Back to :ref:`debugger-execution-list`
@@ -348,7 +440,7 @@ trace
Starts or stops tracing for execution of the specified **<CPU>**, or the
currently visible CPU if no CPU is specified. To enable tracing,
specify the trace log file name in the **<filename>** parameter. To
-disable tracing, use the keyword ``off`` for for the **<filename>**
+disable tracing, use the keyword ``off`` for the **<filename>**
parameter. If the **<filename>** argument begins with two right angle
brackets (**>>**), it is treated as a directive to open the file for
appending rather than overwriting.
diff --git a/docs/source/debugger/general.rst b/docs/source/debugger/general.rst
index ffeb1379f3f..c01ef20dea8 100644
--- a/docs/source/debugger/general.rst
+++ b/docs/source/debugger/general.rst
@@ -41,6 +41,8 @@ General Debugger Commands
save a screen snapshot
:ref:`debugger-command-source`
read commands from file and executes them one by one
+:ref:`debugger-command-time`
+ prints the current machine time to the console
:ref:`debugger-command-quit`
exit the debugger and end the emulation session
@@ -78,8 +80,8 @@ do
The **do** command simply evaluates the supplied expression. This is
often used to set or modify device state variable (e.g. CPU registers),
-or to write to memory. See :ref:`debugger-expressions` for details
-about expression syntax.
+or to write to memory. See :ref:`debugger-express` for details about
+expression syntax.
Examples:
@@ -188,15 +190,22 @@ available:
%c
Prints the corresponding argument as an 8-bit character.
-%[0][<n>]d
+%[-][0][<n>]d
Prints the corresponding argument as a decimal number with optional
- minimum field width and zero fill.
-%[0][<n>]o
+ left justification, zero fill and minimum field width.
+%[-][0][<n>]o
Prints the corresponding argument as an octal number with optional
- minimum field width and zero fill using lowercase letters.
-%[0][<n>]x
- Prints the corresponding argument as a hexadecimal number with
- optional minimum field width and zero fill using uppercase letters.
+ left justification, zero fill and minimum field width.
+%[-][0][<n>]x
+ Prints the corresponding argument as a lowercase hexadecimal number
+ with optional left justification, zero fill and minimum field width.
+%[-][0][<n>]X
+ Prints the corresponding argument as an uppercase hexadecimal number
+ with optional left justification, zero fill and minimum field width.
+%[-][<n>][.[<n>]]s
+ Prints a null-terminated string of 8-bit characters from the address
+ and address space given by the corresponding argument, with optional
+ left justification, minimum and maximum field widths.
\%%
Prints a literal percent symbol.
\\n
@@ -544,6 +553,21 @@ Examples:
Back to :ref:`debugger-general-list`
+.. _debugger-command-time:
+
+time
+----
+
+Prints the total elapsed emulated time to the debugger console.
+
+Examples:
+
+``time``
+ Prints the elapsed emulated time.
+
+Back to :ref:`debugger-general-list`
+
+
.. _debugger-command-quit:
quit
diff --git a/docs/source/debugger/index.rst b/docs/source/debugger/index.rst
index 18785e734e7..2947d0253ac 100644
--- a/docs/source/debugger/index.rst
+++ b/docs/source/debugger/index.rst
@@ -18,7 +18,7 @@ ROM hacking, or just investigating how software works.
Use the ``-debug`` command line option to start MAME with the debugger
activated. By default, pressing the backtick/tilde (**~**) during
-emulation breaks into the debugger (this can by changed by reassigning
+emulation breaks into the debugger (this can be changed by reassigning
the **Break in Debugger** input).
The exact appearance of the debugger depends on your operating system
@@ -50,6 +50,7 @@ name of a command, to see documentation directly in MAME.
breakpoint
watchpoint
registerpoints
+ exceptionpoint
annotation
cheats
image
@@ -163,7 +164,7 @@ debugger should take the most likely meaning for a device or address
space specification.
-.. _debugger-expressions:
+.. _debugger-express:
Debugger expression syntax
--------------------------
@@ -190,7 +191,7 @@ precedence:
Addition, subtraction
``<<`` ``>>``
Bitwise left/right shift
-``< ``<=`` ``>`` ``>=``
+``<`` ``<=`` ``>`` ``>=``
Less than, less than or equal, greater than, greater than or equal
``==`` ``!=``
Equal, not equal
@@ -218,6 +219,8 @@ Major differences from C expression semantics:
always evaluated.
+.. _debugger-express-num:
+
Numbers
~~~~~~~
@@ -236,10 +239,12 @@ Examples:
* ``0x123`` is 123 hexadecimal (291 decimal)
* ``#123`` is 123 decimal
* ``0o123`` is 123 octal (83 decimal)
-* ``0b1001`` is is 1001 binary (9 decimal)
+* ``0b1001`` is 1001 binary (9 decimal)
* ``0b123`` is invalid
+.. _debugger-express-bool:
+
Boolean values
~~~~~~~~~~~~~~
@@ -253,6 +258,8 @@ debugger commands to use the default value, even when subsequent
parameters are specified.
+.. _debugger-express-mem:
+
Memory accesses
~~~~~~~~~~~~~~~
@@ -281,22 +288,22 @@ multiple effects of a write access. For example:
* Some registers need to be written in sequence to avoid race
conditions. The debugger can issue multiple writes at the same point
- in emulated time, so these race conditions cannot be avoided
- trivially. For example writing to the MC68HC05 output compare
- register high byte (OCRH) inhibits compare until the output compare
- register low byte (OCRL) is written to prevent race conditions.
- Since the debugger can write to both locations at the same instant
- from the emulated machine’s point of view, the race condition is not
- usually relevant. It’s more error-prone if you can accidentally set
- hidden state when all you really want to do is change the value, so
- writing to OCRH with side effects suppressed does not inhibit compare,
- it just changes the value in the output compare register.
+ in emulated time, so these race conditions can be avoided trivially.
+ For example writing to the MC68HC05 output compare register high byte
+ (OCRH) inhibits compare until the output compare register low byte
+ (OCRL) is written to prevent race conditions. Since the debugger can
+ write to both locations at the same instant from the emulated
+ machine’s point of view, the race condition is not usually relevant.
+ It’s more error-prone if you can accidentally set hidden state when
+ all you really want to do is change the value, so writing to OCRH with
+ side effects suppressed does not inhibit compare, it just changes the
+ value in the output compare register.
* Writing to some registers has multiple effects that may be useful to
separate for debugging purposes. Using the MC68HC05 as an example
again, writing to OCRL changes the value in the output compare
register, and also clears the output compare flag (OCF) and enables
compare if it was previously inhibited by writing to OCRH. Writing to
- OCRL with side effects disable just changes the value in the register
+ OCRL with side effects disabled just changes the value in the register
without clearing OCF or enabling compare, since it’s useful for
debugging purposes. Writing to OCRL with side effects enabled has the
additional effects.
@@ -353,7 +360,7 @@ Adding access types gives additional possibilities:
suppressing side effects
``id@400``
Refers to the double word at 400 in the I/O space of the current CPU
- CPU while suppressing side effects
+ while suppressing side effects
``ppd!<addr>``
Refers to the double word at physical address **<addr>** in the
program space of the current CPU while not suppressing side effects
@@ -390,6 +397,8 @@ Memory accesses can be used as both lvalues and rvalues, so you can write
``b@100 = ff`` to store a byte in memory.
+.. _debugger-express-func:
+
Functions
~~~~~~~~~
@@ -409,8 +418,8 @@ abs(<x>)
absolute value.
bit(<x>, <n>[, <w>])
Extracts and right-aligns a bit field **<w>** bits wide from **<x>**
- with least significant bit position position **<n>**, counting from
- the least significant bit. If **<w>** is omitted, a single bit is
+ with least significant bit position **<n>**, counting from the
+ least significant bit. If **<w>** is omitted, a single bit is
extracted.
s8(<x>)
Sign-extends the argument from 8 bits to 64 bits (overwrites bits 8
diff --git a/docs/source/debugger/registerpoints.rst b/docs/source/debugger/registerpoints.rst
index aea14edd1ac..ebd531f219d 100644
--- a/docs/source/debugger/registerpoints.rst
+++ b/docs/source/debugger/registerpoints.rst
@@ -131,7 +131,7 @@ rplist
**rplist [<CPU>]**
List current registerpoints, along with their indices and conditions,
-and any associated actions actions. If no **<CPU>** is specified,
+and any associated actions. If no **<CPU>** is specified,
registerpoints for all CPUs in the system will be listed; if a **<CPU>**
is specified, only registerpoints for that CPU will be listed. The
**<CPU>** can be specified by tag or by debugger CPU number (see
diff --git a/docs/source/debugger/watchpoint.rst b/docs/source/debugger/watchpoint.rst
index 2b25e0631f8..0f4bd12902f 100644
--- a/docs/source/debugger/watchpoint.rst
+++ b/docs/source/debugger/watchpoint.rst
@@ -75,7 +75,7 @@ Examples:
execution.
``temp0 = 0 ; wp 45678,1,w,wpdata==f0,{ temp0++ ; g }``
Set a watchpoint for the visible CPU that will halt execution
- whenever a write do the first address space occurs at address 45678
+ whenever a write to the first address space occurs at address 45678
where the value being written is equal to f0. When this happens,
increment the variable **temp0** and resume execution.
diff --git a/docs/source/images/MAMElogo.svg b/docs/source/images/MAMElogo.svg
index 01d860d18e7..a728ab92a31 100644
--- a/docs/source/images/MAMElogo.svg
+++ b/docs/source/images/MAMElogo.svg
@@ -9,12 +9,12 @@
width="1214px">
<defs>
<linearGradient id="left-dark" x1="0" x2="1" y1="0" y2="0">
- <stop id="stop5213" offset="0" stop-color="#00274f" />
- <stop id="stop5215" offset="1" stop-color="#68cafb" />
+ <stop id="left-dark-0" offset="0" stop-color="#00274f" />
+ <stop id="left-dark-1" offset="1" stop-color="#68cafb" />
</linearGradient>
<linearGradient id="right-dark" x1="0" x2="1" y1="0" y2="0">
- <stop id="stop4" offset="0" stop-color="#68cafb" />
- <stop id="stop6" offset="1" stop-color="#00274f" />
+ <stop id="right-dark-0" offset="0" stop-color="#68cafb" />
+ <stop id="right-dark-1" offset="1" stop-color="#00274f" />
</linearGradient>
</defs>
<g>
diff --git a/docs/source/index.rst b/docs/source/index.rst
index d4761f5a2b4..e2e54a4ee2b 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -11,7 +11,7 @@ MAME Documentation
==================
.. note::
- This documentation is a work in progress. You can track the status of these topics through MAME's `issue tracker <https://github.com/mamedev/mame/issues>`_. Learn how you can `contribute <https://github.com/mamedev/mame/blob/master/docs/CONTRIBUTING.md>`_ on GitHub.
+ This documentation is a work in progress. You can track the status of these topics through MAME's `issue tracker <https://github.com/mamedev/mame/issues>`_. Learn how you can :ref:`contribute <contributing>`.
.. toctree::
:titlesonly:
@@ -26,8 +26,10 @@ MAME Documentation
advanced/index
debugger/index
+ luascript/index
tools/index
+ contributing/index
techspecs/index
security
diff --git a/docs/source/initialsetup/compilingmame.rst b/docs/source/initialsetup/compilingmame.rst
index fdd0545db9f..0df34f5d12b 100644
--- a/docs/source/initialsetup/compilingmame.rst
+++ b/docs/source/initialsetup/compilingmame.rst
@@ -9,48 +9,74 @@ All Platforms
-------------
* To compile MAME, you need a C++17 compiler and runtime library. We
- support building with GCC version 7.2 or later and clang version 6 or
- later. MAME should run with GNU libstdc++ version 7.2 or later.
-
-* Whenever you are changing build parameters, (such as switching between
- a SDL-based build and a native Windows renderer one, or adding tools
- to the compile list) you need to run a **make REGENIE=1** to allow the
- settings to be regenerated. Failure to do this will cause you very
+ support building with GCC version 10.3 or later and clang version 11
+ or later. MAME should run with GNU libstdc++ version 10.3 or later or
+ libc++ version 11 or later. The initial release of any major version
+ of GCC should be avoided. For example, if you want to compile MAME
+ with GCC 12, you should use version 12.1 or later.
+
+* Whenever you are changing build parameters, (for example changing
+ optimisation settings, or adding tools to the compile list), or system
+ drivers sources are added, removed, or renamed, the project files need
+ to be regenerated. You can do this by adding **REGENIE=1** to the
+ make arguments, or updating the modification time of the makefile (for
+ example using the **touch** command). Failure to do this may cause
difficult to troubleshoot problems.
* If you want to add various additional tools to the compile, such as
*chdman*, add a **TOOLS=1** to your make command, like
**make REGENIE=1 TOOLS=1**
-* You can do driver specific builds by using *SOURCES=<driver>* in your
- make command. For instance, building Pac-Man by itself would be
- **make SOURCES=src/mame/drivers/pacman.cpp REGENIE=1** including the
- necessary *REGENIE* for rebuilding the settings.
-
-* Speeding up the compilation can be done by using more cores from your
- CPU. This is done with the **-j** parameter. *Note: a good number to
- start with is the total number of CPU cores in your system plus one.
- An excessive number of concurrent jobs may increase compilation time.
- The optimal number depends on many factors, including number of CPU
- cores, available RAM, disk and filesystem performance, and memory
- bandwidth.* For instance, **make -j5** is a good starting point on a
- system with a quad-core CPU.
+* You can build an emulator for a subset of the systems supported by
+ MAME by using *SOURCES=<driver>,...* in your make command. For
+ example
+ **make SUBTARGET=pacem SOURCES=src/mame/pacman/pacman.cpp REGENIE=1**
+ would build an emulator called *pacem* including the system drivers
+ from the source file pacman.cpp (*REGENIE=1* is specified to ensure
+ project files are regenerated). You can specify folders to include
+ their entire contents, and you can separate multiple files/folders
+ with commas. You can also omit the *src/mame/* prefix in many cases.
+
+ If you encounter linking errors after changing the included sources,
+ delete the static libraries for the subtarget from the build folder.
+ For the previous example on Windows using GCC, these would be in
+ *build/mingw-gcc/bin/x64/Release/mame_pacem* by default.
+
+* On a system with multiple CPU cores, compilation can be sped up by
+ compiling multiple source files in parallel. This is done with the
+ **-j** parameter. For instance, **make -j5** is a good starting point
+ on a system with a quad-core CPU.
+
+ *Note: a good number to start with is the total number of CPU cores
+ in your system plus one. An excessive number of concurrent jobs will
+ increase compilation time, particularly if the compiler jobs exhaust
+ available memory. The optimal number depends on many factors,
+ including number of CPU cores, available RAM, disk and filesystem
+ performance, and memory bandwidth.*
* Debugging information can be added to a compile using *SYMBOLS=1*
though most users will not want or need to use this. This increases
- compile time and disk space used.
+ compile time and disk space used. Note that a full build of MAME
+ including internal debugging symbols will exceed the maximum size for
+ an executable on Windows, and will not be possible to run without
+ first stripping the symbols.
Putting all of these together, we get a couple of examples:
-Rebuilding MAME for just the Pac-Man driver, with tools, on a quad-core
-(e.g. i5 or i7) machine::
-
- make SOURCES=src/mame/drivers/pacman.cpp TOOLS=1 REGENIE=1 -j5
-
Rebuilding MAME on a dual-core (e.g. i3 or laptop i5) machine::
make -j3
+Rebuilding MAME for just the Pac-Man and Galaxian families of systems,
+with tools, on a quad-core (e.g. i5 or i7) machine::
+
+ make SUBTARGET=pacem SOURCES=src/mame/pacman,src/mame/galaxian TOOLS=1 REGENIE=1 -j5
+
+Rebuilding MAME for just the Apple II systems, compiling up to six
+sources in parallel::
+
+ make SUBTARGET=appulator SOURCES=apple/apple2.cpp,apple/apple2e.cpp,apple/apple2gs.cpp REGENIE=1 -j6
+
.. _compiling-windows:
@@ -72,7 +98,7 @@ building MAME on a 64-bit system. Instructions may need to be adjusted for
use the portable SDL (Simple DirectMedia Layer) interfaces instead, you can
add **OSD=sdl** to the make options. The main emulator binary will have an
``sdl`` prefix prepended (e.g. ``sdlmame.exe``). You
- will need to install the MSYS2 packages for SDL 2 version 2.0.3 or later.
+ will need to install the MSYS2 packages for SDL 2 version 2.0.14 or later.
* By default, MAME will include the native Windows debugger. To also include
the portable Qt debugger, add **USE_QTDEBUG=1** to the make options. You
will need to install the MSYS2 packages for Qt 5.
@@ -89,8 +115,9 @@ with MSYS2 and the **pacman** package manager.
* Download the latest version of the ``mame-essentials`` package from the
`MAME package repository <https://repo.mamedev.org/x86_64/>`_ and install it
using the **pacman** command.
-* Add the ``mame`` repository to ``/etc/pacman.conf`` using
- ``/etc/pacman.d/mirrorlist.mame`` for locations.
+* Add the ``mame`` package repository to ``/etc/pacman.conf`` using
+ ``/etc/pacman.d/mirrorlist.mame`` for locations, and disable signature
+ verification for this repository (``SigLevel = Never``).
* Install packages necessary to build MAME. At the very least, you’ll need
``bash``, ``git``, ``make``.
* For 64-bit builds you’ll need ``mingw-w64-x86_64-gcc`` and
@@ -152,7 +179,7 @@ configuration::
curl -O "https://repo.mamedev.org/x86_64/mame-essentials-1.0.6-1-x86_64.pkg.tar.xz"
pacman -U mame-essentials-1.0.6-1-x86_64.pkg.tar.xz
- echo -e '\n[mame]\nInclude = /etc/pacman.d/mirrorlist.mame' >> /etc/pacman.conf
+ echo -e '\n[mame]\nInclude = /etc/pacman.d/mirrorlist.mame\nSigLevel = Never' >> /etc/pacman.conf
Building with Microsoft Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -224,10 +251,15 @@ Fedora Linux
------------
You’ll need a few prerequisites from your Linux distribution. Make sure you get
-SDL2 2.0.4 or later as earlier versions are buggy::
+SDL 2 version 2.0.14 or later as earlier versions lack required functionality::
sudo dnf install gcc gcc-c++ SDL2-devel SDL2_ttf-devel libXi-devel libXinerama-devel qt5-qtbase-devel qt5-qttools expat-devel fontconfig-devel alsa-lib-devel pulseaudio-libs-devel
+If you want to use the more efficient LLVM tools for archiving static libraries
+and linking, you’ll need to install the corresponding packages::
+
+ sudo dnf install lld llvm
+
Compilation is exactly as described above in All Platforms.
To build the HTML user/developer documentation, you’ll need Sphinx, as well as
@@ -246,9 +278,9 @@ Debian and Ubuntu (including Raspberry Pi and ODROID devices)
-------------------------------------------------------------
You’ll need a few prerequisites from your Linux distribution. Make sure you get
-SDL2 2.0.4 or later as earlier versions are buggy::
+SDL 2 version 2.0.14 or later as earlier versions lack required functionality::
- sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qt5-default
+ sudo apt-get install git build-essential python3 libsdl2-dev libsdl2-ttf-dev libfontconfig-dev libpulse-dev qtbase5-dev qtbase5-dev-tools qtchooser qt5-qmake
Compilation is exactly as described above in All Platforms. Note the Ubuntu
Linux modifies GCC to enable the GNU C Library “fortify source” feature by
@@ -262,7 +294,7 @@ Arch Linux
You’ll need a few prerequisites from your distro::
- sudo pacman -S base-devel git sdl2 gconf sdl2_ttf gcc qt5
+ sudo pacman -S base-devel git sdl2_ttf python libxinerama libpulse alsa-lib qt5-base
Compilation is exactly as described above in All Platforms.
@@ -272,10 +304,11 @@ Compilation is exactly as described above in All Platforms.
Apple macOS
-----------
-You’ll need a few prerequisites to get started. Make sure you’re on OS X 10.14
-Mojave or later for Intel Macs or macOS 11.0 Big Sur for Apple Silicon. You will
-need SDL2 2.0.4 or later for Intel or SDL2 2.0.14 on Apple Silicon. You’ll also
-need to install Python 3.
+You’ll need a few prerequisites to get started. Make sure you’re on macOS 11.0
+Big Sur or later. You will need SDL 2 version 2.0.14 or later. You’ll also
+need to install Python 3 – it’s currently included with the Xcode command line
+tools, but you can also install a stand-alone version or get it via the Homebrew
+package manager.
* Install **Xcode** from the Mac App Store or
`ADC <https://developer.apple.com/download/more/>`_ (AppleID required).
@@ -288,7 +321,7 @@ need to install Python 3.
* Type **xcode-select --install** to install additional tools necessary for MAME
(also available as a package on ADC).
-Next you’ll need to get SDL2 installed.
+Next you’ll need to get SDL 2 installed.
* Go to `this site <http://libsdl.org/download-2.0.php>`_ and download the
*macOS* .dmg file
@@ -298,12 +331,13 @@ Next you’ll need to get SDL2 installed.
**SDL2.framework** folder from the SDL disk image into the **Frameworks**
folder. You will have to authenticate with your user password.
-Now get Python 3 set up:
+If you don’t already have it, get Python 3 set up:
-* Go to the `official Python site <https://www.python.org/>`_ and click the link
- to the download page for the current version (this was
- `Python 3.10.0 <https://www.python.org/downloads/release/python-3100/>`_ at
- the time of writing).
+* Go to the official Python site, navigate to the
+ `releases for macOS <https://www.python.org/downloads/macos/>`_, and click the
+ link to download the installer for the latest stable release (this was
+ `Python 3.10.4 <https://www.python.org/ftp/python/3.10.4/python-3.10.4-macos11.pkg>`_
+ at the time of writing).
* Scroll down to the “Files” section, and download the macOS version (called
“macOS 64-bit universal2 installer” or similar).
* Once the package downloads, open it and follow the standard installation
@@ -330,7 +364,7 @@ MAME directory):
.. code-block:: bash
- emmake make SUBTARGET=pacmantest SOURCES=src/mame/drivers/pacman.cpp
+ emmake make SUBTARGET=pacmantest SOURCES=src/mame/pacman/pacman.cpp
The **SOURCES** parameter should have the path to at least one driver **.cpp**
file. The make process will attempt to locate and include all dependencies
@@ -340,7 +374,7 @@ commas) if this process misses something. e.g.
.. code-block:: bash
- emmake make SUBTARGET=apple2e SOURCES=src/mame/drivers/apple2e.cpp,src/mame/machine/applefdc.cpp
+ emmake make SUBTARGET=apple2e SOURCES=src/mame/apple/apple2e.cpp,src/devices/machine/applefdc.cpp
The value of the **SUBTARGET** parameter serves only to differentiate multiple
builds and need not be set to any specific value.
@@ -467,160 +501,198 @@ Overall build options
~~~~~~~~~~~~~~~~~~~~~
PREFIX_MAKEFILE
- Name of a makefile to include for additional options if found (defaults to
- **useroptions.mak**). May be useful if you want to quickly switch between
- different build configurations.
+ Name of a makefile to include for additional options if found (defaults to
+ **useroptions.mak**). May be useful if you want to quickly switch between
+ different build configurations.
BUILDDIR
- Set to change the name of the subfolder used for project files, generated
- sources, object files, and intermediate libraries (defaults to **build**).
+ Set to change the name of the subfolder used for project files, generated
+ sources, object files, and intermediate libraries (defaults to **build**).
REGENIE
- Set to **1** to force project files to be regenerated.
+ Set to **1** to force project files to be regenerated.
VERBOSE
- Set to **1** to show full commands when using GNU make as the build tool.
- This option applies immediately without needing regenerate project files.
+ Set to **1** to show full commands when using GNU make as the build tool.
+ This option applies immediately without needing regenerate project files.
IGNORE_GIT
- Set to **1** to skip the working tree scan and not attempt to embed a git
- revision description in the version string.
+ Set to **1** to skip the working tree scan and not attempt to embed a git
+ revision description in the version string.
Tool locations
~~~~~~~~~~~~~~
OVERRIDE_CC
- Set the C/Objective-C compiler command. (This sets the target C compiler
- command when cross-compiling.)
+ Set the C/Objective-C compiler command. (This sets the target C compiler
+ command when cross-compiling.)
OVERRIDE_CXX
- Set the C++/Objective-C++ compiler command. (This sets the target C++
- compiler command when cross-compiling.)
+ Set the C++/Objective-C++ compiler command. (This sets the target C++
+ compiler command when cross-compiling.)
OVERRIDE_LD
- Set the linker command. This is often not necessary or useful because the C
- or C++ compiler command is used to invoke the linker. (This sets the target
- linker command when cross-compiling.)
+ Set the linker command. This is often not necessary or useful because the C
+ or C++ compiler command is used to invoke the linker. (This sets the target
+ linker command when cross-compiling.)
PYTHON_EXECUTABLE
- Set the Python interpreter command. You need Python 3.2 or later to build
- MAME.
+ Set the Python interpreter command. You need Python 3.2 or later to build
+ MAME.
CROSS_BUILD
- Set to **1** to use separate host and target compilers and linkers, as
- required for cross-compilation. In this case, **OVERRIDE_CC**,
- **OVERRIDE_CXX** and **OVERRIDE_LD** set the target C compiler, C++ compiler
- and linker commands, while **CC**, **CXX** and **LD** set the host C
- compiler, C++ compiler and linker commands.
+ Set to **1** to use separate host and target compilers and linkers, as
+ required for cross-compilation. In this case, **OVERRIDE_CC**,
+ **OVERRIDE_CXX** and **OVERRIDE_LD** set the target C compiler, C++ compiler
+ and linker commands, while **CC**, **CXX** and **LD** set the host C
+ compiler, C++ compiler and linker commands.
+
+Including subsets of supported systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SUBTARGET
+ Set emulator subtarget to build. Some pre-defined subtargets are provided,
+ using Lua scripts in *scripts/target/mame* and system driver filter files in
+ *src/mame*. User-defined substargets can be created using the **SOURCES**
+ or **SOURCEFILTER** option.
+SOURCES
+ Specify system driver source files and/or folders to include. Usually used
+ in conjunction with the **SUBTARGET** option. Separate multiple
+ files/folders with commas.
+SOURCEFILTER
+ Specify a system driver filter file. Usually used in conjunction with the
+ **SUBTARGET** option. The filter file can specify source files to include
+ system drivers from, and individual system drivers to include or exclude.
+ There are some example system driver filter files in the *src/mame* folder.
Optional features
~~~~~~~~~~~~~~~~~
TOOLS
- Set to **1** to build additional tools along with the emulator, including
- **unidasm**, **chdman**, **romcmp**, and **srcclean**.
+ Set to **1** to build additional tools along with the emulator, including
+ **unidasm**, **chdman**, **romcmp**, and **srcclean**.
+EMULATOR
+ When set to **0**, the main emulator target will not be created. This is
+ intended to be used in conjunction with setting **TOOLS** to **1** to build
+ the additional tools without building the emulator.
+NO_OPENGL
+ Set to **1** to disable building the OpenGL video output module.
NO_USE_PORTAUDIO
- Set to **1** to disable building the PortAudio sound output module.
+ Set to **1** to disable building the PortAudio sound output module and the
+ PortAudio library.
+NO_USE_PULSEAUDIO
+ Set to **1** to disable building the PulseAudio sound output module on
+ Linux.
+USE_WAYLAND
+ Set to **1** to include support for bgfx video output with the Wayland
+ display server.
+USE_TAPTUN
+ Set to **1** to include the tap/tun network module, or set to **0** to
+ disable building the tap/tun network module. The tap/tun network module is
+ included by default on Windows and Linux.
+USE_PCAP
+ Set to **1** to include the pcap network module, or set to **0** to disable
+ building the pcap network module. The pcap network module is included by
+ default on macOS and NetBSD.
USE_QTDEBUG
- Set to **1** to include the Qt debugger on platforms where it’s not built by
- default (e.g. Windows or macOS), or to **0** to disable it. You’ll need to
- install Qt development libraries and tools to build the Qt debugger. The
- process depends on the platform.
+ Set to **1** to include the Qt debugger on platforms where it’s not built by
+ default (e.g. Windows or macOS), or to **0** to disable it. You’ll need to
+ install Qt development libraries and tools to build the Qt debugger. The
+ process depends on the platform.
Compilation options
~~~~~~~~~~~~~~~~~~~
NOWERROR
- Set to **1** to disable treating compiler warnings as errors. This may be
- needed in marginally supported configurations.
+ Set to **1** to disable treating compiler warnings as errors. This may be
+ needed in marginally supported configurations.
DEPRECATED
- Set to **0** to disable deprecation warnings (note that deprecation warnings
- are not treated as errors).
+ Set to **0** to disable deprecation warnings (note that deprecation warnings
+ are not treated as errors).
DEBUG
- Set to **1** to enable runtime assertion checks and additional diagnostics.
- Note that this has a performance cost, and is most useful for developers.
+ Set to **1** to enable runtime assertion checks and additional diagnostics.
+ Note that this has a performance cost, and is most useful for developers.
OPTIMIZE
- Set optimisation level. The default is **3** to favour performance at the
- expense of larger executable size. Set to **0** to disable optimisation (can
- make debugging easier), **1** for basic optimisation that doesn’t have a
- space/speed trade-off and doesn’t have a large impact on compile time, **2**
- to enable most optimisation that improves performance and reduces size, or
- **s** to enable only optimisations that generally don’t increase executable
- size. The exact set of supported values depends on your compiler.
+ Set optimisation level. The default is **3** to favour performance at the
+ expense of larger executable size. Set to **0** to disable optimisation
+ (can make debugging easier), **1** for basic optimisation that doesn’t have
+ a space/speed trade-off and doesn’t have a large impact on compile time,
+ **2** to enable most optimisation that improves performance and reduces
+ size, or **s** to enable only optimisations that generally don’t increase
+ executable size. The exact set of supported values depends on your
+ compiler.
SYMBOLS
- Set to **1** to include additional debugging symbols over the default for the
- target platform (many target platforms include function name symbols by
- default).
+ Set to **1** to include additional debugging symbols over the default for
+ the target platform (many target platforms include function name symbols by
+ default).
SYMLEVEL
- Numeric value that controls the level of detail in debugging symbols. Higher
- numbers make debugging easier at the cost of increased build time and
- executable size. The supported values depend on your compiler. For GCC and
- similar compilers, **1** includes line number tables and external variables,
- **2** also includes local variables, and **3** also includes macro
- definitions.
+ Numeric value that controls the level of detail in debugging symbols.
+ Higher numbers make debugging easier at the cost of increased build time and
+ executable size. The supported values depend on your compiler. For GCC and
+ similar compilers, **1** includes line number tables and external variables,
+ **2** also includes local variables, and **3** also includes macro
+ definitions.
ARCHOPTS
- Additional command-line options to pass to the compiler and linker. This is
- useful for supplying code generation or ABI options, for example to enable
- support for optional CPU features.
+ Additional command-line options to pass to the compiler and linker. This is
+ useful for supplying code generation or ABI options, for example to enable
+ support for optional CPU features.
ARCHOPTS_C
- Additional command-line options to pass to the compiler when compiling C
- source files.
+ Additional command-line options to pass to the compiler when compiling C
+ source files.
ARCHOPTS_CXX
- Additional command-line options to pass to the compiler when compiling C++
- source files.
+ Additional command-line options to pass to the compiler when compiling C++
+ source files.
ARCHOPTS_OBJC
- Additional command-line options to pass to the compiler when compiling
- Objective-C source files.
+ Additional command-line options to pass to the compiler when compiling
+ Objective-C source files.
ARCHOPTS_OBJCXX
- Additional command-line options to pass to the compiler when compiling
- Objective-C++ source files.
+ Additional command-line options to pass to the compiler when compiling
+ Objective-C++ source files.
Library/framework locations
~~~~~~~~~~~~~~~~~~~~~~~~~~~
SDL_INSTALL_ROOT
- SDL installation root directory for shared library style SDL.
+ SDL installation root directory for shared library style SDL.
SDL_FRAMEWORK_PATH
- Search path for SDL framework.
+ Search path for SDL framework.
USE_LIBSDL
- Set to **1** to use shared library style SDL on targets where framework is
- default.
+ Set to **1** to use shared library style SDL on targets where framework is
+ default.
USE_SYSTEM_LIB_ASIO
- Set to **1** to prefer the system installation of the Asio C++ asynchronous
- I/O library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the Asio C++ asynchronous
+ I/O library over the version provided with the MAME source.
USE_SYSTEM_LIB_EXPAT
- Set to **1** to prefer the system installation of the Expat XML parser
- library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the Expat XML parser
+ library over the version provided with the MAME source.
USE_SYSTEM_LIB_ZLIB
- Set to **1** to prefer the system installation of the zlib data compression
- library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the zlib data compression
+ library over the version provided with the MAME source.
+USE_SYSTEM_LIB_ZSTD
+ Set to **1** to prefer the system installation of the Zstandard data
+ compression library over the version provided with the MAME source.
USE_SYSTEM_LIB_JPEG
- Set to **1** to prefer the system installation of the libjpeg image
- compression library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the libjpeg image
+ compression library over the version provided with the MAME source.
USE_SYSTEM_LIB_FLAC
- Set to **1** to prefer the system installation of the libFLAC audio
- compression library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the libFLAC audio
+ compression library over the version provided with the MAME source.
USE_SYSTEM_LIB_LUA
- Set to **1** to prefer the system installation of the embedded Lua
- interpreter over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the embedded Lua
+ interpreter over the version provided with the MAME source.
USE_SYSTEM_LIB_SQLITE3
- Set to **1** to prefer the system installation of the SQLITE embedded
- database engine over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the SQLITE embedded
+ database engine over the version provided with the MAME source.
USE_SYSTEM_LIB_PORTMIDI
- Set to **1** to prefer the system installation of the PortMidi library over
- the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the PortMidi library over
+ the version provided with the MAME source.
USE_SYSTEM_LIB_PORTAUDIO
- Set to **1** to prefer the system installation of the PortAudio library over
- the version provided with the MAME source.
-USE_BUNDLED_LIB_SDL2
- Set to **1** to prefer the version of SDL provided with the MAME source over
- the system installation. (This is enabled by default for Visual Studio and
- Android builds. For other configurations, the system installation of SDL is
- preferred.)
+ Set to **1** to prefer the system installation of the PortAudio library over
+ the version provided with the MAME source.
USE_SYSTEM_LIB_UTF8PROC
- Set to **1** to prefer the system installation of the Julia utf8proc library
- over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the Julia utf8proc library
+ over the version provided with the MAME source.
USE_SYSTEM_LIB_GLM
- Set to **1** to prefer the system installation of the GLM OpenGL Mathematics
- library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the GLM OpenGL Mathematics
+ library over the version provided with the MAME source.
USE_SYSTEM_LIB_RAPIDJSON
- Set to **1** to prefer the system installation of the Tencent RapidJSON
- library over the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the Tencent RapidJSON
+ library over the version provided with the MAME source.
USE_SYSTEM_LIB_PUGIXML
- Set to **1** to prefer the system installation of the pugixml library over
- the version provided with the MAME source.
+ Set to **1** to prefer the system installation of the pugixml library over
+ the version provided with the MAME source.
.. _compiling-issues:
@@ -670,6 +742,31 @@ around it by adding **-U_FORTIFY_SOURCE** to the compiler flags (e.g. by using
the **ARCHOPTS** setting, or setting the **CFLAGS** and **CXXFLAGS** environment
variables.
+Issues affecting Microsoft Visual Studio
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Microsoft introduced a new version of XAudio2 with Windows 8 that’s incompatible
+with the version included with DirectX for prior Windows versions at the API
+level. Newer versions of the Microsoft Windows SDK include headers and libraries
+for the new version of XAudio2. By default, the target Windows version is set to
+Windows Vista (6.0) when compiling MAME, which prevents the use of this version
+of the XAudio2 headers and libraries. To build MAME with XAudio2 support using
+the Microsoft Windows SDK, you must do one of the following:
+
+* Add ``MODERN_WIN_API=1`` to the options passed to make when generating the
+ Visual Studio project files. This will set the target Windows version to
+ Windows 8 (6.2). The resulting binaries may not run on earlier versions of
+ Windows.
+* Install the DirectX SDL and configure the **osd_windows** project to search
+ the DirectX header/library paths before searching the Microsoft Windows SDK
+ paths.
+
+The MSVC compiler produces spurious warnings about potentially uninitialised
+local variables. You currently need to add ``NOWERROR=1`` to the options passed
+to make when generating the Visual Studio project files. This stops warnings
+from being treated as errors. (MSVC seems to lack options to control which
+specific warnings are treated as error, which other compilers support.)
+
.. _compiling-unusual:
diff --git a/docs/source/initialsetup/configuringmame.rst b/docs/source/initialsetup/configuringmame.rst
index a698113e69a..77eaf1e7a97 100644
--- a/docs/source/initialsetup/configuringmame.rst
+++ b/docs/source/initialsetup/configuringmame.rst
@@ -64,8 +64,3 @@ Choose **Save Configuration** to create the ``mame.ini`` file with default
settings. From here, you can either continue to configure things from the
graphical user interface or edit the ``mame.ini`` file in your favorite
text editor.
-
-
-Configuring MAME
-----------------
-
diff --git a/docs/source/license.rst b/docs/source/license.rst
index fd72712d9d8..aaffd97a169 100644
--- a/docs/source/license.rst
+++ b/docs/source/license.rst
@@ -12,7 +12,7 @@ would encourage new contributors to distribute files under this license.
Please note that MAME is a registered trademark of Gregory Ember, and permission
is required to use the “MAME” name, logo, or wordmark.
- Copyright (C) 1997-2021 MAMEDev and contributors
+ Copyright (c) 1997-2024 MAMEDev and contributors
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
diff --git a/docs/source/luascript/index.rst b/docs/source/luascript/index.rst
new file mode 100644
index 00000000000..7ba5a0a8caf
--- /dev/null
+++ b/docs/source/luascript/index.rst
@@ -0,0 +1,235 @@
+.. _luascript:
+
+Lua Scripting Interface
+=======================
+
+.. contents:: :local:
+
+
+.. _luascript-intro:
+
+Introduction
+------------
+
+MAME provides Lua script bindings for a useful set of core functionality. This
+feature first appeared in version 0.148, when a minimal Lua interface was
+implemented. Today, the Lua interface is rich enough to let you inspect and
+manipulate device state, access CPU registers, read and write memory, and draw
+custom graphical overlays.
+
+There are three ways to use MAME’s Lua scripting capabilities:
+
+* Using the :ref:`interactive Lua console <luascript-console>`, enabled by the
+ :ref:`console option <mame-commandline-console>`.
+* By providing a script file to run using the :ref:`-autoboot_script option
+ <mame-commandline-autobootscript>`. The :ref:`-autoboot_delay option
+ <mame-commandline-autobootdelay>` controls how long MAME waits after starting
+ the emulated system before running the script.
+* By writing :ref:`Lua plugins <plugins>`. Several plugins are included with
+ MAME.
+
+Internally, MAME makes extensive use of `Sol3 <https://github.com/ThePhD/sol2>`_
+to implement Lua bindings.
+
+The Lua API is not yet declared stable and may suddenly change without prior
+notice. However, we expose methods to let you know at runtime which API version
+you are running against, and most objects support some level of runtime
+introspection.
+
+
+.. _luascript-features:
+
+Features
+--------
+
+The API is not yet complete, but this is a partial list of capabilities exposed
+to Lua scripts:
+
+* Session information (application version, current emulated system)
+* Session control (starting, pausing, resetting, stopping)
+* Event hooks (on frame painting and on user events)
+* Device introspection (device tree listing, memory and register enumeration)
+* Screen introspection (screens listing, screen details, frame counting)
+* Screen overlay drawing (text, lines, boxes on multiple screens)
+* Memory read/write (8/16/32/64 bits, signed and unsigned)
+* Register and state control (state enumeration, get and set)
+
+
+.. _luascript-api:
+
+API reference
+-------------
+
+.. toctree::
+ :maxdepth: 2
+
+ ref-common
+ ref-core
+ ref-devices
+ ref-mem
+ ref-input
+ ref-render
+ ref-debugger
+
+
+.. _luascript-console:
+
+Interactive Lua console tutorial
+--------------------------------
+
+First run an arcade game in MAME at the command prompt with the ``-console``
+and ``-window`` options to enable the Lua console:
+
+::
+
+ $ mame -console -window YOUR_SYSTEM
+ /| /| /| /| /| _______
+ / | / | / | / | / | / /
+ / |/ | / | / |/ | / ____/
+ / | / | / | / /_
+ / |/ | / |/ __/
+ / /| /| /| |/ /| /| /____
+ / / | / | / | / | / | /
+ / _/ |/ / / |___/ |/ /_______/
+ / /
+ / _/
+
+ mame 0.255
+ Copyright (C) Nicola Salmoria and the MAME team
+
+ Lua 5.4
+ Copyright (C) Lua.org, PUC-Rio
+
+ [MAME]>
+
+At this point, your game is probably running in attract mode. Let’s pause it:
+
+::
+
+ [MAME]> emu.pause()
+ [MAME]>
+
+Even without textual feedback on the console, you’ll notice the game is now
+paused. In general, commands are quiet and only print error messages.
+
+You can check the version of MAME you are running with:
+
+::
+
+ [MAME]> print(emu.app_name() .. " " .. emu.app_version())
+ mame 0.255
+
+Let’s examine the emulated screens. First, enumerate the :ref:`screen devices
+<luascript-ref-screendev>` in the system:
+
+::
+
+ [MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end
+ :screen
+
+``manager.machine`` is the :ref:`running machine <luascript-ref-machine>` object
+for the current emulation session. We will be using this frequently.
+``screens`` is a :ref:`device enumerator <luascript-ref-devenum>` that yields
+all emulated screens in the system. Most arcade games only have one main
+screen. In our case, the main and only screen has the absolute tag ``:screen``.
+We can examine it further:
+
+::
+
+ [MAME]> -- keep a reference to the main screen in a variable
+ [MAME]> s = manager.machine.screens[':screen']
+ [MAME]> print(s.width .. 'x' .. s.height)
+ 320x224
+
+Several methods are available for drawing an overlay on the screen using lines,
+rectangles and text:
+
+::
+
+ [MAME]> -- define a function for drawing an overlay and call it
+ [MAME]> function draw_overlay()
+ [MAME]>> s:draw_text(40, 40, 'foo') -- (x0, y0, msg)
+ [MAME]>> s:draw_box(20, 20, 80, 80, 0xff00ffff, 0) -- (x0, y0, x1, y1, line-color, fill-color)
+ [MAME]>> s:draw_line(20, 20, 80, 80, 0xff00ffff) -- (x0, y0, x1, y1, line-color)
+ [MAME]>> end
+ [MAME]> draw_overlay()
+
+This will draw some useless lines and text over the screen. However, when the
+emulated system is resumed, your overlay needs to be refreshed or it will just
+disappear. In order to do this, you have to register your function to be called
+on every video update:
+
+::
+
+ [MAME]> emu.register_frame_done(draw_overlay, 'frame')
+
+All colors are specified in ARGB format (eight bits per channel). The
+coordinate origin (0,0) normally corresponds to the top-left corner of the
+screen.
+
+As with screens, you can examine all the emulated devices in the running system:
+
+::
+
+ [MAME]> for tag, device in pairs(manager.machine.devices) do print(tag) end
+ :audiocpu
+ :maincpu
+ :saveram
+ :screen
+ :palette
+ [...]
+
+For some of them, you can also inspect and manipulate memory and state:
+
+::
+
+ [MAME]> cpu = manager.machine.devices[':maincpu']
+ [MAME]> -- enumerate, read and write register state
+ [MAME]> for k, v in pairs(cpu.state) do print(k) end
+ CURPC
+ rPC
+ IR
+ CURFLAGS
+ SSR
+ D0
+ [...]
+ [MAME]> print(cpu.state["D0"].value)
+ 303
+ [MAME]> cpu.state['D0'].value = 255
+ [MAME]> print(cpu.state['D0'].value)
+ 255
+
+::
+
+ [MAME]> -- inspect memory
+ [MAME]> for name, space in pairs(cpu.spaces) do print(name) end
+ program
+ cpu_space
+ [MAME]> mem = cpu.spaces['program']
+ [MAME]> print(mem:read_i8(0xc000))
+ 41
+
+Note that many objects support symbol completion if you type part of a method or
+property name and press the Tab key:
+
+::
+
+ [MAME]>print(mem:read_<TAB>
+ read_direct_i8
+ read_u16
+ read_range
+ read_direct_u16
+ read_direct_i64
+ read_i64
+ read_i32
+ read_direct_u64
+ read_i8
+ read_u32
+ read_u8
+ read_u64
+ read_direct_u32
+ read_direct_i16
+ read_direct_i32
+ read_direct_u8
+ read_i16
+ [MAME]>print(mem:read_direct_i8
diff --git a/docs/source/luascript/ref-common.rst b/docs/source/luascript/ref-common.rst
new file mode 100644
index 00000000000..c08d3676621
--- /dev/null
+++ b/docs/source/luascript/ref-common.rst
@@ -0,0 +1,118 @@
+.. _luascript-ref-common:
+
+Lua Common Types and Globals
+============================
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-containers:
+
+Containers
+----------
+
+Many properties yield container wrappers. Container wrappers are cheap to
+create, and provide an interface that is similar to a read-only table. The
+complexity of operations may vary. Container wrappers usually provide most of
+these operations:
+
+#c
+ Get the number of items in the container.
+c[k]
+ Returns the item corresponding to the key ``k``, or ``nil`` if the key is
+ not present.
+pairs(c)
+ Iterate over container by key and value. The key is what you would pass to
+ the index operator or the ``get`` method to get the value.
+ipairs(c)
+ Iterate over container by index and value. The index is what you would pass
+ to the ``at`` method to get the value (this may be the same as the key for
+ some containers).
+c:empty()
+ Returns a Boolean indicating whether there are no items in the container.
+c:get(k)
+ Returns the item corresponding to the key ``k``, or ``nil`` if the key is
+ not present. Usually equivalent to the index operator.
+c:at(i)
+ Returns the value at the 1-based index ``i``, or ``nil`` if it is out of
+ range.
+c:find(v)
+ Returns the key for item ``v``, or ``nil`` if it is not in the container.
+ The key is what you would pass to the index operator to get the value.
+c:index_of(v)
+ Returns the 1-based index for item ``v``, or ``nil`` if it is not in the
+ container. The index is what you would pass to the ``at`` method to get the
+ value.
+
+
+.. _luascript-ref-emu:
+
+Emulator interface
+------------------
+
+The emulator interface ``emu`` provides access to core functionality. Many
+classes are also available as properties of the emulator interface.
+
+Methods
+~~~~~~~
+
+emu.wait(duration, …)
+ Yields for the specified duration in terms of emulated time. The duration
+ may be specified as an :ref:`attotime <luascript-ref-attotime>` or a number
+ in seconds. Any additional arguments are returned from the coroutine.
+ Returns a Boolean indicating whether the duration expired normally.
+
+ All outstanding calls to ``emu.wait`` will return ``false`` immediately if a
+ saved state is loaded or the emulation session ends. Calling this function
+ from callbacks that are not run as coroutines will raise an error.
+emu.wait_next_update(…)
+ Yields until the next video/UI update. Any arguments are returned from the
+ coroutine. Calling this function from callbacks that are not run as coroutines
+ will raise an error.
+emu.wait_next_frame(…)
+ Yields until the next emulated frame completes. Any arguments are returned
+ from the coroutine. Calling this function from callbacks that are not run as
+ coroutines will raise an error.
+emu.add_machine_reset_notifier(callback)
+ Add a callback to receive notifications when the emulated system is reset.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_stop_notifier(callback)
+ Add a callback to receive notifications when the emulated system is stopped.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_pause_notifier(callback)
+ Add a callback to receive notifications when the emulated system is paused.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_resume_notifier(callback)
+ Add a callback to receive notifications when the emulated system is resumed
+ after being paused. Returns a
+ :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_frame_notifier(callback)
+ Add a callback to receive notifications when an emulated frame completes.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_pre_save_notifier(callback)
+ Add a callback to receive notification before the emulated system state is
+ saved. Returns a
+ :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.add_machine_post_load_notifier(callback)
+ Add a callback to receive notification after the emulated system is restored
+ to a previously saved state. Returns a
+ :ref:`notifier subscription <luascript-ref-notifiersub>`.
+emu.print_error(message)
+ Print an error message.
+emu.print_warning(message)
+ Print a warning message.
+emu.print_info(message)
+ Print an informational message.
+emu.print_verbose(message)
+ Print a verbose diagnostic message (disabled by default).
+emu.print_debug(message)
+ Print a debug message (only enabled for debug builds by default).
+emu.lang_translate([context], message)
+ Look up a message with optional context in the current localised message
+ catalog. Returns the message unchanged if no corresponding localised
+ message is found.
+emu.subst_env(string)
+ Substitute environment variables in a string. The syntax is dependent on
+ the host operating system.
diff --git a/docs/source/luascript/ref-core.rst b/docs/source/luascript/ref-core.rst
new file mode 100644
index 00000000000..f761b20f5de
--- /dev/null
+++ b/docs/source/luascript/ref-core.rst
@@ -0,0 +1,635 @@
+.. _luascript-ref-core:
+
+Lua Core Classes
+================
+
+Many of MAME’s core classes used to implement an emulation session are available
+to Lua scripts.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-notifiersub:
+
+Notifier subscription
+---------------------
+
+Wraps MAME’s ``util::notifier_subscription`` class, which manages a subscription
+to a broadcast notification.
+
+Methods
+~~~~~~~
+
+subscription:unsubscribe()
+ Unsubscribes from notifications. The subscription will become inactive and
+ no future notifications will be received.
+
+Properties
+~~~~~~~~~~
+
+subscription.is_active (read-only)
+ A Boolean indicating whether the subscription is active. A subscription
+ becomes inactive after explicitly unsubscribing or if the underlying
+ notifier is destroyed.
+
+
+.. _luascript-ref-attotime:
+
+Attotime
+--------
+
+Wraps MAME’s ``attotime`` class, which represents a high-precision time
+interval. Attotime values support addition and subtraction with other attotime
+values, and multiplication and division by integers.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.attotime()
+ Creates an attotime value representing zero (i.e. no elapsed time).
+emu.attotime(seconds, attoseconds)
+ Creates an attotime with the specified whole and fractional parts.
+emu.attotime(attotime)
+ Creates a copy of an existing attotime value.
+emu.attotime.from_double(seconds)
+ Creates an attotime value representing the specified number of seconds.
+emu.attotime.from_ticks(periods, frequency)
+ Creates an attotime representing the specified number of periods of the
+ specified frequency in Hertz.
+emu.attotime.from_seconds(seconds)
+ Creates an attotime value representing the specified whole number of
+ seconds.
+emu.attotime.from_msec(milliseconds)
+ Creates an attotime value representing the specified whole number of
+ milliseconds.
+emu.attotime.from_usec(microseconds)
+ Creates an attotime value representing the specified whole number of
+ microseconds.
+emu.attotime.from_nsec(nanoseconds)
+ Creates an attotime value representing the specified whole number of
+ nanoseconds.
+
+Methods
+~~~~~~~
+
+t:as_double()
+ Returns the time interval in seconds as a floating-point value.
+t:as_hz()
+ Interprets the interval as a period and returns the corresponding frequency
+ in Hertz as a floating-point value. Returns zero if ``t.is_never`` is true.
+ The interval must not be zero.
+t:as_khz()
+ Interprets the interval as a period and returns the corresponding frequency
+ kilohertz as a floating-point value. Returns zero if ``t.is_never`` is
+ true. The interval must not be zero.
+t:as_mhz()
+ Interprets the interval as a period and returns the corresponding frequency
+ megahertz as a floating-point value. Returns zero if ``t.is_never`` is
+ true. The interval must not be zero.
+t:as_ticks(frequency)
+ Returns the interval as a whole number of periods at the specified
+ frequency. The frequency is specified in Hertz.
+
+Properties
+~~~~~~~~~~
+
+t.is_zero (read-only)
+ A Boolean indicating whether the value represents no elapsed time.
+t.is_never (read-only)
+ A Boolean indicating whether the value is greater than the maximum number of
+ whole seconds that can be represented (treated as an unreachable time in the
+ future or overflow).
+t.attoseconds (read-only)
+ The fraction seconds portion of the interval in attoseconds.
+t.seconds (read-only)
+ The number of whole seconds in the interval.
+t.msec (read-only)
+ The number of whole milliseconds in the fractional seconds portion of the
+ interval.
+t.usec (read-only)
+ The number of whole microseconds in the fractional seconds portion of the
+ interval.
+t.nsec (read-only)
+ The number of whole nanoseconds in the fractional seconds portion of the
+ interval.
+
+
+.. _luascript-ref-mameman:
+
+MAME machine manager
+--------------------
+
+Wraps MAME’s ``mame_machine_manager`` class, which holds the running machine, UI
+manager, and other global components.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager
+ The MAME machine manager is available as a global variable in the Lua
+ environment.
+
+Properties
+~~~~~~~~~~
+
+manager.machine (read-only)
+ The :ref:`running machine <luascript-ref-machine>` for the current emulation
+ session.
+manager.ui (read-only)
+ The :ref:`UI manager <luascript-ref-uiman>` for the current session.
+manager.options (read-only)
+ The :ref:`emulation options <luascript-ref-emuopts>` for the current
+ session.
+manager.plugins[] (read-only)
+ Gets information about the :ref:`Lua plugins <luascript-ref-plugin>` that
+ are present, indexed by name. The index get, ``at`` and ``index_of``
+ methods have O(n) complexity.
+
+
+.. _luascript-ref-machine:
+
+Running machine
+---------------
+
+Wraps MAME’s ``running_machine`` class, which represents an emulation session.
+It provides access to the other core objects that implement an emulation session
+as well as the emulated device tree.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine
+ Gets the running machine instance for the current emulation session.
+
+Methods
+~~~~~~~
+
+machine:exit()
+ Schedules an exit from the current emulation session. This will either
+ return to the system selection menu or exit the application, depending on
+ how it was started. This method returns immediately, before the scheduled
+ exit takes place.
+machine:hard_reset()
+ Schedules a hard reset. This is implemented by tearing down the emulation
+ session and starting another emulation session for the same system. This
+ method returns immediately, before the scheduled reset takes place.
+machine:soft_reset()
+ Schedules a soft reset. This is implemented by calling the reset method of
+ the root device, which is propagated down the device tree. This method
+ returns immediately, before the scheduled reset takes place.
+machine:save(filename)
+ Schedules saving machine state to the specified file. If the file name is a
+ relative path, it is considered to be relative to the first configured save
+ state directory. This method returns immediately, before the machine state
+ is saved. If this method is called when a save or load operation is already
+ pending, the previously pending operation will be cancelled.
+machine:load(filename)
+ Schedules loading machine state from the specified file. If the file name
+ is a relative path, the configured save state directories will be searched.
+ This method returns immediately, before the machine state is saved. If this
+ method is called when a save or load operation is already pending, the
+ previously pending operation will be cancelled.
+machine:popmessage([msg])
+ Displays a pop-up message to the user. If the message is not provided, the
+ currently displayed pop-up message (if any) will be hidden.
+machine:logerror(msg)
+ Writes the message to the machine error log. This may be displayed in a
+ debugger window, written to a file, or written to the standard error output.
+
+Properties
+~~~~~~~~~~
+
+machine.time (read-only)
+ The elapsed emulated time for the current session as an
+ :ref:`attotime <luascript-ref-attotime>`.
+machine.system (read-only)
+ The :ref:`driver metadata <luascript-ref-driver>` for the current
+ system.
+machine.parameters (read-only)
+ The :ref:`parameters manager <luascript-ref-paramman>` for the current
+ emulation session.
+machine.video (read-only)
+ The :ref:`video manager <luascript-ref-videoman>` for the current emulation
+ session.
+machine.sound (read-only)
+ The :ref:`sound manager <luascript-ref-soundman>` for the current emulation
+ session.
+machine.output (read-only)
+ The :ref:`output manager <luascript-ref-outputman>` for the current
+ emulation session.
+machine.memory (read-only)
+ The :ref:`emulated memory manager <luascript-ref-memman>` for the current
+ session.
+machine.ioport (read-only)
+ The :ref:`I/O port manager <luascript-ref-ioportman>` for the current
+ emulation session.
+machine.input (read-only)
+ The :ref:`input manager <luascript-ref-inputman>` for the current emulation
+ session.
+machine.natkeyboard (read-only)
+ Gets the :ref:`natural keyboard manager <luascript-ref-natkbdman>`, used for
+ controlling keyboard and keypad input to the emulated system.
+machine.uiinput (read-only)
+ The :ref:`UI input manager <luascript-ref-uiinputman>` for the current
+ emulation session.
+machine.render (read-only)
+ The :ref:`render manager <luascript-ref-renderman>` for the current
+ emulation session.
+machine.debugger (read-only)
+ The :ref:`debugger manager <luascript-ref-debugman>` for the current
+ emulation session, or ``nil`` if the debugger is not enabled.
+machine.options (read-only)
+ The user-specified :ref:`options <luascript-ref-emuopts>` for the current
+ emulation session.
+machine.samplerate (read-only)
+ The output audio sample rate in Hertz.
+machine.paused (read-only)
+ A Boolean indicating whether emulation is not currently running, usually
+ because the session has been paused or the emulated system has not completed
+ starting.
+machine.exit_pending (read-only)
+ A Boolean indicating whether the emulation session is scheduled to exit.
+machine.hard_reset_pending (read-only)
+ A Boolean indicating whether a hard reset of the emulated system is pending.
+machine.devices (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`devices <luascript-ref-device>` in the emulated system.
+machine.palettes (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`palette devices <luascript-ref-dipalette>` in the emulated system.
+machine.screens (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`screen devices <luascript-ref-screendev>` in the emulated system.
+machine.cassettes (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`cassette image devices <luascript-ref-cassdev>` in the emulated
+ system.
+machine.images (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`media image devices <luascript-ref-diimage>` in the emulated system.
+machine.slots (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`slot devices <luascript-ref-dislot>` in the emulated system.
+
+
+.. _luascript-ref-videoman:
+
+Video manager
+-------------
+
+Wraps MAME’s ``video_manager`` class, which is responsible for coordinating
+emulated video drawing, speed throttling, and reading host inputs.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.video
+ Gets the video manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+video:frame_update()
+ Updates emulated screens, reads host inputs, and updates video output.
+video:snapshot()
+ Saves snapshot files according to the current configuration. If MAME is
+ configured to take native emulated screen snapshots, one snapshot will be
+ saved for each emulated screen that is visible in a host window/screen with
+ the current view configuration. If MAME is not configured to use take
+ native emulated screen snapshots or if the system has no emulated screens, a
+ single snapshot will be saved using the currently selected snapshot view.
+video:begin_recording([filename], [format])
+ Stops any video recordings currently in progress and starts recording either
+ the visible emulated screens or the current snapshot view, depending on
+ whether MAME is configured to take native emulated screen snapshots.
+
+ If the file name is not supplied, the configured snapshot file name is used.
+ If the file name is a relative path, it is interpreted relative to the first
+ configured snapshot directory. If the format is supplied, it must be
+ ``"avi"`` or ``"mng"``. If the format is not supplied, it defaults to AVI.
+video:end_recording()
+ Stops any video recordings that are in progress.
+video:snapshot_size()
+ Returns the width and height in pixels of snapshots created with the current
+ snapshot target configuration and emulated screen state. This may be
+ configured explicitly by the user, or calculated based on the selected
+ snapshot view and the resolution of any visible emulated screens.
+video:snapshot_pixels()
+ Returns the pixels of a snapshot created using the current snapshot target
+ configuration as 32-bit integers packed into a binary string in host Endian
+ order. Pixels are organised in row-major order, from left to right then top
+ to bottom. Pixel values are colours in RGB format packed into 32-bit
+ integers.
+
+Properties
+~~~~~~~~~~
+
+video.speed_factor (read-only)
+ Configured emulation speed adjustment in per mille (i.e. the ratio to normal
+ speed multiplied by 1,000).
+video.throttled (read/write)
+ A Boolean indicating whether MAME should wait before video updates to avoid
+ running faster than the target speed.
+video.throttle_rate (read/write)
+ The target emulation speed as a ratio of full speed adjusted by the speed
+ factor (i.e. 1 is normal speed adjusted by the speed factor, larger numbers
+ are faster, and smaller numbers are slower).
+video.frameskip (read/write)
+ The number of emulated video frames to skip drawing out of every twelve, or
+ -1 to automatically adjust the number of frames to skip to maintain the
+ target emulation speed.
+video.speed_percent (read-only)
+ The current emulated speed as a percentage of the full speed adjusted by the
+ speed factor.
+video.effective_frameskip (read-only)
+ The number of emulated frames that are skipped out of every twelve.
+video.skip_this_frame (read-only)
+ A Boolean indicating whether the video manager will skip drawing emulated
+ screens for the current frame.
+video.snap_native (read-only)
+ A Boolean indicating whether the video manager will take native emulated
+ screen snapshots. In addition to the relevant configuration setting, the
+ emulated system must have at least one emulated screen.
+video.is_recording (read-only)
+ A Boolean indicating whether any video recordings are currently in progress.
+video.snapshot_target (read-only)
+ The :ref:`render target <luascript-ref-rendertarget>` used to produce
+ snapshots and video recordings.
+
+
+.. _luascript-ref-soundman:
+
+Sound manager
+-------------
+
+Wraps MAME’s ``sound_manager`` class, which manages the emulated sound stream
+graph and coordinates sound output.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.sound
+ Gets the sound manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+sound:start_recording([filename])
+ Starts recording to a WAV file. Has no effect if currently recording. If
+ the file name is not supplied, uses the configured WAV file name (from
+ command line or INI file), or has no effect if no WAV file name is
+ configured. Returns ``true`` if recording started, or ``false`` if
+ recording is already in progress, opening the output file failed, or no file
+ name was supplied or configured.
+sound:stop_recording()
+ Stops recording and closes the file if currently recording to a WAV file.
+sound:get_samples()
+ Returns the current contents of the output sample buffer as a binary string.
+ Samples are 16-bit integers in host byte order. Samples for left and right
+ stereo channels are interleaved.
+
+Properties
+~~~~~~~~~~
+
+sound.muted (read-only)
+ A Boolean indicating whether sound output is muted for any reason.
+sound.ui_mute (read/write)
+ A Boolean indicating whether sound output is muted at the request of the
+ user.
+sound.debugger_mute (read/write)
+ A Boolean indicating whether sound output is muted at the request of the
+ debugger.
+sound.system_mute (read/write)
+ A Boolean indicating whether sound output is muted at the request of the
+ emulated system.
+sound.attenuation (read/write)
+ The output volume attenuation in decibels. Should generally be a negative
+ integer or zero.
+sound.recording (read-only)
+ A Boolean indicating whether sound output is currently being recorded to a
+ WAV file.
+
+
+.. _luascript-ref-outputman:
+
+Output manager
+--------------
+
+Wraps MAME’s ``output_manager`` class, providing access to system outputs that
+can be used for interactive artwork or consumed by external programs.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.output
+ Gets the output manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+output:set_value(name, val)
+ Sets the specified output value. The value must be an integer. The output
+ will be created if it does not already exist.
+output:set_indexed_value(prefix, index, val)
+ Appends the index (formatted as a decimal integer) to the prefix and sets
+ the value of the corresponding output. The value must be an integer. The
+ output will be created if it does not already exist.
+output:get_value(name)
+ Returns the value of the specified output, or zero if it doesn’t exist.
+output:get_indexed_value(prefix, index)
+ Appends the index (formatted as a decimal integer) to the prefix and returns
+ the value of the corresponding output, or zero if it doesn’t exist.
+output:name_to_id(name)
+ Gets the per-session unique integer ID for the specified output, or zero if
+ it doesn’t exist.
+output:id_to_name(id)
+ Gets the name for the output with the specified per-session unique ID, or
+ ``nil`` if it doesn’t exist. This method has O(n) complexity, so avoid
+ calling it when performance is important.
+
+
+.. _luascript-ref-paramman:
+
+Parameters manager
+------------------
+
+Wraps MAME’s ``parameters_manager`` class, which provides a simple key-value
+store for metadata from system ROM definitions.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.parameters
+ Gets the parameters manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+parameters:lookup(tag)
+ Gets the value for the specified parameter if it is set, or an empty string
+ if it is not set.
+parameters:add(tag, value)
+ Sets the specified parameter if it is not set. Has no effect if the
+ specified parameter is already set.
+
+
+.. _luascript-ref-uiman:
+
+UI manager
+----------
+
+Wraps MAME’s ``mame_ui_manager`` class, which handles menus and other user
+interface functionality.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.ui
+ Gets the UI manager for the current session.
+
+Methods
+~~~~~~~
+
+ui:get_char_width(ch)
+ Gets the width of a Unicode character as a proportion of the width of the UI
+ container in the current font at the configured UI line height.
+ui:get_string_width(str)
+ Gets the width of a string as a proportion of the width of the UI container
+ in the current font at the configured UI line height.
+ui:set_aggressive_input_focus(enable)
+ On some platforms, this controls whether MAME should accept input focus in
+ more situations than when its windows have UI focus.
+ui:get_general_input_setting(type, [player])
+ Gets a description of the configured
+ :ref:`input sequence <luascript-ref-inputseq>` for the specified input type
+ and player suitable for using in prompts. The input type is an enumerated
+ value. The player number is a zero-based index. If the player number is
+ not supplied, it is assumed to be zero.
+
+Properties
+~~~~~~~~~~
+
+ui.options (read-only)
+ The UI :ref:`options <luascript-ref-coreopts>` for the current session.
+ui.line_height (read-only)
+ The configured UI text line height as a proportion of the height of the UI
+ container.
+ui.menu_active (read-only)
+ A Boolean indicating whether an interactive UI element is currently active.
+ Examples include menus and slider controls.
+ui.ui_active (read/write)
+ A Boolean indicating whether UI control inputs are currently enabled.
+ui.single_step (read/write)
+ A Boolean controlling whether the emulated system should be automatically
+ paused when the next frame is drawn. This property is automatically reset
+ when the automatic pause happens.
+ui.show_fps (read/write)
+ A Boolean controlling whether the current emulation speed and frame skipping
+ settings should be displayed.
+ui.show_profiler (read/write)
+ A Boolean controlling whether profiling statistics should be displayed.
+
+
+.. _luascript-ref-driver:
+
+System driver metadata
+----------------------
+
+Provides some metadata for an emulated system.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.driver_find(name)
+ Gets the driver metadata for the system with the specified short name, or
+ ``nil`` if no such system exists.
+manager.machine.system
+ Gets the driver metadata for the current system.
+
+Properties
+~~~~~~~~~~
+
+driver.name (read-only)
+ The short name of the system, as used on the command line, in configuration
+ files, and when searching for resources.
+driver.description (read-only)
+ The full display name for the system.
+driver.year (read-only)
+ The release year for the system. May contain question marks if not known
+ definitively.
+driver.manufacturer (read-only)
+ The manufacturer, developer or distributor of the system.
+driver.parent (read-only)
+ The short name of parent system for organisation purposes, or ``"0"`` if the
+ system has no parent.
+driver.compatible_with (read-only)
+ The short name of a system that this system is compatible with software for,
+ or ``nil`` if the system is not listed as compatible with another system.
+driver.source_file (read-only)
+ The source file where this system driver is defined. The path format
+ depends on the toolchain the emulator was built with.
+driver.rotation (read-only)
+ A string indicating the rotation applied to all screens in the system after
+ the screen orientation specified in the machine configuration is applied.
+ Will be one of ``"rot0"``, ``"rot90"``, ``"rot180"`` or ``"rot270"``.
+driver.not_working (read-only)
+ A Boolean indicating whether the system is marked as not working.
+driver.supports_save (read-only)
+ A Boolean indicating whether the system supports save states.
+driver.no_cocktail (read-only)
+ A Boolean indicating whether screen flipping in cocktail mode is
+ unsupported.
+driver.is_bios_root (read-only)
+ A Boolean indicating whether this system represents a system that runs
+ software from removable media without media present.
+driver.requires_artwork (read-only)
+ A Boolean indicating whether the system requires external artwork to be
+ usable.
+driver.clickable_artwork (read-only)
+ A Boolean indicating whether the system requires clickable artwork features
+ to be usable.
+driver.unofficial (read-only)
+ A Boolean indicating whether this is an unofficial but common user
+ modification to a system.
+driver.no_sound_hw (read-only)
+ A Boolean indicating whether the system has no sound output hardware.
+driver.mechanical (read-only)
+ A Boolean indicating whether the system depends on mechanical features that
+ cannot be properly simulated.
+driver.is_incomplete (read-only)
+ A Boolean indicating whether the system is a prototype with incomplete
+ functionality.
+
+
+.. _luascript-ref-plugin:
+
+Lua plugin
+----------
+
+Provides a description of an available Lua plugin.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.plugins[name]
+ Gets the description of the Lua plugin with the specified name, or ``nil``
+ if no such plugin is available
+
+Properties
+~~~~~~~~~~
+
+plugin.name (read-only)
+ The short name of the plugin, used in configuration and when accessing the
+ plugin programmatically.
+plugin.description (read-only)
+ The display name for the plugin.
+plugin.type (read-only)
+ The plugin type. May be ``"plugin"`` for user-loadable plugins, or
+ ``"library"`` for libraries providing common functionality to multiple
+ plugins.
+plugin.directory (read-only)
+ The path to the directory containing the plugin’s files.
+plugin.start (read-only)
+ A Boolean indicating whether the plugin enabled.
diff --git a/docs/source/luascript/ref-debugger.rst b/docs/source/luascript/ref-debugger.rst
new file mode 100644
index 00000000000..e347b7303ff
--- /dev/null
+++ b/docs/source/luascript/ref-debugger.rst
@@ -0,0 +1,451 @@
+.. _luascript-ref-debugger:
+
+Lua Debugger Classes
+====================
+
+Some of MAME’s core debugging features can be controlled from Lua script. The
+debugger must be enabled to use the debugger features (usually by passing
+``-debug`` on the command line).
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-debugsymtable:
+
+Symbol table
+------------
+
+Wrap’s MAME’s ``symbol_table`` class, providing named symbols that can be used
+in expressions. Note that symbol tables can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.symbol_table(machine)
+ Creates a new symbol table in the context of the specified machine,
+emu.symbol_table(parent, [device])
+ Creates a new symbol table with the specified parent symbol table. If a
+ device is specified and it implements ``device_memory_interface``, it will
+ be used as the base for looking up address spaces and memory regions. Note
+ that if a device that does not implement ``device_memory_interface`` is
+ supplied, it will not be used (address spaces and memory regions will be
+ looked up relative to the root device).
+emu.symbol_table(device)
+ Creates a new symbol table in the context of the specified device. If the
+ device implements ``device_memory_interface``, it will be used as the base
+ for looking up address spaces and memory regions. Note that if a device
+ that does not implement ``device_memory_interface`` is supplied, it will
+ only be used to determine the machine context (address spaces and memory
+ regions will be looked up relative to the root device).
+
+Methods
+~~~~~~~
+
+symbols:set_memory_modified_func(cb)
+ Set a function to call when memory is modified via the symbol table. No
+ arguments are passed to the function and any return values are ignored.
+ Call with ``nil`` to remove the callback.
+symbols:add(name, [value])
+ Adds a named integer symbol. The name must be a string. If a value is
+ supplied, it must be an integer. If a value is supplied, a read-only symbol
+ is added with the supplied value. If no value is supplied, a read/write
+ symbol is created with and initial value of zero. If a symbol entry with
+ the specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:add(name, getter, [setter], [format])
+ Adds a named integer symbol using getter and optional setter callbacks. The
+ name must be a string. The getter must be a function returning an integer
+ for the symbol value. If supplied, the setter must be a function that
+ accepts a single integer argument for the new value of the symbol. A format
+ string for displaying the symbol value may optionally be supplied. If a
+ symbol entry with the specified name already exists in the symbol table, it
+ will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:add(name, minparams, maxparams, execute)
+ Adds a named function symbol. The name must be a string. The minimum and
+ maximum numbers of parameters must be integers. If a symbol entry with the
+ specified name already exists in the symbol table, it will be replaced.
+
+ Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
+symbols:find(name)
+ Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table.
+symbols:find_deep(name)
+ Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
+ specified name, or ``nil`` if there is no symbol with the specified name in
+ the symbol table or any of its parent symbol tables.
+symbols:value(name)
+ Returns the integer value of the symbol with the specified name, or zero if
+ there is no symbol with the specified name in the symbol table or any of its
+ parent symbol tables. Raises an error if the symbol with specified name is
+ a function symbol.
+symbols:set_value(name, value)
+ Sets the value of the symbol with the specified name. Raises an error if
+ the symbol with the specified name is a read-only integer symbol or if it is
+ a function symbol. Has no effect if there is no symbol with the specified
+ name in the symbol table or any of its parent symbol tables.
+symbols:memory_value(name, space, offset, size, disable_se)
+ Read a value from memory. Supply the name or tag of the address space or
+ memory region to read from, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:set_memory_value(name, space, offset, value, size, disable_se)
+ Write a value to memory. Supply the name or tag of the address space or
+ memory region to write to, or ``nil`` to use the address space or memory
+ region implied by the ``space`` argument. See
+ :ref:`memory accesses in debugger expressions <debugger-express-mem>` for
+ access type specifications that can be used for the ``space`` argument.
+ The access size is specified in bytes, and must be 1, 2, 4 or 8. The
+ ``disable_se`` argument specifies whether memory access side effects should
+ be disabled.
+symbols:read_memory(space, address, size, apply_translation)
+ Read a value from an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug read intention. Returns a value
+ of the requested size with all bits set if address translation fails.
+symbols:write_memory(space, address, data, size, apply_translation)
+ Write a value to an address space. The access size is specified in bytes,
+ and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
+ the address will be translated with debug write intention. The symbol
+ table’s memory modified function will be called after the value is written.
+ The value will not be written and the symbol table’s memory modified
+ function will not be called if address translation fails.
+
+Properties
+~~~~~~~~~~
+
+symbols.entries[]
+ The :ref:`symbol entries <luascript-ref-debugsymentry>` in the symbol table,
+ indexed by name. The ``at`` and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+symbols.parent (read-only)
+ The parent symbol table, or ``nil`` if the symbol table has no parent.
+
+
+.. _luascript-ref-debugexpression:
+
+Parsed expression
+-----------------
+
+Wraps MAME’s ``parsed_expression`` class, which represents a tokenised debugger
+expression. Note that parsed expressions can be created and used even when the
+debugger is not enabled.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.parsed_expression(symbols)
+ Creates an empty expression that will use the supplied
+ :ref:`symbol table <luascript-ref-debugsymtable>` to look up symbols.
+emu.parsed_expression(symbols, string, [default_base])
+ Creates an expression by parsing the supplied string, looking up symbols in
+ the supplied :ref:`symbol table <luascript-ref-debugsymtable>`. If the
+ default base for interpreting integer literals is not supplied, 16 is used
+ (hexadecimal). Raises an :ref:`expression error
+ <luascript-ref-debugexpressionerror>` if the string contains syntax errors
+ or uses undefined symbols.
+
+Methods
+~~~~~~~
+
+expression:set_default_base(base)
+ Set the default base for interpreting numeric literals. The base must be a
+ positive integer.
+expression:parse(string)
+ Parse a debugger expression string. Replaces the current contents of the
+ expression if it is not empty. Raises an :ref:`expression error
+ <luascript-ref-debugexpressionerror>` if the string contains syntax errors
+ or uses undefined symbols. The previous content of the expression is not
+ preserved when attempting to parse an invalid expression string.
+expression:execute()
+ Evaluates the expression, returning an unsigned integer result. Raises an
+ :ref:`expression error <luascript-ref-debugexpressionerror>` if the
+ expression cannot be evaluated (e.g. attempting to call a function with an
+ invalid number of arguments).
+
+Properties
+~~~~~~~~~~
+
+expression.is_empty (read-only)
+ A Boolean indicating whether the expression contains no tokens.
+expression.original_string (read-only)
+ The original string that was parsed to create the expression.
+expression.symbols (read/write)
+ The :ref:`symbol table <luascript-ref-debugsymtable>` used for to look up
+ symbols in the expression.
+
+
+.. _luascript-ref-debugsymentry:
+
+Symbol entry
+------------
+
+Wraps MAME’s ``symbol_entry`` class, which represents an entry in a
+:ref:`symbol table <luascript-ref-debugsymtable>`. Note that symbol entries
+must not be used after the symbol table they belong to is destroyed.
+
+Instantiation
+~~~~~~~~~~~~~
+
+symbols:add(name, [value])
+ Adds an integer symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+symbols:add(name, getter, [setter], [format])
+ Adds an integer symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+symbols:add(name, minparams, maxparams, execute)
+ Adds function symbol to a
+ :ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
+ entry.
+
+Properties
+~~~~~~~~~~
+
+entry.name (read-only)
+ The name of the symbol entry.
+entry.format (read-only)
+ The format string used to convert the symbol entry to text for display.
+entry.is_function (read-only)
+ A Boolean indicating whether the symbol entry is a callable function.
+entry.is_lval (read-only)
+ A Boolean indicating whether the symbol entry is an integer symbol that can
+ be set (i.e. whether it can be used on the left-hand side of assignment
+ expressions).
+entry.value (read/write)
+ The integer value of the symbol entry. Attempting to set the value raises
+ an error if the symbol entry is read-only. Attempting to get or set the
+ value of a function symbol raises an error.
+
+
+.. _luascript-ref-debugman:
+
+Debugger manager
+----------------
+
+Wraps MAME’s ``debugger_manager`` class, providing the main interface to control
+the debugger.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.debugger
+ Returns the global debugger manager instance, or ``nil`` if the debugger is
+ not enabled.
+
+Methods
+~~~~~~~
+
+debugger:command(str)
+ Execute a debugger console command. The argument is the command string.
+ The output is sent to both the debugger console and the Lua console.
+
+Properties
+~~~~~~~~~~
+
+debugger.consolelog[] (read-only)
+ The lines in the console log (output from debugger commands). This
+ container only supports index and length operations.
+debugger.errorlog[] (read-only)
+ The lines in the error log (``logerror`` output). This container only
+ supports index and length operations.
+debugger.visible_cpu (read/write)
+ The CPU device with debugger focus. Changes become visible in the debugger
+ console after the next step. Setting to a device that is not a CPU has no
+ effect.
+debugger.execution_state (read/write)
+ Either ``"run"`` if the emulated system is running, or ``"stop"`` if it is
+ stopped in the debugger.
+
+
+.. _luascript-ref-devdebug:
+
+Device debugger interface
+-------------------------
+
+Wraps MAME’s ``device_debug`` class, providing the debugger interface to an
+emulated CPU device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].debug
+ Returns the debugger interface for an emulated CPU device, or ``nil`` if the
+ device is not a CPU.
+
+Methods
+~~~~~~~
+
+debug:step([cnt])
+ Step by the specified number of instructions. If the instruction count is
+ not provided, it defaults to a single instruction.
+debug:go()
+ Run the emulated CPU.
+debug:bpset(addr, [cond], [act])
+ Set a breakpoint at the specified address, with an optional condition and
+ action. If the action is not specified, it defaults to just breaking into
+ the debugger. Returns the breakpoint number for the new breakpoint.
+
+ If specified, the condition must be a debugger expression that will be
+ evaluated each time the breakpoint is hit. Execution will only be stopped
+ if the expression evaluates to a non-zero value. If the condition is not
+ specified, it defaults to always active.
+debug:bpenable([bp])
+ Enable the specified breakpoint, or all breakpoints for the device if no
+ breakpoint number is specified. Returns whether the specified number
+ matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
+ breakpoint number is specified.
+debug:bpdisable([bp])
+ Disable the specified breakpoint, or all breakpoints for the device if no
+ breakpoint number is specified. Returns whether the specified number
+ matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
+ breakpoint number is specified.
+debug:bpclear([bp])
+ Clear the specified breakpoint, or all breakpoints for the device if no
+ breakpoint number is specified. Returns whether the specified number
+ matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
+ breakpoint number is specified.
+debug:bplist()
+ Returns a table of breakpoints for the device. The keys are the breakpoint
+ numbers, and the values are
+ :ref:`breakpoint objects <luascript-ref-breakpoint>`.
+debug:wpset(space, type, addr, len, [cond], [act])
+ Set a watchpoint over the specified address range, with an optional
+ condition and action. The type must be ``"r"``, ``"w"`` or ``"rw"`` for a
+ read, write or read/write breakpoint. If the action is not specified, it
+ defaults to just breaking into the debugger. Returns the watchpoint number
+ for the new watchpoint.
+
+ If specified, the condition must be a debugger expression that will be
+ evaluated each time the breakpoint is hit. Execution will only be stopped
+ if the expression evaluates to a non-zero value. The variable 'wpaddr' is
+ set to the address that actually triggered the watchpoint, the variable
+ 'wpdata' is set to the data that is being read or written, and the variable
+ 'wpsize' is set to the size of the data in bytes. If the condition is not
+ specified, it defaults to always active.
+debug:wpenable([wp])
+ Enable the specified watchpoint, or all watchpoints for the device if no
+ watchpoint number is specified. Returns whether the specified number
+ matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
+ watchpoint number is specified.
+debug:wpdisable([wp])
+ Disable the specified watchpoint, or all watchpoints for the device if no
+ watchpoint number is specified. Returns whether the specified number
+ matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
+ watchpoint number is specified.
+debug:wpclear([wp])
+ Clear the specified watchpoint, or all watchpoints for the device if no
+ watchpoint number is specified. Returns whether the specified number
+ matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
+ watchpoint number is specified.
+debug:wplist(space)
+ Returns a table of watchpoints for the specified address space of the
+ device. The keys are the watchpoint numbers, and the values are
+ :ref:`watchpoint objects <luascript-ref-watchpoint>`.
+
+
+.. _luascript-ref-breakpoint:
+
+Breakpoint
+----------
+
+Wraps MAME’s ``debug_breakpoint`` class, representing a breakpoint for an
+emulated CPU device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].debug:bplist()[bp]
+ Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no
+ breakpoint corresponds to the specified index.
+
+Properties
+~~~~~~~~~~
+
+breakpoint.index (read-only)
+ The breakpoint’s index. The can be used to enable, disable or clear the
+ breakpoint via the
+ :ref:`CPU debugger interface <luascript-ref-devdebug>`.
+breakpoint.enabled (read/write)
+ A Boolean indicating whether the breakpoint is currently enabled.
+breakpoint.address (read-only)
+ The breakpoint’s address.
+breakpoint.condition (read-only)
+ A debugger expression evaluated each time the breakpoint is hit. The action
+ will only be triggered if this expression evaluates to a non-zero value. An
+ empty string if no condition was specified.
+breakpoint.action (read-only)
+ An action the debugger will run when the breakpoint is hit and the condition
+ evaluates to a non-zero value. An empty string if no action was specified.
+
+
+.. _luascript-ref-watchpoint:
+
+Watchpoint
+----------
+
+Wraps MAME’s ``debug_watchpoint`` class, representing a watchpoint for an
+emulated CPU device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].debug:wplist(space)[wp]
+ Gets the specified watchpoint for an address space of an emulated CPU
+ device, or ``nil`` if no watchpoint in the address space corresponds to the
+ specified index.
+
+Properties
+~~~~~~~~~~
+
+watchpoint.index (read-only)
+ The watchpoint’s index. The can be used to enable, disable or clear the
+ watchpoint via the
+ :ref:`CPU debugger interface <luascript-ref-devdebug>`.
+watchpoint.enabled (read/write)
+ A Boolean indicating whether the watchpoint is currently enabled.
+watchpoint.type (read-only)
+ Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write
+ watchpoint.
+watchpoint.address (read-only)
+ The starting address of the watchpoint’s address range.
+watchpoint.length (read-only)
+ The length of the watchpoint’s address range.
+watchpoint.condition (read-only)
+ A debugger expression evaluated each time the watchpoint is hit. The action
+ will only be triggered if this expression evaluates to a non-zero value. An
+ empty string if no condition was specified.
+watchpoint.action (read-only)
+ An action the debugger will run when the watchpoint is hit and the condition
+ evaluates to a non-zero value. An empty string if no action was specified.
+
+
+.. _luascript-ref-debugexpressionerror:
+
+Expression error
+----------------
+
+Wraps MAME’s ``expression_error`` class, describing an error occurring while
+parsing or executing a debugger expression. Raised on errors when using
+:ref:`parsed expressions <luascript-ref-debugexpression>`. Can be converted to
+a string to provide a description of the error.
+
+Properties
+~~~~~~~~~~
+
+err.code (read-only)
+ An implementation-dependent number representing the category of error.
+ Should not be displayed to the user.
+err.offset (read-only)
+ The offset within the expression string where the error was encountered.
diff --git a/docs/source/luascript/ref-devices.rst b/docs/source/luascript/ref-devices.rst
new file mode 100644
index 00000000000..1c3eabdbd2d
--- /dev/null
+++ b/docs/source/luascript/ref-devices.rst
@@ -0,0 +1,770 @@
+.. _luascript-ref-dev:
+
+Lua Device Classes
+==================
+
+Several device classes and device mix-ins classes are exposed to Lua. Devices
+can be looked up by tag or enumerated.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-devenum:
+
+Device enumerators
+------------------
+
+Device enumerators are special containers that allow iterating over devices and
+looking up devices by tag. A device enumerator can be created to find any kind
+of device, to find devices of a particular type, or to find devices that
+implement a particular interface. When iterating using ``pairs`` or ``ipairs``,
+devices are returned by walking the device tree depth-first in creation order.
+
+The index get operator looks up a device by tag. It returns ``nil`` if no
+device with the specified tag is found, or if the device with the specified tag
+does not meet the type/interface requirements of the device enumerator. The
+complexity is O(1) if the result is cached, but an uncached device lookup is
+expensive. The ``at`` method has O(n) complexity.
+
+If you create a device enumerator with a starting point other than the root
+machine device, passing an absolute tag or a tag containing parent references to
+the index operator may return a device that would not be discovered by
+iteration. If you create a device enumerator with restricted depth, devices
+that would not be found due to being too deep in the hierarchy can still be
+looked up by tag.
+
+Creating a device enumerator with depth restricted to zero can be used to
+downcast a device or test whether a device implements a certain interface. For
+example this will test whether a device implements the media image interface:
+
+.. code-block:: Lua
+
+ image_intf = emu.image_enumerator(device, 0):at(1)
+ if image_intf then
+ print(string.format("Device %s mounts images", device.tag))
+ end
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices
+ Returns a device enumerator that will iterate over
+ :ref:`devices <luascript-ref-device>` in the system.
+manager.machine.palettes
+ Returns a device enumerator that will iterate over
+ :ref:`palette devices <luascript-ref-dipalette>` in the system.
+manager.machine.screens
+ Returns a device enumerator that will iterate over
+ :ref:`screen devices <luascript-ref-screendev>` in the system.
+manager.machine.cassettes
+ Returns a device enumerator that will iterate over
+ :ref:`cassette image devices <luascript-ref-cassdev>` in the system.
+manager.machine.images
+ Returns a device enumerator that will iterate over
+ :ref:`media image devices <luascript-ref-diimage>` in the system.
+manager.machine.slots
+ Returns a device enumerator that will iterate over
+ :ref:`slot devices <luascript-ref-dislot>` in the system.
+emu.device_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`devices <luascript-ref-device>` in the sub-tree starting at the
+ specified device. The specified device will be included. If the depth is
+ provided, it must be an integer specifying the maximum number of levels to
+ iterate below the specified device (i.e. 1 will limit iteration to the
+ device and its immediate children).
+emu.palette_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`palette devices <luascript-ref-dipalette>` in the sub-tree starting at
+ the specified device. The specified device will be included if it is a
+ palette device. If the depth is provided, it must be an integer specifying
+ the maximum number of levels to iterate below the specified device (i.e. 1
+ will limit iteration to the device and its immediate children).
+emu.screen_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`screen devices <luascript-ref-screendev>` in the sub-tree starting at
+ the specified device. The specified device will be included if it is a
+ screen device. If the depth is provided, it must be an integer specifying
+ the maximum number of levels to iterate below the specified device (i.e. 1
+ will limit iteration to the device and its immediate children).
+emu.cassette_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`cassette image devices <luascript-ref-cassdev>` in the sub-tree
+ starting at the specified device. The specified device will be included if
+ it is a cassette image device. If the depth is provided, it must be an
+ integer specifying the maximum number of levels to iterate below the
+ specified device (i.e. 1 will limit iteration to the device and its
+ immediate children).
+emu.image_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`media image devices <luascript-ref-diimage>` in the sub-tree starting
+ at the specified device. The specified device will be included if it is a
+ media image device. If the depth is provided, it must be an integer
+ specifying the maximum number of levels to iterate below the specified
+ device (i.e. 1 will limit iteration to the device and its immediate
+ children).
+emu.slot_enumerator(device, [depth])
+ Returns a device enumerator that will iterate over
+ :ref:`slot devices <luascript-ref-dislot>` in the sub-tree starting at the
+ specified device. The specified device will be included if it is a slot
+ device. If the depth is provided, it must be an integer specifying the
+ maximum number of levels to iterate below the specified device (i.e. 1 will
+ limit iteration to the device and its immediate children).
+
+
+.. _luascript-ref-device:
+
+Device
+------
+
+Wraps MAME’s ``device_t`` class, which is a base of all device classes.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag]
+ Gets a device by tag relative to the root machine device, or ``nil`` if no
+ such device exists.
+manager.machine.devices[tag]:subdevice(tag)
+ Gets a device by tag relative to another arbitrary device, or ``nil`` if no
+ such device exists.
+
+Methods
+~~~~~~~
+
+device:subtag(tag)
+ Converts a tag relative to the device to an absolute tag.
+device:siblingtag(tag)
+ Converts a tag relative to the device’s parent device to an absolute tag.
+device:memshare(tag)
+ Gets a :ref:`memory share <luascript-ref-memshare>` by tag relative to the
+ device, or ``nil`` if no such memory share exists.
+device:membank(tag)
+ Gets a :ref:`memory bank <luascript-ref-membank>` by tag relative to the
+ device, or ``nil`` if no such memory bank exists.
+device:memregion(tag)
+ Gets a :ref:`memory region <luascript-ref-memregion>` by tag relative to the
+ device, or ``nil`` if no such memory region exists.
+device:ioport(tag)
+ Gets an :ref:`I/O port <luascript-ref-ioport>` by tag relative to the
+ device, or ``nil`` if no such I/O port exists.
+device:subdevice(tag)
+ Gets a device by tag relative to the device.
+device:siblingdevice(tag)
+ Gets a device by tag relative to the device’s parent.
+device:parameter(tag)
+ Gets a parameter value by tag relative to the device, or an empty string if
+ the parameter is not set.
+
+Properties
+~~~~~~~~~~
+
+device.tag (read-only)
+ The device’s absolute tag in canonical form.
+device.basetag (read-only)
+ The last component of the device’s tag (i.e. its tag relative to its
+ immediate parent), or ``"root"`` for the root machine device.
+device.name (read-only)
+ The full display name for the device’s type.
+device.shortname (read-only)
+ The short name of the devices type (this is used, e.g. on the command line,
+ when looking for resource like ROMs or artwork, and in various data files).
+device.owner (read-only)
+ The device’s immediate parent in the device tree, or ``nil`` for the root
+ machine device.
+device.configured (read-only)
+ A Boolean indicating whether the device has completed configuration.
+device.started (read-only)
+ A Boolean indicating whether the device has completed starting.
+device.debug (read-only)
+ The :ref:`debugger interface <luascript-ref-devdebug>` to the device if it
+ is a CPU device, or ``nil`` if it is not a CPU device or the debugger is not
+ enabled.
+device.state[] (read-only)
+ The :ref:`state entries <luascript-ref-distateentry>` for devices that
+ expose the register state interface, indexed by symbol, or ``nil`` for other
+ devices. The index operator and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+device.spaces[] (read-only)
+ A table of the device’s :ref:`address spaces <luascript-ref-addrspace>`,
+ indexed by name. Only valid for devices that implement the memory
+ interface. Note that the names are specific to the device type and have no
+ special significance.
+
+
+.. _luascript-ref-dipalette:
+
+Palette device
+--------------
+
+Wraps MAME’s ``device_palette_interface`` class, which represents a device that
+translates pen values to colours.
+
+Colours are represented in alpha/red/green/blue (ARGB) format. Channel values
+range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
+Colour channel values are not pre-multiplied by the alpha value. Channel values
+are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
+green, blue from most-significant to least-significant byte.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.palettes[tag]
+ Gets a palette device by tag relative to the root machine device, or ``nil``
+ if no such device exists or it is not a palette device.
+
+Methods
+~~~~~~~
+
+palette:pen(index)
+ Gets the remapped pen number for the specified palette index.
+palette:pen_color(pen)
+ Gets the colour for the specified pen number.
+palette:pen_contrast(pen)
+ Gets the contrast value for the specified pen number. The contrast is a
+ floating-point number.
+palette:pen_indirect(index)
+ Gets the indirect pen index for the specified palette index.
+palette:indirect_color(index)
+ Gets the indirect pen colour for the specified palette index.
+palette:set_pen_color(pen, color)
+ Sets the colour for the specified pen number. The colour may be specified
+ as a single packed 32-bit value; or as individual red, green and blue
+ channel values, in that order.
+palette:set_pen_red_level(pen, level)
+ Sets the red channel value of the colour for the specified pen number.
+ Other channel values are not affected.
+palette:set_pen_green_level(pen, level)
+ Sets the green channel value of the colour for the specified pen number.
+ Other channel values are not affected.
+palette:set_pen_blue_level(pen, level)
+ Sets the blue channel value of the colour for the specified pen number.
+ Other channel values are not affected.
+palette:set_pen_contrast(pen, factor)
+ Sets the contrast value for the specified pen number. The value must be a
+ floating-point number.
+palette:set_pen_indirect(pen, index)
+ Sets the indirect pen index for the specified pen number.
+palette:set_indirect_color(index, color)
+ Sets the indirect pen colour for the specified palette index. The colour
+ may be specified as a single packed 32-bit value; or as individual red,
+ green and blue channel values, in that order.
+palette:set_shadow_factor(factor)
+ Sets the contrast value for the current shadow group. The value must be a
+ floating-point number.
+palette:set_highlight_factor(factor)
+ Sets the contrast value for the current highlight group. The value must be
+ a floating-point number.
+palette:set_shadow_mode(mode)
+ Sets the shadow mode. The value is the index of the desired shadow table.
+
+Properties
+~~~~~~~~~~
+
+palette.palette (read-only)
+ The underlying :ref:`palette <luascript-ref-palette>` managed by the
+ device.
+palette.entries (read-only)
+ The number of colour entries in the palette.
+palette.indirect_entries (read-only)
+ The number of indirect pen entries in the palette.
+palette.black_pen (read-only)
+ The index of the fixed black pen entry.
+palette.white_pen (read-only)
+ The index of the fixed white pen.
+palette.shadows_enabled (read-only)
+ A Boolean indicating whether shadow colours are enabled.
+palette.highlights_enabled (read-only)
+ A Boolean indicating whether highlight colours are enabled.
+palette.device (read-only)
+ The underlying :ref:`device <luascript-ref-device>`.
+
+
+.. _luascript-ref-screendev:
+
+Screen device
+-------------
+
+Wraps MAME’s ``screen_device`` class, which represents an emulated video output.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.screens[tag]
+ Gets a screen device by tag relative to the root machine device, or ``nil``
+ if no such device exists or it is not a screen device.
+
+Base classes
+~~~~~~~~~~~~
+
+* :ref:`luascript-ref-device`
+
+Methods
+~~~~~~~
+
+screen:orientation()
+ Returns the rotation angle in degrees (will be one of 0, 90, 180 or 270),
+ whether the screen is flipped left-to-right, and whether the screen is
+ flipped top-to-bottom. This is the final screen orientation after the
+ screen orientation specified in the machine configuration and the rotation
+ for the system driver are applied.
+screen:time_until_pos(v, [h])
+ Gets the time remaining until the raster reaches the specified position. If
+ the horizontal component of the position is not specified, it defaults to
+ zero (0, i.e. the beginning of the line). The result is a floating-point
+ number in units of seconds.
+screen:time_until_vblank_start()
+ Gets the time remaining until the start of the vertical blanking interval.
+ The result is a floating-point number in units of seconds.
+screen:time_until_vblank_end()
+ Gets the time remaining until the end of the vertical blanking interval.
+ The result is a floating-point number in units of seconds.
+screen:snapshot([filename])
+ Saves a screen snapshot in PNG format. If no filename is supplied, the
+ configured snapshot path and name format will be used. If the supplied
+ filename is not an absolute path, it is interpreted relative to the first
+ configured snapshot path. The filename may contain conversion specifiers
+ that will be replaced by the system name or an incrementing number.
+
+ Returns a file error if opening the snapshot file failed, or ``nil``
+ otherwise.
+screen:pixel(x, y)
+ Gets the pixel at the specified location. Coordinates are in pixels, with
+ the origin at the top left corner of the visible area, increasing to the
+ right and down. Returns either a palette index or a colour in RGB format
+ packed into a 32-bit integer. Returns zero (0) if the specified point is
+ outside the visible area.
+screen:pixels()
+ Returns all visible pixels, the visible area width and visible area height.
+
+ Pixels are returned as 32-bit integers packed into a binary string in host
+ Endian order. Pixels are organised in row-major order, from left to right
+ then top to bottom. Pixels values are either palette indices or colours in
+ RGB format packed into 32-bit integers.
+screen:draw_box(left, top, right, bottom, [line], [fill])
+ Draws an outlined rectangle with edges at the specified positions.
+
+ Coordinates are floating-point numbers in units of emulated screen pixels,
+ with the origin at (0, 0). Note that emulated screen pixels often aren’t
+ square. The coordinate system is rotated if the screen is rotated, which is
+ usually the case for vertical-format screens. Before rotation, the origin
+ is at the top left, and coordinates increase to the right and downwards.
+ Coordinates are limited to the screen area.
+
+ The fill and line colours are in alpha/red/green/blue (ARGB) format.
+ Channel values are in the range 0 (transparent or off) to 255 (opaque or
+ full intensity), inclusive. Colour channel values are not pre-multiplied by
+ the alpha value. The channel values must be packed into the bytes of a
+ 32-bit unsigned integer, in the order alpha, red, green, blue from
+ most-significant to least-significant byte. If the line colour is not
+ provided, the UI text colour is used; if the fill colour is not provided,
+ the UI background colour is used.
+screen:draw_line(x0, y0, x1, y1, [color])
+ Draws a line from (x0, y0) to (x1, y1).
+
+ Coordinates are floating-point numbers in units of emulated screen pixels,
+ with the origin at (0, 0). Note that emulated screen pixels often aren’t
+ square. The coordinate system is rotated if the screen is rotated, which is
+ usually the case for vertical-format screens. Before rotation, the origin
+ is at the top left, and coordinates increase to the right and downwards.
+ Coordinates are limited to the screen area.
+
+ The line colour is in alpha/red/green/blue (ARGB) format. Channel values
+ are in the range 0 (transparent or off) to 255 (opaque or full intensity),
+ inclusive. Colour channel values are not pre-multiplied by the alpha value.
+ The channel values must be packed into the bytes of a 32-bit unsigned
+ integer, in the order alpha, red, green, blue from most-significant to
+ least-significant byte. If the line colour is not provided, the UI text
+ colour is used.
+screen:draw_text(x|justify, y, text, [foreground], [background])
+ Draws text at the specified position. If the screen is rotated the text
+ will be rotated.
+
+ If the first argument is a number, the text will be left-aligned at this X
+ coordinate. If the first argument is a string, it must be ``"left"``,
+ ``"center"`` or ``"right"`` to draw the text left-aligned at the
+ left edge of the screen, horizontally centred on the screen, or
+ right-aligned at the right edge of the screen, respectively. The second
+ argument specifies the Y coordinate of the maximum ascent of the text.
+
+ Coordinates are floating-point numbers in units of emulated screen pixels,
+ with the origin at (0, 0). Note that emulated screen pixels often aren’t
+ square. The coordinate system is rotated if the screen is rotated, which is
+ usually the case for vertical-format screens. Before rotation, the origin
+ is at the top left, and coordinates increase to the right and downwards.
+ Coordinates are limited to the screen area.
+
+ The foreground and background colours are in alpha/red/green/blue (ARGB)
+ format. Channel values are in the range 0 (transparent or off) to 255
+ (opaque or full intensity), inclusive. Colour channel values are not
+ pre-multiplied by the alpha value. The channel values must be packed into
+ the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
+ from most-significant to least-significant byte. If the foreground colour
+ is not provided, the UI text colour is used; if the background colour is not
+ provided, it is fully transparent.
+
+Properties
+~~~~~~~~~~
+
+screen.width (read-only)
+ The width of the bitmap produced by the emulated screen in pixels.
+screen.height (read-only)
+ The height of the bitmap produced by the emulated screen in pixels.
+screen.refresh (read-only)
+ The screen’s configured refresh rate in Hertz (this may not reflect the
+ current value).
+screen.refresh_attoseconds (read-only)
+ The screen’s configured refresh interval in attoseconds (this may not
+ reflect the current value).
+screen.xoffset (read-only)
+ The screen’s default X position offset. This is a floating-point number
+ where one (1) corresponds to the X size of the screen’s container. This may
+ be useful for restoring the default after adjusting the X offset via the
+ screen’s container.
+screen.yoffset (read-only)
+ The screen’s default Y position offset. This is a floating-point number
+ where one (1) corresponds to the Y size of the screen’s container. This may
+ be useful for restoring the default after adjusting the Y offset via the
+ screen’s container.
+screen.xscale (read-only)
+ The screen’s default X scale factor, as a floating-point number. This may
+ be useful for restoring the default after adjusting the X scale via the
+ screen’s container.
+screen.yscale (read-only)
+ The screen’s default Y scale factor, as a floating-point number. This may
+ be useful for restoring the default after adjusting the Y scale via the
+ screen’s container.
+screen.pixel_period (read-only)
+ The interval taken to draw a horizontal pixel, as a floating-point number in
+ units of seconds.
+screen.scan_period (read-only)
+ The interval taken to draw a scan line (including the horizontal blanking
+ interval), as a floating-point number in units of seconds.
+screen.frame_period (read-only)
+ The interval taken to draw a complete frame (including blanking intervals),
+ as a floating-point number in units of seconds.
+screen.frame_number (read-only)
+ The current frame number for the screen. This increments monotonically each
+ frame interval.
+screen.container (read-only)
+ The :ref:`render container <luascript-ref-rendercontainer>` used to draw the
+ screen.
+screen.palette (read-only)
+ The :ref:`palette device <luascript-ref-dipalette>` used to translate pixel
+ values to colours, or ``nil`` if the screen uses a direct colour pixel
+ format.
+
+
+.. _luascript-ref-cassdev:
+
+Cassette image device
+---------------------
+
+Wraps MAME’s ``cassette_image_device`` class, representing a compact cassette
+mechanism typically used by a home computer for program storage.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.cassettes[tag]
+ Gets a cassette image device by tag relative to the root machine device, or
+ ``nil`` if no such device exists or it is not a cassette image device.
+
+Base classes
+~~~~~~~~~~~~
+
+* :ref:`luascript-ref-device`
+* :ref:`luascript-ref-diimage`
+
+Methods
+~~~~~~~
+
+cassette:stop()
+ Disables playback.
+cassette:play()
+ Enables playback. The cassette will play if the motor is enabled.
+cassette:forward()
+ Sets forward play direction.
+cassette:reverse()
+ Sets reverse play direction.
+cassette:seek(time, whence)
+ Jump to the specified position on the tape. The time is a floating-point
+ number in units of seconds, relative to the point specified by the whence
+ argument. The whence argument must be one of ``"set"``, ``"cur"`` or
+ ``"end"`` to seek relative to the start of the tape, the current position,
+ or the end of the tape, respectively.
+
+Properties
+~~~~~~~~~~
+
+cassette.is_stopped (read-only)
+ A Boolean indicating whether the cassette is stopped (i.e. not recording and
+ not playing).
+cassette.is_playing (read-only)
+ A Boolean indicating whether playback is enabled (i.e. the cassette will
+ play if the motor is enabled).
+cassette.is_recording (read-only)
+ A Boolean indicating whether recording is enabled (i.e. the cassette will
+ record if the motor is enabled).
+cassette.motor_state (read/write)
+ A Boolean indicating whether the cassette motor is enabled.
+cassette.speaker_state (read/write)
+ A Boolean indicating whether the cassette speaker is enabled.
+cassette.position (read-only)
+ The current position as a floating-point number in units of seconds relative
+ to the start of the tape.
+cassette.length (read-only)
+ The length of the tape as a floating-point number in units of seconds, or
+ zero (0) if no tape image is mounted.
+
+
+.. _luascript-ref-diimage:
+
+Image device interface
+----------------------
+
+Wraps MAME’s ``device_image_interface`` class which is a mix-in implemented by
+devices that can load media image files.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.images[tag]
+ Gets an image device by tag relative to the root machine device, or ``nil``
+ if no such device exists or it is not a media image device.
+
+Methods
+~~~~~~~
+
+image:load(filename)
+ Loads the specified file as a media image. Returns ``nil`` if no error
+ or a string describing an error if an error occurred.
+image:load_software(name)
+ Loads a media image described in a software list. Returns ``nil`` if no
+ error or a string describing an error if an error occurred.
+image:unload()
+ Unloads the mounted image.
+image:create(filename)
+ Creates and mounts a media image file with the specified name. Returns
+ ``nil`` if no error or a string describing an error if an error
+ occurred.
+image:display()
+ Returns a “front panel display” string for the device, if supported. This
+ can be used to show status information, like the current head position or
+ motor state.
+image:add_media_change_notifier(callback)
+ Add a callback to receive notifications when a media image is loaded or
+ unloaded for the device. The callback is passed a single string argument
+ which will be ``"loaded"`` if a media image has been loaded or
+ ``"unloaded"`` if the previously loaded media image has been unloaded.
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+
+Properties
+~~~~~~~~~~
+
+image.is_readable (read-only)
+ A Boolean indicating whether the device supports reading.
+image.is_writeable (read-only)
+ A Boolean indicating whether the device supports writing.
+image.must_be_loaded (read-only)
+ A Boolean indicating whether the device requires a media image to be loaded
+ in order to start.
+image.is_reset_on_load (read-only)
+ A Boolean indicating whether the device requires a hard reset to change
+ media images (usually for cartridge slots that contain hardware in addition
+ to memory chips).
+image.image_type_name (read-only)
+ A string for categorising the media device.
+image.instance_name (read-only)
+ The instance name of the device in the current configuration. This is used
+ for setting the media image to load on the command line or in INI files.
+ This is not stable, it may have a number appended that may change depending
+ on slot configuration.
+image.brief_instance_name (read-only)
+ The brief instance name of the device in the current configuration. This is
+ used for setting the media image to load on the command line or in INI
+ files. This is not stable, it may have a number appended that may change
+ depending on slot configuration.
+image.formatlist[] (read-only)
+ The :ref:`media image formats <luascript-ref-imagefmt>` supported by the
+ device, indexed by name. The index operator and ``index_of`` methods have
+ O(n) complexity; all other supported operations have O(1) complexity.
+image.exists (read-only)
+ A Boolean indicating whether a media image file is mounted.
+image.readonly (read-only)
+ A Boolean indicating whether a media image file is mounted in read-only
+ mode.
+image.filename (read-only)
+ The full path to the mounted media image file, or ``nil`` if no media image
+ is mounted.
+image.crc (read-only)
+ The 32-bit cyclic redundancy check of the content of the mounted image file
+ if the mounted media image was not loaded from a software list, is mounted
+ read-only and is not a CD-ROM, or zero (0) otherwise.
+image.loaded_through_softlist (read-only)
+ A Boolean indicating whether the mounted media image was loaded from a
+ software list, or ``false`` if no media image is mounted.
+image.software_list_name (read-only)
+ The short name of the software list if the mounted media image was loaded
+ from a software list.
+image.software_longname (read-only)
+ The full name of the software item if the mounted media image was loaded
+ from a software list, or ``nil`` otherwise.
+image.software_publisher (read-only)
+ The publisher of the software item if the mounted media image was loaded
+ from a software list, or ``nil`` otherwise.
+image.software_year (read-only)
+ The release year of the software item if the mounted media image was loaded
+ from a software list, or ``nil`` otherwise.
+image.software_parent (read-only)
+ The short name of the parent software item if the mounted media image was
+ loaded from a software list, or ``nil`` otherwise.
+image.device (read-only)
+ The underlying :ref:`device <luascript-ref-device>`.
+
+
+.. _luascript-ref-dislot:
+
+Slot device interface
+---------------------
+
+Wraps MAME’s ``device_slot_interface`` class which is a mix-in implemented by
+devices that instantiate a user-specified child device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.slots[tag]
+ Gets an slot device by tag relative to the root machine device, or ``nil``
+ if no such device exists or it is not a slot device.
+
+Properties
+~~~~~~~~~~
+
+slot.fixed (read-only)
+ A Boolean indicating whether this is a slot with a card specified in machine
+ configuration that cannot be changed by the user.
+slot.has_selectable_options (read-only)
+ A Boolean indicating whether the slot has any user-selectable options (as
+ opposed to options that can only be selected programmatically, typically for
+ fixed slots or to load media images).
+slot.options[] (read-only)
+ The :ref:`slot options <luascript-ref-slotopt>` describing the child devices
+ that can be instantiated by the slot, indexed by option value. The ``at``
+ and ``index_of`` methods have O(n) complexity; all other supported
+ operations have O(1) complexity.
+slot.device (read-only)
+ The underlying :ref:`device <luascript-ref-device>`.
+
+
+.. _luascript-ref-distateentry:
+
+Device state entry
+------------------
+
+Wraps MAME’s ``device_state_entry`` class, which allows access to named
+registers exposed by a :ref:`device <luascript-ref-device>`. Supports
+conversion to string for display.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].state[symbol]
+ Gets a state entry for a given device by symbol.
+
+Properties
+~~~~~~~~~~
+
+entry.value (read/write)
+ The numeric value of the state entry, as either an integer or floating-point
+ number. Attempting to set the value of a read-only state entry raises an
+ error.
+entry.symbol (read-only)
+ The state entry’s symbolic name.
+entry.visible (read-only)
+ A Boolean indicating whether the state entry should be displayed in the
+ debugger register view.
+entry.writeable (read-only)
+ A Boolean indicating whether it is possible to modify the state entry’s
+ value.
+entry.is_float (read-only)
+ A Boolean indicating whether the state entry’s value is a floating-point
+ number.
+entry.datamask (read-only)
+ A bit mask of the valid bits of the value for integer state entries.
+entry.datasize (read-only)
+ The size of the underlying value in bytes for integer state entries.
+entry.max_length (read-only)
+ The maximum display string length for the state entry.
+
+
+.. _luascript-ref-imagefmt:
+
+Media image format
+------------------
+
+Wraps MAME’s ``image_device_format`` class, which describes a media file format
+supported by a :ref:`media image device <luascript-ref-diimage>`.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.images[tag].formatlist[name]
+ Gets a media image format supported by a given device by name.
+
+Properties
+~~~~~~~~~~
+
+format.name (read-only)
+ An abbreviated name used to identify the format. This often matches the
+ primary filename extension used for the format.
+format.description (read-only)
+ The full display name of the format.
+format.extensions[] (read-only)
+ Yields a table of filename extensions used for the format.
+format.option_spec (read-only)
+ A string describing options available when creating a media image using this
+ format. The string is not intended to be human-readable.
+
+
+.. _luascript-ref-slotopt:
+
+Slot option
+-----------
+
+Wraps MAME’s ``device_slot_interface::slot_option`` class, which represents a
+child device that a :ref:`slot device <luascript-ref-dislot>` can be
+configured to instantiate.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.slots[tag].options[name]
+ Gets a slot option for a given :ref:`slot device <luascript-ref-dislot>` by
+ name (i.e. the value used to select the option).
+
+Properties
+~~~~~~~~~~
+
+option.name (read-only)
+ The name of the slot option. This is the value used to select this option
+ on the command line or in an INI file.
+option.device_fullname (read-only)
+ The full display name of the device type instantiated by this option.
+option.device_shortname (read-only)
+ The short name of the device type instantiated by this option.
+option.selectable (read-only)
+ A Boolean indicating whether the option may be selected by the user (options
+ that are not user-selectable are typically used for fixed slots or to load
+ media images).
+option.default_bios (read-only)
+ The default BIOS setting for the device instantiated using this option, or
+ ``nil`` if the default BIOS specified in the device’s ROM definitions will
+ be used.
+option.clock (read-only)
+ The configured clock frequency for the device instantiated using this
+ option. This is an unsigned 32-bit integer. If the eight most-significant
+ bits are all set, it is a ratio of the parent device’s clock frequency, with
+ the numerator in bits 12-23 and the denominator in bits 0-11. If the eight
+ most-significant bits are not all set, it is a frequency in Hertz.
diff --git a/docs/source/luascript/ref-input.rst b/docs/source/luascript/ref-input.rst
new file mode 100644
index 00000000000..7390d46743f
--- /dev/null
+++ b/docs/source/luascript/ref-input.rst
@@ -0,0 +1,776 @@
+.. _luascript-ref-input:
+
+Lua Input System Classes
+========================
+
+Allows scripts to get input from the user, and access I/O ports in the emulated
+system.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-ioportman:
+
+I/O port manager
+----------------
+
+Wraps MAME’s ``ioport_manager`` class, which provides access to emulated I/O
+ports and handles input configuration.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.ioport
+ Gets the global I/O port manager instance for the emulated machine.
+
+Methods
+~~~~~~~
+
+ioport:count_players()
+ Returns the number of player controllers in the system.
+ioport:type_pressed(type, [player])
+ Returns a Boolean indicating whether the specified input is currently
+ pressed. The input type may be an enumerated value or an
+ :ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
+ enumerated value, the player number may be supplied as a zero-based index;
+ if the player number is not supplied, it is assumed to be zero. If the
+ input type is an input type entry, the player number may not be supplied
+ separately.
+ioport:type_name(type, [player])
+ Returns the display name for the specified input type and player number.
+ The input type is an enumerated value. The player number is a zero-based
+ index. If the player number is not supplied, it is assumed to be zero.
+ioport:type_group(type, player)
+ Returns the input group for the specified input type and player number. The
+ input type is an enumerated value. The player number is a zero-based index.
+ Returns an integer giving the grouping for the input. If the player number
+ is not supplied, it is assumed to be zero.
+
+ This should be called with values obtained from I/O port fields to provide
+ canonical grouping in an input configuration UI.
+ioport:type_seq(type, [player], [seqtype])
+ Get the configured :ref:`input sequence <luascript-ref-inputseq>` for the
+ specified input type, player number and sequence type. The input type may
+ be an enumerated value or an
+ :ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
+ enumerated value, the player number may be supplied as a zero-based index;
+ if the player number is not supplied, it is assumed to be zero. If the
+ input type is an input type entry, the player number may not be supplied
+ separately. If the sequence type is supplied, it must be ``"standard"``,
+ ``"increment"`` or ``"decrement"``; if it is not supplied, it is assumed to
+ be ``"standard"``.
+
+ This provides access to general input assignments.
+ioport:set_type_seq(type, [player], seqtype, seq)
+ Set the configured :ref:`input sequence <luascript-ref-inputseq>` for the
+ specified input type, player number and sequence type. The input type may
+ be an enumerated value or an
+ :ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
+ enumerated value, the player number must be supplied as a zero-based index.
+ If the input type is an input type entry, the player number may not be
+ supplied separately. The sequence type must be ``"standard"``,
+ ``"increment"`` or ``"decrement"``.
+
+ This allows general input assignments to be set.
+ioport:token_to_input_type(string)
+ Returns the input type and player number for the specified input type token
+ string.
+ioport:input_type_to_token(type, [player])
+ Returns the token string for the specified input type and player number. If
+ the player number is not supplied, it assumed to be zero.
+
+Properties
+~~~~~~~~~~
+
+ioport.types[] (read-only)
+ Gets the supported :ref:`input types <luascript-ref-inputtype>`. Keys are
+ arbitrary indices. All supported operations have O(1) complexity.
+ioport.ports[]
+ Gets the emulated :ref:`I/O ports <luascript-ref-ioport>` in the system.
+ Keys are absolute tags. The ``at`` and ``index_of`` methods have O(n)
+ complexity; all other supported operations have O(1) complexity.
+
+
+.. _luascript-ref-natkbdman:
+
+Natural keyboard manager
+------------------------
+
+Wraps MAME’s ``natural_keyboard`` class, which manages emulated keyboard and
+keypad inputs.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.natkeyboard
+ Gets the global natural keyboard manager instance for the emulated machine.
+
+Methods
+~~~~~~~
+
+natkeyboard:post(text)
+ Post literal text to the emulated machine. The machine must have keyboard
+ inputs with character bindings, and the correct keyboard input device must
+ be enabled.
+natkeyboard:post_coded(text)
+ Post text to the emulated machine. Brace-enclosed codes are interpreted in
+ the text. The machine must have keyboard inputs with character bindings,
+ and the correct keyboard input device must be enabled.
+
+ The recognised codes are ``{BACKSPACE}``, ``{BS}``, ``{BKSP}``, ``{DEL}``,
+ ``{DELETE}``, ``{END}``, ``{ENTER}``, ``{ESC}``, ``{HOME}``, ``{INS}``,
+ ``{INSERT}``, ``{PGDN}``, ``{PGUP}``, ``{SPACE}``, ``{TAB}``, ``{F1}``,
+ ``{F2}``, ``{F3}``, ``{F4}``, ``{F5}``, ``{F6}``, ``{F7}``, ``{F8}``,
+ ``{F9}``, ``{F10}``, ``{F11}``, ``{F12}``, and ``{QUOTE}``.
+natkeyboard:paste()
+ Post the contents of the host clipboard to the emulated machine. The
+ machine must have keyboard inputs with character bindings, and the correct
+ keyboard input device must be enabled.
+natkeyboard:dump()
+ Returns a string with a human-readable description of the keyboard and
+ keypad input devices in the system, whether they are enabled, and their
+ character bindings.
+
+Properties
+~~~~~~~~~~
+
+natkeyboard.empty (read-only)
+ A Boolean indicating whether the natural keyboard manager’s input buffer is
+ empty.
+natkeyboard.full (read-only)
+ A Boolean indicating whether the natural keyboard manager’s input buffer is
+ full.
+natkeyboard.can_post (read-only)
+ A Boolean indicating whether the emulated system supports posting character
+ data via the natural keyboard manager.
+natkeyboard.is_posting (read-only)
+ A Boolean indicating whether posted character data is currently being
+ delivered to the emulated system.
+natkeyboard.in_use (read/write)
+ A Boolean indicating whether “natural keyboard” mode is enabled. When
+ “natural keyboard” mode is enabled, the natural keyboard manager translates
+ host character input to emulated system keystrokes.
+natkeyboard.keyboards[]
+ Gets the :ref:`keyboard/keypad input devices <luascript-ref-natkbddev>` in
+ the emulated system, indexed by absolute device tag. Index get has O(n)
+ complexity; all other supported operations have O(1) complexity.
+
+
+.. _luascript-ref-natkbddev:
+
+Keyboard input device
+---------------------
+
+Represents a keyboard or keypad input device managed by the
+:ref:`natural keyboard manager <luascript-ref-natkbdman>`. Note that this is
+not a :ref:`device <luascript-ref-device>` class.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.natkeyboard.keyboards[tag]
+ Gets the keyboard input device with the specified tag, or ``nil`` if the tag
+ does not correspond to a keyboard input device.
+
+Properties
+~~~~~~~~~~
+
+keyboard.device (read-only)
+ The underlying :ref:`device <luascript-ref-device>`.
+keyboard.tag (read-only)
+ The absolute tag of the underlying device.
+keyboard.basetag (read-only)
+ The last component of the tag of the underlying device, or ``"root"`` for
+ the root machine device.
+keyboard.name (read-only)
+ The human-readable description of the underlying device type.
+keyboard.shortname (read-only)
+ The identifier for the underlying device type.
+keyboard.is_keypad (read-only)
+ A Boolean indicating whether the underlying device has keypad inputs but no
+ keyboard inputs. This is used when determining which keyboard input devices
+ should be enabled by default.
+keyboard.enabled (read/write)
+ A Boolean indicating whether the device’s keyboard and/or keypad inputs are
+ enabled.
+
+
+.. _luascript-ref-ioport:
+
+I/O port
+--------
+
+Wraps MAME’s ``ioport_port`` class, representing an emulated I/O port.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.ioport.ports[tag]
+ Gets an emulated I/O port by absolute tag, or ``nil`` if the tag does not
+ correspond to an I/O port.
+manager.machine.devices[devtag]:ioport(porttag)
+ Gets an emulated I/O port by tag relative to a device, or ``nil`` if no such
+ I/O port exists.
+
+Methods
+~~~~~~~
+
+port:read()
+ Read the current input value. Returns a 32-bit integer.
+port:write(value, mask)
+ Write to the I/O port output fields that are set in the specified mask. The
+ value and mask must be 32-bit integers. Note that this does not set values
+ for input fields.
+port:field(mask)
+ Get the first :ref:`I/O port field <luascript-ref-ioportfield>`
+ corresponding to the bits that are set in the specified mask, or ``nil`` if
+ there is no corresponding field.
+
+Properties
+~~~~~~~~~~
+
+port.device (read-only)
+ The device that owns the I/O port.
+port.tag (read-only)
+ The absolute tag of the I/O port
+port.active (read-only)
+ A mask indicating which bits of the I/O port correspond to active fields
+ (i.e. not unused or unassigned bits).
+port.live (read-only)
+ The live state of the I/O port.
+port.fields[] (read-only)
+ Gets a table of :ref:`fields <luascript-ref-ioportfield>` indexed by name.
+
+
+.. _luascript-ref-ioportfield:
+
+I/O port field
+--------------
+
+Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.ioport.ports[tag]:field(mask)
+ Gets a field for the given port by bit mask.
+manager.machine.ioport.ports[tag].fields[name]
+ Gets a field for the given port by display name.
+
+Methods
+~~~~~~~
+
+field:set_value(value)
+ Set the value of the I/O port field. For digital fields, the value is
+ compared to zero to determine whether the field should be active; for
+ analog fields, the value must be right-aligned and in the correct range.
+field:clear_value()
+ Clear programmatically overridden value and restore the field’s regular
+ behaviour.
+field:set_input_seq(seqtype, seq)
+ Set the :ref:`input sequence <luascript-ref-inputseq>` for the specified
+ sequence type. This is used to configure per-machine input settings. The
+ sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
+field:input_seq(seq_type)
+ Get the configured :ref:`input sequence <luascript-ref-inputseq>` for the
+ specified sequence type. This gets per-machine input assignments. The
+ sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
+field:set_default_input_seq(seq_type, seq)
+ Set the default :ref:`input sequence <luascript-ref-inputseq>` for the
+ specified sequence type. This overrides the default input assignment for a
+ specific input. The sequence type must be ``"standard"``, ``"increment"``
+ or ``"decrement"``.
+field:default_input_seq(seq_type)
+ Gets the default :ref:`input sequence <luascript-ref-inputseq>` for the
+ specified sequence type. If the default assignment is not overridden, this
+ returns the general input assignment for the field’s input type. The
+ sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
+field:keyboard_codes(shift)
+ Gets a table of characters corresponding to the field for the specified
+ shift state. The shift state is a bit mask of active shift keys.
+
+Properties
+~~~~~~~~~~
+
+field.device (read-only)
+ The device that owns the port that the field belongs to.
+field.port (read-only)
+ The :ref:`I/O port <luascript-ref-ioport>` that the field belongs to.
+field.live (read-only)
+ The :ref:`live state <luascript-ref-ioportfieldlive>` of the field.
+field.type (read-only)
+ The input type of the field. This is an enumerated value.
+field.name (read-only)
+ The display name for the field.
+field.default_name (read-only)
+ The name for the field from the emulated system’s configuration (cannot be
+ overridden by scripts or plugins).
+field.player (read-only)
+ Zero-based player number for the field.
+field.mask (read-only)
+ Bits in the I/O port corresponding to this field.
+field.defvalue (read-only)
+ The field’s default value.
+field.minvalue (read-only)
+ The minimum allowed value for analog fields, or ``nil`` for digital fields.
+field.maxvalue (read-only)
+ The maximum allowed value for analog fields, or ``nil`` for digital fields.
+field.sensitivity (read-only)
+ The sensitivity or gain for analog fields, or ``nil`` for digital fields.
+field.way (read-only)
+ The number of directions allowed by the restrictor plate/gate for a digital
+ joystick, or zero (0) for other inputs.
+field.type_class (read-only)
+ The type class for the input field – one of ``"keyboard"``,
+ ``"controller"``, ``"config"``, ``"dipswitch"`` or ``"misc"``.
+field.is_analog (read-only)
+ A Boolean indicating whether the field is an analog axis or positional
+ control.
+field.is_digital_joystick (read-only)
+ A Boolean indicating whether the field corresponds to a digital joystick
+ switch.
+field.enabled (read-only)
+ A Boolean indicating whether the field is enabled.
+field.optional (read-only)
+ A Boolean indicating whether the field is optional and not required to use
+ the emulated system.
+field.cocktail (read-only)
+ A Boolean indicating whether the field is only used when the system is
+ configured for a cocktail table cabinet.
+field.toggle (read-only)
+ A Boolean indicating whether the field corresponds to a hardware toggle
+ switch or push-on, push-off button.
+field.rotated (read-only)
+ A Boolean indicating whether the field corresponds to a control that is
+ rotated relative its standard orientation.
+field.analog_reverse (read-only)
+ A Boolean indicating whether the field corresponds to an analog control that
+ increases in the opposite direction to the convention (e.g. larger values
+ when a pedal is released or a joystick is moved to the left).
+field.analog_reset (read-only)
+ A Boolean indicating whether the field corresponds to an incremental
+ position input (e.g. a dial or trackball axis) that should be reset to zero
+ for every video frame.
+field.analog_wraps (read-only)
+ A Boolean indicating whether the field corresponds to an analog input that
+ wraps from one end of its range to the other (e.g. an incremental position
+ input like a dial or trackball axis).
+field.analog_invert (read-only)
+ A Boolean indicating whether the field corresponds to an analog input that
+ has its value ones-complemented.
+field.impulse (read-only)
+ A Boolean indicating whether the field corresponds to a digital input that
+ activates for a fixed amount of time.
+field.crosshair_scale (read-only)
+ The scale factor for translating the field’s range to crosshair position. A
+ value of one (1) translates the field’s full range to the full width or
+ height the screen.
+field.crosshair_offset (read-only)
+ The offset for translating the field’s range to crosshair position.
+field.user_value (read/write)
+ The value for DIP switch or configuration settings.
+field.settings[] (read-only)
+ Gets a table of the currently enabled settings for a DIP switch or
+ configuration field, indexed by value.
+
+
+.. _luascript-ref-ioportfieldlive:
+
+Live I/O port field state
+-------------------------
+
+Wraps MAME’s ``ioport_field_live`` class, representing the live state of an I/O
+port field.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.ioport.ports[tag]:field(mask).live
+ Gets the live state for an I/O port field.
+
+Properties
+~~~~~~~~~~
+
+live.name
+ Display name for the field.
+
+
+.. _luascript-ref-inputtype:
+
+Input type
+----------
+
+Wraps MAME’s ``input_type_entry`` class, representing an emulated input type or
+emulator UI input type. Input types are uniquely identified by the combination
+of their enumerated type value and player index.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.ioport.types[index]
+ Gets a supported input type.
+
+Properties
+~~~~~~~~~~
+
+type.type (read-only)
+ An enumerated value representing the type of input.
+type.group (read-only)
+ An integer giving the grouping for the input type. Should be used to
+ provide canonical grouping in an input configuration UI.
+type.player (read-only)
+ The zero-based player number, or zero for non-player controls.
+type.token (read-only)
+ The token string for the input type, used in configuration files.
+type.name (read-only)
+ The display name for the input type.
+type.is_analog (read-only)
+ A Boolean indicating whether the input type is analog or digital. Inputs
+ that only have on and off states are considered digital, while all other
+ inputs are considered analog, even if they can only represent discrete
+ values or positions.
+
+
+.. _luascript-ref-inputman:
+
+Input manager
+-------------
+
+Wraps MAME’s ``input_manager`` class, which reads host input devices and checks
+whether configured inputs are active.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.input
+ Gets the global input manager instance for the emulated system.
+
+Methods
+~~~~~~~
+
+input:code_value(code)
+ Gets the current value for the host input corresponding to the specified
+ code. Returns a signed integer value, where zero is the neutral position.
+input:code_pressed(code)
+ Returns a Boolean indicating whether the host input corresponding to the
+ specified code has a non-zero value (i.e. it is not in the neutral
+ position).
+input:code_pressed_once(code)
+ Returns a Boolean indicating whether the host input corresponding to the
+ specified code has moved away from the neutral position since the last time
+ it was checked using this function. The input manager can track a limited
+ number of inputs this way.
+input:code_name(code)
+ Get display name for an input code.
+input:code_to_token(code)
+ Get token string for an input code. This should be used when saving
+ configuration.
+input:code_from_token(token)
+ Convert a token string to an input code. Returns the invalid input code if
+ the token is not valid or belongs to an input device that is not present.
+input:seq_pressed(seq)
+ Returns a Boolean indicating whether the supplied
+ :ref:`input sequence <luascript-ref-inputseq>` is currently pressed.
+input:seq_clean(seq)
+ Remove invalid elements from the supplied
+ :ref:`input sequence <luascript-ref-inputseq>`. Returns the new, cleaned
+ input sequence.
+input:seq_name(seq)
+ Get display text for an :ref:`input sequence <luascript-ref-inputseq>`.
+input:seq_to_tokens(seq)
+ Convert an :ref:`input sequence <luascript-ref-inputseq>` to a token string.
+ This should be used when saving configuration.
+input:seq_from_tokens(tokens)
+ Convert a token string to an
+ :ref:`input sequence <luascript-ref-inputseq>`. This should be used when
+ loading configuration.
+input:axis_code_poller()
+ Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
+ obtaining an analog host input code.
+input:switch_code_poller()
+ Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
+ obtaining a host switch input code.
+input:keyboard_code_poller()
+ Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
+ obtaining a host switch input code that only considers keyboard input
+ devices.
+input:axis_sequence_poller()
+ Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
+ obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
+ an analog input assignment.
+input:axis_sequence_poller()
+ Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
+ obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
+ a digital input assignment.
+
+Properties
+~~~~~~~~~~
+
+input.device_classes[] (read-only)
+ Gets a table of host
+ :ref:`input device classes <luascript-ref-inputdevclass>` indexed by name.
+
+
+.. _luascript-ref-inputcodepoll:
+
+Input code poller
+-----------------
+
+Wraps MAME’s ``input_code_poller`` class, used to poll for host inputs being
+activated.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.input:axis_code_poller()
+ Returns an input code poller that polls for analog inputs being activated.
+manager.machine.input:switch_code_poller()
+ Returns an input code poller that polls for host switch inputs being
+ activated.
+manager.machine.input:keyboard_code_poller()
+ Returns an input code poller that polls for host switch inputs being
+ activated, only considering keyboard input devices.
+
+Methods
+~~~~~~~
+
+poller:reset()
+ Resets the polling logic. Active switch inputs are cleared and initial
+ analog input positions are set.
+poller:poll()
+ Returns an input code corresponding to the first relevant host input that
+ has been activated since the last time the method was called. Returns the
+ invalid input code if no relevant input has been activated.
+
+
+.. _luascript-ref-inputseqpoll:
+
+Input sequence poller
+---------------------
+
+Wraps MAME’s ``input_sequence_poller`` poller class, which allows users to
+assign host input combinations to emulated inputs and other actions.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.input:axis_sequence_poller()
+ Returns an input sequence poller for assigning host inputs to an analog
+ input.
+manager.machine.input:switch_sequence_poller()
+ Returns an input sequence poller for assigning host inputs to a switch
+ input.
+
+Methods
+~~~~~~~
+
+poller:start([seq])
+ Start polling. If a sequence is supplied, it is used as a starting
+ sequence: for analog inputs, the user can cycle between the full range, and
+ the positive and negative portions of an axis; for switch inputs, an “or”
+ code is appended and the user can add an alternate host input combination.
+poller:poll()
+ Polls for user input and updates the sequence if appropriate. Returns a
+ Boolean indicating whether sequence input is complete. If this method
+ returns false, you should continue polling.
+
+Properties
+~~~~~~~~~~
+
+poller.sequence (read-only)
+ The current :ref:`input sequence <luascript-ref-inputseq>`. This is updated
+ while polling. It is possible for the sequence to become invalid.
+poller.valid (read-only)
+ A Boolean indicating whether the current input sequence is valid.
+poller.modified (read-only)
+ A Boolean indicating whether the sequence was changed by any user input
+ since starting polling.
+
+
+.. _luascript-ref-inputseq:
+
+Input sequence
+--------------
+
+Wraps MAME’s ``input_seq`` class, representing a combination of host inputs that
+can be read or assigned to an emulated input. Input sequences can be
+manipulated using :ref:`input manager <luascript-ref-inputman>` methods. Use an
+:ref:`input sequence poller <luascript-ref-inputseqpoll>` to obtain an input
+sequence from the user.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.input_seq()
+ Creates an empty input sequence.
+emu.input_seq(seq)
+ Creates a copy of an existing input sequence.
+
+Methods
+~~~~~~~
+
+seq:reset()
+ Clears the input sequence, removing all items.
+seq:set_default()
+ Sets the input sequence to a single item containing the metavalue specifying
+ that the default setting should be used.
+
+Properties
+~~~~~~~~~~
+
+seq.empty (read-only)
+ A Boolean indicating whether the input sequence is empty (contains no items,
+ indicating an unassigned input).
+seq.length (read-only)
+ The number of items in the input sequence.
+seq.is_valid (read-only)
+ A Boolean indicating whether the input sequence is a valid. To be valid, it
+ must contain at least one item, all items must be valid codes, all product
+ groups must contain at least one item that is not negated, and items
+ referring to absolute and relative axes must not be mixed within a product
+ group.
+seq.is_default (read-only)
+ A Boolean indicating whether the input sequence specifies that the default
+ setting should be used.
+
+
+.. _luascript-ref-inputdevclass:
+
+Host input device class
+-----------------------
+
+Wraps MAME’s ``input_class`` class, representing a category of host input
+devices (e.g. keyboards or joysticks).
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.input.device_classes[name]
+ Gets an input device class by name.
+
+Properties
+~~~~~~~~~~
+
+devclass.name (read-only)
+ The device class name.
+devclass.enabled (read-only)
+ A Boolean indicating whether the device class is enabled.
+devclass.multi (read-only)
+ A Boolean indicating whether the device class supports multiple devices, or
+ inputs from all devices in the class are combined and treated as a single
+ device.
+devclass.devices[] (read-only)
+ Gets a table of :ref:`host input devices <luascript-ref-inputdev>` in the
+ class. Keys are one-based indices.
+
+
+.. _luascript-ref-inputdev:
+
+Host input device
+-----------------
+
+Wraps MAME’s ``input_device`` class, representing a host input device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.input.device_classes[name].devices[index]
+ Gets a specific host input device.
+
+Properties
+~~~~~~~~~~
+
+inputdev.name (read-only)
+ Display name for the device. This is not guaranteed to be unique.
+inputdev.id (read-only)
+ Unique identifier string for the device. This may not be human-readable.
+inputdev.devindex (read-only)
+ Device index within the device class. This is not necessarily the same as
+ the index in the ``devices`` property of the device class – the ``devindex``
+ indices may not be contiguous.
+inputdev.items (read-only)
+ Gets a table of :ref:`input items <luascript-ref-inputdevitem>`, indexed
+ by item ID. The item ID is an enumerated value.
+
+
+.. _luascript-ref-inputdevitem:
+
+Host input device item
+----------------------
+
+Wraps MAME’s ``input_device_item`` class, representing a single host input (e.g.
+a key, button, or axis).
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.input.device_classes[name].devices[index].items[id]
+ Gets an individual host input item. The item ID is an enumerated value.
+
+Properties
+~~~~~~~~~~
+
+item.name (read-only)
+ The display name of the input item. Note that this is just the name of the
+ item itself, and does not include the device name. The full display name
+ for the item can be obtained by calling the ``code_name`` method on the
+ :ref:`input manager <luascript-ref-inputman>` with the item’s code.
+item.code (read-only)
+ The input item’s identification code. This is used by several
+ :ref:`input manager <luascript-ref-inputman>` methods.
+item.token (read-only)
+ The input item’s token string. Note that this is a token fragment for the
+ item itself, and does not include the device portion. The full token for
+ the item can be obtained by calling the ``code_to_token`` method on the
+ :ref:`input manager <luascript-ref-inputman>` with the item’s code.
+item.current (read-only)
+ The item’s current value. This is a signed integer where zero is the
+ neutral position.
+
+
+.. _luascript-ref-uiinputman:
+
+UI input manager
+----------------
+
+Wraps MAME’s ``ui_input_manager`` class, which is used for high-level input.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.uiinput
+ Gets the global UI input manager instance for the machine.
+
+Methods
+~~~~~~~
+
+uiinput:reset()
+ Clears pending events and UI input states. Should be called when leaving a
+ modal state where input is handled directly (e.g. configuring an input
+ combination).
+uiinput:find_mouse()
+ Returns host system mouse pointer X position, Y position, button state, and
+ the :ref:`render target <luascript-ref-rendertarget>` it falls in. The
+ position is in host pixels, where zero is at the top/left. The button state
+ is a Boolean indicating whether the primary mouse button is pressed.
+
+ If the mouse pointer is not over one of MAME’s windows, this may return the
+ position and render target from when the mouse pointer was most recently
+ over one of MAME’s windows. The render target may be ``nil`` if the mouse
+ pointer is not over one of MAME’s windows.
+uiinput:pressed(type)
+ Returns a Boolean indicating whether the specified UI input has been
+ pressed. The input type is an enumerated value.
+uiinput:pressed_repeat(type, speed)
+ Returns a Boolean indicating whether the specified UI input has been
+ pressed or auto-repeat has been triggered at the specified speed. The input
+ type is an enumerated value; the speed is an interval in sixtieths of a
+ second.
+
+Properties
+~~~~~~~~~~
+
+uiinput.presses_enabled (read/write)
+ Whether the UI input manager will check for UI inputs frame updates.
diff --git a/docs/source/luascript/ref-mem.rst b/docs/source/luascript/ref-mem.rst
new file mode 100644
index 00000000000..0987889d3dc
--- /dev/null
+++ b/docs/source/luascript/ref-mem.rst
@@ -0,0 +1,459 @@
+.. _luascript-ref-mem:
+
+Lua Memory System Classes
+=========================
+
+MAME’s Lua interface exposes various memory system objects, including address
+spaces, memory shares, memory banks, and memory regions. Scripts can read from
+and write to the emulated memory system.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-memman:
+
+Memory manager
+--------------
+
+Wraps MAME’s ``memory_manager`` class, which allows the memory shares, banks and
+regions in a system to be enumerated.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.memory
+ Gets the global memory manager instance for the emulated system.
+
+Properties
+~~~~~~~~~~
+
+memory.shares[]
+ The :ref:`memory shares <luascript-ref-memshare>` in the system, indexed by
+ absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all
+ other supported operations have O(1) complexity.
+memory.banks[]
+ The :ref:`memory banks <luascript-ref-membank>` in the system, indexed by
+ absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all
+ other supported operations have O(1) complexity.
+memory.regions[]
+ The :ref:`memory regions <luascript-ref-memregion>` in the system, indexed
+ by absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity;
+ all other supported operations have O(1) complexity.
+
+
+.. _luascript-ref-addrspace:
+
+Address space
+-------------
+
+Wraps MAME’s ``address_space`` class, which represents an address space
+belonging to a device.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name]
+ Gets the address space with the specified name for a given device. Note
+ that names are specific to the device type.
+
+Methods
+~~~~~~~
+
+space:read_i{8,16,32,64}(addr)
+ Reads a signed integer value of the size in bits from the specified address.
+space:read_u{8,16,32,64}(addr)
+ Reads an unsigned integer value of the size in bits from the specified
+ address.
+space:write_i{8,16,32,64}(addr, val)
+ Writes a signed integer value of the size in bits to the specified address.
+space:write_u{8,16,32,64}(addr, val)
+ Writes an unsigned integer value of the size in bits to the specified
+ address.
+space:readv_i{8,16,32,64}(addr)
+ Reads a signed integer value of the size in bits from the specified virtual
+ address. The address is translated with the debug read intent. Returns
+ zero if address translation fails.
+space:readv_u{8,16,32,64}(addr)
+ Reads an unsigned integer value of the size in bits from the specified
+ virtual address. The address is translated with the debug read intent.
+ Returns zero if address translation fails.
+space:writev_i{8,16,32,64}(addr, val)
+ Writes a signed integer value of the size in bits to the specified virtual
+ address. The address is translated with the debug write intent. Does not
+ write if address translation fails.
+space:writev_u{8,16,32,64}(addr, val)
+ Writes an unsigned integer value of the size in bits to the specified
+ virtual address. The address is translated with the debug write intent.
+ Does not write if address translation fails.
+space:read_direct_i{8,16,32,64}(addr)
+ Reads a signed integer value of the size in bits from the specified address
+ one byte at a time by obtaining a read pointer for each byte address. If
+ a read pointer cannot be obtained for a byte address, the corresponding
+ result byte will be zero.
+space:read_direct_u{8,16,32,64}(addr)
+ Reads an unsigned integer value of the size in bits from the specified
+ address one byte at a time by obtaining a read pointer for each byte
+ address. If a read pointer cannot be obtained for a byte address, the
+ corresponding result byte will be zero.
+space:write_direct_i{8,16,32,64}(addr, val)
+ Writes a signed integer value of the size in bits to the specified address
+ one byte at a time by obtaining a write pointer for each byte address. If
+ a write pointer cannot be obtained for a byte address, the corresponding
+ byte will not be written.
+space:write_direct_u{8,16,32,64}(addr, val)
+ Writes an unsigned integer value of the size in bits to the specified
+ address one byte at a time by obtaining a write pointer for each byte
+ address. If a write pointer cannot be obtained for a byte address, the
+ corresponding byte will not be written.
+space:read_range(start, end, width, [step])
+ Reads a range of addresses as a binary string. The end address must be
+ greater than or equal to the start address. The width must be 8, 16, 30 or
+ 64. If the step is provided, it must be a positive number of elements.
+space:add_change_notifier(callback)
+ Add a callback to receive notifications for handler changes in address
+ space. The callback function is passed a single string as an argument,
+ either ``r`` if read handlers have potentially changed, ``w`` if write
+ handlers have potentially changed, or ``rw`` if both read and write handlers
+ have potentially changed.
+
+ Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
+space:install_read_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
+ will receive notifications on reads from the specified range of addresses in
+ the address space. The start and end addresses are inclusive. The name
+ must be a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data read,
+ and the memory access mask. The offset is the absolute offset into the
+ address space. To modify the data being read, return the modified value
+ from the callback function as an integer. If the callback does not return
+ an integer, the data will not be modified.
+space:install_write_tap(start, end, name, callback)
+ Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
+ will receive notifications on write to the specified range of addresses in
+ the address space. The start and end addresses are inclusive. The name
+ must be a string, and the callback must be a function.
+
+ The callback is passed three arguments for the access offset, the data
+ written, and the memory access mask. The offset is the absolute offset into
+ the address space. To modify the data being written, return the modified
+ value from the callback function as an integer. If the callback does not
+ return an integer, the data will not be modified.
+
+Properties
+~~~~~~~~~~
+
+space.name (read-only)
+ The display name for the address space.
+space.shift (read-only)
+ The address granularity for the address space specified as the shift
+ required to translate a byte address to a native address. Positive values
+ shift towards the most significant bit (left) and negative values shift
+ towards the least significant bit (right).
+space.index (read-only)
+ The zero-based space index. Some space indices have special meanings for
+ the debugger.
+space.address_mask (read-only)
+ The address mask for the space.
+space.data_width (read-only)
+ The data width for the space in bits.
+space.endianness (read-only)
+ The Endianness of the space (``"big"`` or ``"little"``).
+space.map (read-only)
+ The configured :ref:`address map <luascript-ref-addrmap>` for the space or
+ ``nil``.
+
+
+.. _luascript-ref-addrspacetap:
+
+Pass-through handler
+--------------------
+
+Tracks a pass-through handler installed in an
+:ref:`address space <luascript-ref-addrspace>`. A memory pass-through handler
+receives notifications on accesses to a specified range of addresses, and can
+modify the data that is read or written if desired. Note that pass-through handler
+callbacks are not run as coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on reads
+ from the specified range of addresses in an
+ :ref:`address space <luascript-ref-addrspace>`.
+manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)
+ Installs a pass-through handler that will receive notifications on writes to
+ the specified range of addresses in an
+ :ref:`address space <luascript-ref-addrspace>`.
+
+Methods
+~~~~~~~
+
+passthrough:reinstall()
+ Reinstalls the pass-through handler in the address space. May be necessary
+ if the handler is removed due to other changes to handlers in the address
+ space.
+passthrough:remove()
+ Removes the pass-through handler from the address space. The associated
+ callback will not be called in response to future memory accesses.
+
+Properties
+~~~~~~~~~~
+
+passthrough.addrstart (read-only)
+ The inclusive start address of the address range monitored by the
+ pass-through handler (i.e. the lowest address that the handler will be
+ notified for).
+passthrough.addrend (read-only)
+ The inclusive end address of the address range monitored by the pass-through
+ handler (i.e. the highest address that the handler will be notified for).
+passthrough.name (read-only)
+ The display name for the pass-through handler.
+
+
+.. _luascript-ref-addrmap:
+
+Address map
+-----------
+
+Wraps MAME’s ``address_map`` class, used to configure handlers for an address
+space.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name].map
+ Gets the configured address map for an address space, or ``nil`` if no map
+ is configured.
+
+Properties
+~~~~~~~~~~
+
+map.spacenum (read-only)
+ The address space number of the address space the map is associated with.
+map.device (read-only)
+ The device that owns the address space the map is associated with.
+map.unmap_value (read-only)
+ The constant value to return from unmapped reads.
+map.global_mask (read-only)
+ Global mask to be applied to all addresses when accessing the space.
+map.entries[] (read-only)
+ The configured :ref:`entries <luascript-ref-addrmapentry>` in the address
+ map. Uses 1-based integer indices. The index operator and the ``at``
+ method have O(n) complexity.
+
+
+.. _luascript-ref-addrmapentry:
+
+Address map entry
+-----------------
+
+Wraps MAME’s ``address_map_entry`` class, representing an entry in a configured
+address map.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name].map.entries[index]
+ Gets an entry from the configured map for an address space.
+
+Properties
+~~~~~~~~~~
+
+entry.address_start (read-only)
+ Start address of the entry’s range.
+entry.address_end (read-only)
+ End address of the entry’s range (inclusive).
+entry.address_mirror (read-only)
+ Address mirror bits.
+entry.address_mask (read-only)
+ Address mask bits. Only valid for handlers.
+entry.mask (read-only)
+ Lane mask, indicating which data lines on the bus are connected to the
+ handler.
+entry.cswidth (read-only)
+ The trigger width for a handler that isn’t connected to all the data lines.
+entry.read (read-only)
+ :ref:`Additional data <luascript-ref-memhandlerdata>` for the read handler.
+entry.write (read-only)
+ :ref:`Additional data <luascript-ref-memhandlerdata>` for the write handler.
+entry.share (read-only)
+ Memory share tag for making RAM entries accessible or ``nil``.
+entry.region (read-only)
+ Explicit memory region tag for ROM entries, or ``nil``. For ROM entries,
+ ``nil`` infers the region from the device tag.
+entry.region_offset (read-only)
+ Starting offset in memory region for ROM entries.
+
+
+.. _luascript-ref-memhandlerdata:
+
+Address map handler data
+------------------------
+
+Wraps MAME’s ``map_handler_data`` class, which provides configuration data to
+handlers in address maps.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.devices[tag].spaces[name].map.entries[index].read
+ Gets the read handler data for an address map entry.
+manager.machine.devices[tag].spaces[name].map.entries[index].write
+ Gets the write handler data for an address map entry.
+
+Properties
+~~~~~~~~~~
+
+data.handlertype (read-only)
+ Handler type. Will be one of ``"none"``, ``"ram"``, ``"rom"``, ``"nop"``,
+ ``"unmap"``, ``"delegate"``, ``"port"``, ``"bank"``, ``"submap"``, or
+ ``"unknown"``. Note that multiple handler type values can yield
+ ``"delegate"`` or ``"unknown"``.
+data.bits (read-only)
+ Data width for the handler in bits.
+data.name (read-only)
+ Display name for the handler, or ``nil``.
+data.tag (read-only)
+ Tag for I/O ports and memory banks, or ``nil``.
+
+
+.. _luascript-ref-memshare:
+
+Memory share
+------------
+
+Wraps MAME’s ``memory_share`` class, representing a named allocated memory zone.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.memory.shares[tag]
+ Gets a memory share by absolute tag, or ``nil`` if no such memory share
+ exists.
+manager.machine.devices[tag]:memshare(tag)
+ Gets a memory share by tag relative to a device, or ``nil`` if no such
+ memory share exists.
+
+Methods
+~~~~~~~
+
+share:read_i{8,16,32,64}(offs)
+ Reads a signed integer value of the size in bits from the specified offset
+ in the memory share.
+share:read_u{8,16,32,64}(offs)
+ Reads an unsigned integer value of the size in bits from the specified
+ offset in the memory share.
+share:write_i{8,16,32,64}(offs, val)
+ Writes a signed integer value of the size in bits to the specified offset in
+ the memory share.
+share:write_u{8,16,32,64}(offs, val)
+ Writes an unsigned integer value of the size in bits to the specified offset
+ in the memory share.
+
+Properties
+~~~~~~~~~~
+
+share.tag (read-only)
+ The absolute tag of the memory share.
+share.size (read-only)
+ The size of the memory share in bytes.
+share.length (read-only)
+ The length of the memory share in native width elements.
+share.endianness (read-only)
+ The Endianness of the memory share (``"big"`` or ``"little"``).
+share.bitwidth (read-only)
+ The native element width of the memory share in bits.
+share.bytewidth (read-only)
+ The native element width of the memory share in bytes.
+
+
+.. _luascript-ref-membank:
+
+Memory bank
+-----------
+
+Wraps MAME’s ``memory_bank`` class, representing a named memory zone
+indirection.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.memory.banks[tag]
+ Gets a memory region by absolute tag, or ``nil`` if no such memory bank
+ exists.
+manager.machine.devices[tag]:membank(tag)
+ Gets a memory region by tag relative to a device, or ``nil`` if no such
+ memory bank exists.
+
+Properties
+~~~~~~~~~~
+
+bank.tag (read-only)
+ The absolute tag of the memory bank.
+bank.entry (read/write)
+ The currently selected zero-based entry number.
+
+
+.. _luascript-ref-memregion:
+
+Memory region
+-------------
+
+Wraps MAME’s ``memory_region`` class, representing a memory region used to store
+read-only data like ROMs or the result of fixed decryptions.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.memory.regions[tag]
+ Gets a memory region by absolute tag, or ``nil`` if no such memory region
+ exists.
+manager.machine.devices[tag]:memregion(tag)
+ Gets a memory region by tag relative to a device, or ``nil`` if no such
+ memory region exists.
+
+Methods
+~~~~~~~
+
+region:read(offs, len)
+ Reads up to the specified length in bytes from the specified offset in the
+ memory region. The bytes read will be returned as a string. If the
+ specified length extends beyond the end of the memory region, the returned
+ string will be shorter than requested. Note that the data will be in host
+ byte order.
+region:read_i{8,16,32,64}(offs)
+ Reads a signed integer value of the size in bits from the specified offset
+ in the memory region. The offset is specified in bytes. Reading beyond the
+ end of the memory region returns zero.
+region:read_u{8,16,32,64}(offs)
+ Reads an unsigned integer value of the size in bits from the specified
+ offset in the memory region. The offset is specified in bytes. Reading
+ beyond the end of the memory region returns zero.
+region:write_i{8,16,32,64}(offs, val)
+ Writes a signed integer value of the size in bits to the specified offset in
+ the memory region. The offset is specified in bytes. Attempting to write
+ beyond the end of the memory region has no effect.
+region:write_u{8,16,32,64}(offs, val)
+ Writes an unsigned integer value of the size in bits to the specified offset
+ in the memory region. The offset is specified in bytes. Attempting to
+ write beyond the end of the memory region has no effect.
+
+Properties
+~~~~~~~~~~
+
+region.tag (read-only)
+ The absolute tag of the memory region.
+region.size (read-only)
+ The size of the memory region in bytes.
+region.length (read-only)
+ The length of the memory region in native width elements.
+region.endianness (read-only)
+ The Endianness of the memory region (``"big"`` or ``"little"``).
+region.bitwidth (read-only)
+ The native element width of the memory region in bits.
+region.bytewidth (read-only)
+ The native element width of the memory region in bytes.
diff --git a/docs/source/luascript/ref-render.rst b/docs/source/luascript/ref-render.rst
new file mode 100644
index 00000000000..265e52b5016
--- /dev/null
+++ b/docs/source/luascript/ref-render.rst
@@ -0,0 +1,1301 @@
+.. _luascript-ref-render:
+
+Lua Render System Classes
+=========================
+
+The render system is responsible for drawing what you see in MAME’s windows,
+including emulated screens, artwork, and UI elements.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-renderbounds:
+
+Render bounds
+-------------
+
+Wraps MAME’s ``render_bounds`` class, which represents a rectangle using
+floating-point coordinates.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.render_bounds()
+ Creates a render bounds object representing a unit square, with top left
+ corner at (0, 0) and bottom right corner at (1, 1). Note that render
+ target coordinates don’t necessarily have equal X and Y scales, so this may
+ not represent a square in the final output.
+emu.render_bounds(left, top, right, bottom)
+ Creates a render bounds object representing a rectangle with top left
+ corner at (x0, y0) and bottom right corner at (x1, y1).
+
+ The arguments must all be floating-point numbers.
+
+Methods
+~~~~~~~
+
+bounds:includes(x, y)
+ Returns a Boolean indicating whether the specified point falls within the
+ rectangle. The rectangle must be normalised for this to work (right greater
+ than left and bottom greater than top).
+
+ The arguments must both be floating-point numbers.
+bounds:set_xy(left, top, right, bottom)
+ Set the rectangle’s position and size in terms of the positions of the
+ edges.
+
+ The arguments must all be floating-point numbers.
+bounds:set_wh(left, top, width, height)
+ Set the rectangle’s position and size in terms of the top left corner
+ position, and the width and height.
+
+ The arguments must all be floating-point numbers.
+
+Properties
+~~~~~~~~~~
+
+bounds.x0 (read/write)
+ The leftmost coordinate in the rectangle (i.e. the X coordinate of the left
+ edge or the top left corner).
+bounds.x1 (read/write)
+ The rightmost coordinate in the rectangle (i.e. the X coordinate of the
+ right edge or the bottom right corner).
+bounds.y0 (read/write)
+ The topmost coordinate in the rectangle (i.e. the Y coordinate of the top
+ edge or the top left corner).
+bounds.y1 (read/write)
+ The bottommost coordinate in the rectangle (i.e. the Y coordinate of the
+ bottom edge or the bottom right corner).
+bounds.width (read/write)
+ The width of the rectangle. Setting this property changes the position of
+ the rightmost edge.
+bounds.height (read/write)
+ The height of the rectangle. Setting this property changes the position of
+ the bottommost edge.
+bounds.aspect (read-only)
+ The width-to-height aspect ratio of the rectangle. Note that this is often
+ in render target coordinates which don’t necessarily have equal X and Y
+ scales. A rectangle representing a square in the final output doesn’t
+ necessarily have an aspect ratio of 1.
+
+
+.. _luascript-ref-rendercolor:
+
+Render colour
+-------------
+
+Wraps MAME’s ``render_color`` class, which represents an ARGB (alpha, red,
+green, blue) format colour. Channels are floating-point values ranging from
+zero (0, transparent alpha or colour off) to one (1, opaque or full colour
+intensity). Colour channel values are not pre-multiplied by the alpha channel
+value.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.render_color()
+ Creates a render colour object representing opaque white (all channels set
+ to 1). This is the identity value – ARGB multiplication by this value will
+ not change a colour.
+emu.render_color(a, r, g, b)
+ Creates a render colour object with the specified alpha, red, green and
+ blue channel values.
+
+ The arguments must all be floating-point numbers in the range from zero (0)
+ to one (1), inclusive.
+
+Methods
+~~~~~~~
+
+color:set(a, r, g, b)
+ Sets the colour object’s alpha, red, green and blue channel values.
+
+ The arguments must all be floating-point numbers in the range from zero (0)
+ to one (1), inclusive.
+
+Properties
+~~~~~~~~~~
+
+color.a (read/write)
+ Alpha value, in the range of zero (0, transparent) to one (1, opaque).
+color.r (read/write)
+ Red channel value, in the range of zero (0, off) to one (1, full intensity).
+color.g (read/write)
+ Green channel value, in the range of zero (0, off) to one (1, full
+ intensity).
+color.b (read/write)
+ Blue channel value, in the range of zero (0, off) to one (1, full
+ intensity).
+
+
+.. _luascript-ref-palette:
+
+Palette
+-------
+
+Wraps MAME’s ``palette_t`` class, which represents a table of colours that can
+be looked up by zero-based index. Palettes always contain additional special
+entries for black and white.
+
+Each colour has an associated contrast adjustment value. Each adjustment group
+has associated brightness and contrast adjustment values. The palette also has
+overall brightness, contrast and gamma adjustment values.
+
+Colours are represented in alpha/red/green/blue (ARGB) format. Channel values
+range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
+Colour channel values are not pre-multiplied by the alpha value. Channel values
+are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
+green, blue from most-significant to least-significant byte.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.palette(colors, [groups])
+ Creates a palette with the specified number of colours and
+ brightness/contrast adjustment groups. The number of colour groups defaults
+ to one if not specified. Colours are initialised to black, brightness
+ adjustment is initialised to 0.0, contrast adjustment initialised to 1.0,
+ and gamma adjustment is initialised to 1.0.
+
+Methods
+~~~~~~~
+
+palette:entry_color(index)
+ Gets the colour at the specified zero-based index.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Returns black if the index is greater than or equal to the number of
+ colours in the palette.
+palette:entry_contrast(index)
+ Gets the contrast adjustment for the colour at the specified zero-based
+ index. This is a floating-point number.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Returns 1.0 if the index is greater than or equal to the number of
+ colours in the palette.
+palette:entry_adjusted_color(index, [group])
+ Gets a colour with brightness, contrast and gamma adjustments applied.
+
+ If the group is specified, colour index values range from zero to the number
+ of colours in the palette minus one, and group values range from zero to the
+ number of adjustment groups in the palette minus one.
+
+ If the group is not specified, index values range from zero to the number of
+ colours multiplied by the number of adjustment groups plus one. Index
+ values may be calculated by multiplying the zero-based group index by the
+ number of colours in the palette, and adding the zero-based colour index.
+ The last two index values correspond to the special entries for black and
+ white, respectively.
+
+ Returns black if the specified combination of index and adjustment group is
+ invalid.
+palette:entry_set_color(index, color)
+ Sets the colour at the specified zero-based index. The colour may be
+ specified as a single packed 32-bit value; or as individual red, green and
+ blue channel values, in that order.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_red_level(index, level)
+ Sets the red channel value of the colour at the specified zero-based index.
+ Other channel values are not affected.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_green_level(index, level)
+ Sets the green channel value of the colour at the specified zero-based
+ index. Other channel values are not affected.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_blue_level(index, level)
+ Sets the blue channel value of the colour at the specified zero-based index.
+ Other channel values are not affected.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:entry_set_contrast(index, level)
+ Sets the contrast adjustment value for the colour at the specified
+ zero-based index. This must be a floating-point number.
+
+ Index values range from zero to the number of colours in the palette minus
+ one. Raises an error if the index value is invalid.
+palette:group_set_brightness(group, brightness)
+ Sets the brightness adjustment value for the adjustment group at the
+ specified zero-based index. This must be a floating-point number.
+
+ Group values range from zero to the number of adjustment groups in the
+ palette minus one. Raises an error if the index value is invalid.
+palette:group_set_contrast(group, contrast)
+ Sets the contrast adjustment value for the adjustment group at the specified
+ zero-based index. This must be a floating-point number.
+
+ Group values range from zero to the number of adjustment groups in the
+ palette minus one. Raises an error if the index value is invalid.
+
+Properties
+~~~~~~~~~~
+
+palette.colors (read-only)
+ The number of colour entries in each group of colours in the palette.
+palette.groups (read-only)
+ The number of groups of colours in the palette.
+palette.max_index (read-only)
+ The number of valid colour indices in the palette.
+palette.black_entry (read-only)
+ The index of the special entry for the colour black.
+palette.white_entry (read-only)
+ The index of the special entry for the colour white.
+palette.brightness (write-only)
+ The overall brightness adjustment for the palette. This is a floating-point
+ number.
+palette.contrast (write-only)
+ The overall contrast adjustment for the palette. This is a floating-point
+ number.
+palette.gamma (write-only)
+ The overall gamma adjustment for the palette. This is a floating-point
+ number.
+
+
+.. _luascript-ref-bitmap:
+
+Bitmap
+------
+
+Wraps implementations of MAME’s ``bitmap_t`` and ``bitmap_specific`` classes,
+which represent two-dimensional bitmaps stored in row-major order. Pixel
+coordinates are zero-based, increasing to the right and down. Several pixel
+formats are supported.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.bitmap_ind8(palette, [width, height], [xslop, yslop])
+ Creates an 8-bit indexed bitmap. Each pixel is a zero-based, unsigned 8-bit
+ index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind16(palette, [width, height], [xslop, yslop])
+ Creates a 16-bit indexed bitmap. Each pixel is a zero-based, unsigned
+ 16-bit index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind32(palette, [width, height], [xslop, yslop])
+ Creates a 32-bit indexed bitmap. Each pixel is a zero-based, unsigned
+ 32-bit index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind64(palette, [width, height], [xslop, yslop])
+ Creates a 64-bit indexed bitmap. Each pixel is a zero-based, unsigned
+ 64-bit index into a :ref:`palette <luascript-ref-palette>`.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_yuy16([width, height], [xslop], yslop])
+ Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling (horizontal
+ pairs of pixels have individual luma values but share chroma values). Each
+ pixel is a 16-bit integer value. The most significant byte of the pixel
+ value is the unsigned 8-bit Y' (luma) component of the pixel colour. For
+ each horizontal pair of pixels, the least significant byte of the first
+ pixel (even zero-based X coordinate) value is the signed 8-bit Cb value for
+ the pair of pixels, and the least significant byte of the second pixel (odd
+ zero-based X coordinate) value is the signed 8-bit Cr value for the pair of
+ pixels.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_rgb32([width, height], [xslop, yslop])
+ Creates an RGB format bitmap with no alpha (transparency) channel. Each
+ pixel is represented by a 32-bit integer value. The most significant byte
+ of the pixel value is ignored. The remaining three bytes, from most
+ significant to least significant, are the unsigned 8-bit unsigned red, green
+ and blue channel values (larger values correspond to higher intensities).
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_argb32([width, height], [xslop, yslop])
+ Creates an ARGB format bitmap. Each pixel is represented by a 32-bit
+ integer value. The most significant byte of the pixel is the 8-bit unsigned
+ alpha (transparency) channel value (smaller values are more transparent).
+ The remaining three bytes, from most significant to least significant, are
+ the unsigned 8-bit unsigned red, green and blue channel values (larger
+ values correspond to higher intensities). Colour channel values are not
+ pre-multiplied by the alpha channel value.
+
+ If no width and height are specified, they are assumed to be zero. If the
+ width is specified, the height must also be specified. The X and Y slop
+ values set the amount of extra storage in pixels to reserve at the
+ left/right of each row and top/bottom of each column, respectively. If an X
+ slop value is specified, a Y slop value must be specified as well. If no X
+ and Y slop values are specified, they are assumed to be zero (the storage
+ will be sized to fit the bitmap content). If the width and/or height is
+ less than or equal to zero, no storage will be allocated, irrespective of
+ the X and Y slop values, and the width and height of the bitmap will both be
+ set to zero.
+
+ The initial clipping rectangle is set to the entirety of the bitmap.
+emu.bitmap_ind8(source, [x0, y0, x1, y1])
+ Creates an 8-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 8-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_ind16(source, [x0, y0, x1, y1])
+ Creates a 16-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 16-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_ind32(source, [x0, y0, x1, y1])
+ Creates a 32-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 32-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_ind64(source, [x0, y0, x1, y1])
+ Creates a 64-bit indexed bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the 64-bit
+ indexed format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_yuy16(source, [x0, y0, x1, y1])
+ Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling representing a
+ view of a portion of an existing bitmap. The initial clipping rectangle is
+ set to the bounds of the view. The source bitmap will be locked, preventing
+ resizing and reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the Y'CbCr
+ format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_rgb32(source, [x0, y0, x1, y1])
+ Creates an RGB format bitmap representing a view of a portion of an existing
+ bitmap. The initial clipping rectangle is set to the bounds of the view.
+ The source bitmap will be locked, preventing resizing and reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the RGB
+ format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_argb32(source, [x0, y0, x1, y1])
+ Creates an ARGB format bitmap representing a view of a portion of an
+ existing bitmap. The initial clipping rectangle is set to the bounds of the
+ view. The source bitmap will be locked, preventing resizing and
+ reallocation.
+
+ If no coordinates are specified, the new bitmap will represent a view of the
+ source bitmap’s current clipping rectangle. If coordinates are specified,
+ the new bitmap will represent a view of the rectangle with top left corner
+ at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap.
+ Coordinates are in units of pixels. The bottom right coordinates are
+ inclusive.
+
+ The source bitmap must be owned by the Lua script and must use the ARGB
+ format. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the source bitmap’s clipping rectangle.
+emu.bitmap_argb32.load(data)
+ Creates an ARGB format bitmap from data in PNG, JPEG (JFIF/EXIF) or
+ Microsoft DIB (BMP) format. Raises an error if the data invalid or not a
+ supported format.
+
+Methods
+~~~~~~~
+
+bitmap:cliprect()
+ Returns the left, top, right and bottom coordinates of the bitmap’s clipping
+ rectangle. Coordinates are in units of pixels; the bottom and right
+ coordinates are inclusive.
+bitmap:reset()
+ Sets the width and height to zero, and frees the pixel storage if the bitmap
+ owns its own storage, or releases the source bitmap if the it represents a
+ view of another bitmap.
+
+ The bitmap must be owned by the Lua script. Raises an error if the bitmap’s
+ storage is referenced by another bitmap or a :ref:`texture
+ <luascript-ref-rendertexture>`.
+bitmap:allocate(width, height, [xslop, yslop])
+ Reallocates storage for the bitmap, sets its width and height, and sets the
+ clipping rectangle to the entirety of the bitmap. If the bitmap already
+ owns allocated storage, it will always be freed and reallocated; if the
+ bitmap represents a view of another bitmap, the source bitmap will be
+ released. The storage will be filled with pixel value zero.
+
+ The X and Y slop values set the amount of extra storage in pixels to reserve
+ at the left/right of each row and top/bottom of each column, respectively.
+ If an X slop value is specified, a Y slop value must be specified as well.
+ If no X and Y slop values are specified, they are assumed to be zero (the
+ storage will be sized to fit the bitmap content). If the width and/or
+ height is less than or equal to zero, no storage will be allocated,
+ irrespective of the X and Y slop values, and the width and height of the
+ bitmap will both be set to zero.
+
+ The bitmap must be owned by the Lua script. Raises an error if the bitmap’s
+ storage is referenced by another bitmap or a :ref:`texture
+ <luascript-ref-rendertexture>`.
+bitmap:resize(width, height, [xslop, yslop])
+ Changes the width and height, and sets the clipping rectangle to the
+ entirety of the bitmap.
+
+ The X and Y slop values set the amount of extra storage in pixels to reserve
+ at the left/right of each row and top/bottom of each column, respectively.
+ If an X slop value is specified, a Y slop value must be specified as well.
+ If no X and Y slop values are specified, they are assumed to be zero (rows
+ will be stored contiguously, and the top row will be placed at the beginning
+ of the bitmap’s storage).
+
+ If the bitmap already owns allocated storage and it is large enough for the
+ updated size, it will be used without being freed; if it is too small for
+ the updated size, it will always be freed and reallocated. If the bitmap
+ represents a view of another bitmap, the source bitmap will be released. If
+ storage is allocated, it will be filled with pixel value zero (if existing
+ storage is used, its contents will not be changed).
+
+ Raises an error if the bitmap’s storage is referenced by another bitmap or a
+ :ref:`texture <luascript-ref-rendertexture>`.
+bitmap:wrap(source, [x0, y0, x1, y1])
+ Makes the bitmap represent a view of a portion of another bitmap and sets
+ the clipping rectangle to the bounds of the view.
+
+ If no coordinates are specified, the target bitmap will represent a view of
+ the source bitmap’s current clipping rectangle. If coordinates are
+ specified, the target bitmap will represent a view of the rectangle with top
+ left corner at (x0, y0) and bottom right corner at (x1, y1) in the source
+ bitmap. Coordinates are in units of pixels. The bottom right coordinates
+ are inclusive.
+
+ The source bitmap will be locked, preventing resizing and reallocation. If
+ the target bitmap owns allocated storage, it will be freed; if it represents
+ a view of another bitmap, the current source bitmap will be released.
+
+ The source and target bitmaps must both be owned by the Lua script and must
+ use the same pixel format. Raises an error if coordinates are specified
+ representing a rectangle not fully contained within the source bitmap’s
+ clipping rectangle; if the bitmap’s storage is referenced by another bitmap
+ or a :ref:`texture <luascript-ref-rendertexture>`; or if the source and
+ target are the same bitmap.
+bitmap:pix(x, y)
+ Returns the colour value of the pixel at the specified location.
+ Coordinates are zero-based in units of pixels.
+bitmap:pixels([x0, y0, x1, y1])
+ Returns the pixels, width and height of the portion of the bitmap with top
+ left corner at (x0, y0) and bottom right corner at (x1, y1). Coordinates
+ are in units of pixels. The bottom right coordinates are inclusive. If
+ coordinates are not specified, the bitmap’s clipping rectangle is used.
+
+ Pixels are returned packed into a binary string in host Endian order.
+ Pixels are organised in row-major order, from left to right then top to
+ bottom. The size and format of the pixel values depends on the format of
+ the bitmap. Raises an error if coordinates are specified representing a
+ rectangle not fully contained within the bitmap’s clipping rectangle.
+bitmap:fill(color, [x0, y0, x1, y1])
+ Fills a portion of the bitmap with the specified colour value. If
+ coordinates are not specified, the clipping rectangle is filled; if
+ coordinates are specified, the intersection of the clipping rectangle and
+ the rectangle with top left corner at (x0, y0) and bottom right corner at
+ (x1, y1) is filled. Coordinates are in units of pixels. The bottom right
+ coordinates are inclusive.
+bitmap:plot(x, y, color)
+ Sets the colour value of the pixel at the specified location if it is within
+ the clipping rectangle. Coordinates are zero-based in units of pixels.
+bitmap:plot_box(x, y, width, height, color)
+ Fills the intersection of the clipping rectangle and the rectangle with top
+ left (x, y) and the specified height and width with the specified colour
+ value. Coordinates and dimensions are in units of pixels.
+bitmap:resample(dest, [color])
+ Copies the bitmap into the destination bitmap, scaling to fill the
+ destination bitmap and using a re-sampling filter. Only ARGB format source
+ and destination bitmaps are supported. The source pixel values will be
+ multiplied by the colour if it is supplied. It must be a
+ :ref:`render colour <luascript-ref-rendercolor>`.
+
+Properties
+~~~~~~~~~~
+
+bitmap.palette (read/write)
+ The :ref:`palette <luascript-ref-palette>` used to translate pixel
+ values to colours. Only applicable for bitmaps that use indexed pixel
+ formats.
+bitmap.width (read-only)
+ Width of the bitmap in pixels.
+bitmap.height (read-only)
+ Height of the bitmap in pixels.
+bitmap.rowpixels (read-only)
+ Row stride of the bitmap’s storage in pixels. That is, the difference in
+ pixel offsets of the pixels at the same horizontal location in consecutive
+ rows. May be greater than the width.
+bitmap.rowbytes (read-only)
+ Row stride of the bitmap’s storage in bytes. That is, the difference in
+ byte addresses of the pixels at the same horizontal location in consecutive
+ rows.
+bitmap.bpp (read-only)
+ Size of the type used to represent pixels in the bitmap in bits (may be
+ larger than the number of significant bits).
+bitmap.valid (read-only)
+ A Boolean indicating whether the bitmap has storage available (may be false
+ for empty bitmaps).
+bitmap.locked (read-only)
+ A Boolean indicating whether the bitmap’s storage is referenced by another
+ bitmap or a :ref:`texture <luascript-ref-rendertexture>`.
+
+
+.. _luascript-ref-rendertexture:
+
+Render texture
+--------------
+
+Wraps MAME’s ``render_texture`` class, representing a texture that cam be drawn
+in a :ref:`render container <luascript-ref-rendercontainer>`. Render textures
+must be freed before the emulation session ends.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render:texture_alloc(bitmap)
+ Creates a render texture based on a :ref:`bitmap
+ <luascript-ref-bitmap>`. The bitmap must be owned by the Lua script, and
+ must use the Y'CbCr, RGB or ARGB format. The bitmap’s storage will be
+ locked, preventing resizing and reallocation.
+
+Methods
+~~~~~~~
+
+texture:free()
+ Frees the texture. The storage of the underlying bitmap will be released.
+
+Properties
+~~~~~~~~~~
+
+texture.valid (read-only)
+ A Boolean indicating whether the texture is valid (false if the texture has
+ been freed).
+
+
+.. _luascript-ref-renderman:
+
+Render manager
+--------------
+
+Wraps MAME’s ``render_manager`` class, responsible for managing render targets
+and textures.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render
+ Gets the global render manager instance for the emulation session.
+
+Methods
+~~~~~~~
+
+render:texture_alloc(bitmap)
+ Creates a :ref:`render texture <luascript-ref-rendertexture>` based on a
+ :ref:`bitmap <luascript-ref-bitmap>`. The bitmap must be owned by the Lua
+ script, and must use the Y'CbCr, RGB or ARGB pixel format. The bitmap’s
+ storage will be locked, preventing resizing and reallocation. Render
+ textures must be freed before the emulation session ends.
+
+Properties
+~~~~~~~~~~
+
+render.max_update_rate (read-only)
+ The maximum update rate in Hertz. This is a floating-point number.
+render.ui_target (read-only)
+ The :ref:`render target <luascript-ref-rendertarget>` used to draw the user
+ interface (including menus, sliders and pop-up messages). This is usually
+ the first host window or screen.
+render.ui_container (read-only)
+ The :ref:`render container <luascript-ref-rendercontainer>` used for drawing
+ the user interface.
+render.targets[] (read-only)
+ The list of render targets, including output windows and screens, as well as
+ hidden render targets used for things like rendering screenshots. Uses
+ 1-based integer indices. The index operator and the ``at`` method have O(n)
+ complexity.
+
+
+.. _luascript-ref-rendertarget:
+
+Render target
+-------------
+
+Wrap’s MAME’s ``render_target`` class, which represents a video output channel.
+This could be a host window or screen, or a hidden target used for rendering
+screenshots.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render.targets[index]
+ Gets a render target by index.
+manager.machine.render.ui_target
+ Gets the render target used to display the user interface (including menus,
+ sliders and pop-up messages). This is usually the first host window or
+ screen.
+manager.machine.video.snapshot_target
+ Gets the render target used to produce snapshots and video recordings.
+
+Properties
+~~~~~~~~~~
+
+target.index (read-only)
+ The 1-based index of the render target. This has O(n) complexity.
+target.width (read-only)
+ The width of the render target in output pixels. This is an integer.
+target.height (read-only)
+ The height of the render target in output pixels. This is an integer.
+target.pixel_aspect (read-only)
+ The width-to-height aspect ratio of the render target’s pixels. This is a
+ floating-point number.
+target.hidden (read-only)
+ A Boolean indicating whether this is an internal render target that is not
+ displayed to the user directly (e.g. the render target used to draw
+ screenshots).
+target.is_ui_target (read-only)
+ A Boolean indicating whether this is the render target used to display the
+ user interface.
+target.max_update_rate (read/write)
+ The maximum update rate for the render target in Hertz.
+target.orientation (read/write)
+ The target orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+target.view_names[]
+ The names of the available views for this render target. Uses 1-based
+ integer indices. The ``find`` and ``index_of`` methods have O(n)
+ complexity; all other supported operations have O(1) complexity.
+target.current_view (read-only)
+ The currently selected view for the render target. This is a
+ :ref:`layout view <luascript-ref-renderlayview>` object.
+target.view_index (read/write)
+ The 1-based index of the selected view for this render target.
+target.visibility_mask (read-only)
+ An integer bit mask indicating which item collections are currently visible
+ for the current view.
+target.screen_overlay (read/write)
+ A Boolean indicating whether screen overlays are enabled.
+target.zoom_to_screen (read/write)
+ A Boolean indicating whether the render target is configured to scale so
+ that the emulated screen(s) fill as much of the output window/screen as
+ possible.
+
+
+.. _luascript-ref-rendercontainer:
+
+Render container
+----------------
+
+Wraps MAME’s ``render_container`` class.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render.ui_container
+ Gets the render container used to draw the user interface, including menus,
+ sliders and pop-up messages.
+manager.machine.screens[tag].container
+ Gets the render container used to draw a given screen.
+
+Methods
+~~~~~~~
+
+container:draw_box(left, top, right, bottom, [line], [fill])
+ Draws an outlined rectangle with edges at the specified positions.
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ the screen that shows the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or screen area.
+
+ The fill and line colours are in alpha/red/green/blue (ARGB) format.
+ Channel values are in the range 0 (transparent or off) to 255 (opaque or
+ full intensity), inclusive. Colour channel values are not pre-multiplied by
+ the alpha value. The channel values must be packed into the bytes of a
+ 32-bit unsigned integer, in the order alpha, red, green, blue from
+ most-significant to least-significant byte. If the line colour is not
+ provided, the UI text colour is used; if the fill colour is not provided,
+ the UI background colour is used.
+container:draw_line(x0, y0, x1, y1, [color])
+ Draws a line from (x0, y0) to (x1, y1).
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ the screen that shows the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or screen area.
+
+ The line colour is in alpha/red/green/blue (ARGB) format. Channel values
+ are in the range 0 (transparent or off) to 255 (opaque or full intensity),
+ inclusive. Colour channel values are not pre-multiplied by the alpha value.
+ The channel values must be packed into the bytes of a 32-bit unsigned
+ integer, in the order alpha, red, green, blue from most-significant to
+ least-significant byte. If the line colour is not provided, the UI text
+ colour is used.
+container:draw_quad(texture, x0, y0, x1, y1, [color])
+ Draws a textured rectangle with top left corner at (x0, y0) and bottom right
+ corner at (x1, y1). If a colour is specified, the ARGB channel values of
+ the texture’s pixels are multiplied by the corresponding values of the
+ specified colour.
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ the screen that shows the user interface. Note that the aspect ratio is
+ usually not square. If the rectangle extends beyond the container’s bounds,
+ it will be cropped.
+
+ The colour is in alpha/red/green/blue (ARGB) format. Channel values are in
+ the range 0 (transparent or off) to 255 (opaque or full intensity),
+ inclusive. Colour channel values are not pre-multiplied by the alpha value.
+ The channel values must be packed into the bytes of a 32-bit unsigned
+ integer, in the order alpha, red, green, blue from most-significant to
+ least-significant byte.
+container:draw_text(x|justify, y, text, [foreground], [background])
+ Draws text at the specified position. If the screen is rotated the text
+ will be rotated.
+
+ If the first argument is a number, the text will be left-aligned at this X
+ coordinate. If the first argument is a string, it must be ``"left"``,
+ ``"center"`` or ``"right"`` to draw the text left-aligned at the
+ left edge of the window or screen, horizontally centred in the window or
+ screen, or right-aligned at the right edge of the window or screen,
+ respectively. The second argument specifies the Y coordinate of the maximum
+ ascent of the text.
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ the screen that shows the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or screen area.
+
+ The foreground and background colours are in alpha/red/green/blue (ARGB)
+ format. Channel values are in the range 0 (transparent or off) to 255
+ (opaque or full intensity), inclusive. Colour channel values are not
+ pre-multiplied by the alpha value. The channel values must be packed into
+ the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
+ from most-significant to least-significant byte. If the foreground colour
+ is not provided, the UI text colour is used; if the background colour is not
+ provided, it is fully transparent.
+
+Properties
+~~~~~~~~~~
+
+container.user_settings (read/write)
+ The container’s :ref:`user settings <luascript-ref-rendercntnrsettings>`.
+ This can be used to control a number of image adjustments.
+container.orientation (read/write)
+ The container orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+container.xscale (read/write)
+ The container’s X scale factor. This is a floating-point number.
+container.yscale (read/write)
+ The container’s Y scale factor. This is a floating-point number.
+container.xoffset (read/write)
+ The container’s X offset. This is a floating-point number where one (1)
+ corresponds to the X size of the container.
+container.yoffset (read/write)
+ The container’s Y offset. This is a floating-point number where one (1)
+ corresponds to the Y size of the container.
+container.is_empty (read-only)
+ A Boolean indicating whether the container has no items.
+
+
+.. _luascript-ref-rendercntnrsettings:
+
+Container user settings
+-----------------------
+
+Wraps MAME’s ``render_container::user_settings`` class, representing image
+adjustments applied to a
+:ref:`render container <luascript-ref-rendercontainer>`.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.screens[tag].container
+ Gets the current render container user settings for a given emulated screen.
+
+Properties
+~~~~~~~~~~
+
+settings.orientation (read/write)
+ The container orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+settings.brightness (read/write)
+ The brightness adjustment applied to the container. This is a
+ floating-point number.
+settings.contrast (read/write)
+ The contrast adjustment applied to the container. This is a floating-point
+ number.
+settings.gamma (read/write)
+ The gamma adjustment applied to the container. This is a floating-point
+ number.
+settings.xscale (read/write)
+ The container’s X scale factor. This is a floating-point number.
+settings.yscale (read/write)
+ The container’s Y scale factor. This is a floating-point number.
+settings.xoffset (read/write)
+ The container’s X offset. This is a floating-point number where one (1)
+ represents the X size of the container.
+settings.yoffset (read/write)
+ The container’s Y offset. This is a floating-point number where one (1)
+ represents the Y size of the container.
+
+
+.. _luascript-ref-renderlayfile:
+
+Layout file
+-----------
+
+Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
+file for use by a render target. Note that layout file callbacks are not run as
+coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+A layout file object is supplied to its layout script in the ``file`` variable.
+Layout file objects are not instantiated directly from Lua scripts.
+
+Methods
+~~~~~~~
+
+layout:set_resolve_tags_callback(cb)
+ Set a function to perform additional tasks after the emulated machine has
+ finished starting, tags in the layout views have been resolved, and the
+ default view item handlers have been set up. The function must accept no
+ arguments.
+
+ Call with ``nil`` to remove the callback.
+
+Properties
+~~~~~~~~~~
+
+layout.device (read-only)
+ The device that caused the layout file to be loaded. Usually the root
+ machine device for external layouts.
+layout.elements[] (read-only)
+ The :ref:`elements <luascript-ref-renderlayelem>` created from the layout
+ file. Elements are indexed by name (i.e. the value of the ``name``
+ attribute). The index get method has O(1) complexity, and the ``at`` and
+ ``index_of`` methods have O(n) complexity.
+layout.views[] (read-only)
+ The :ref:`views <luascript-ref-renderlayview>` created from the layout file.
+ Views are indexed by unqualified name (i.e. the value of the ``name``
+ attribute). Views are ordered how they appear in the layout file when
+ iterating or using the ``at`` method. The index get, ``at`` and
+ ``index_of`` methods have O(n) complexity.
+
+ Note that some views in the XML file may not be created. For example views
+ that reference screens provided by slot card devices will not be created if
+ said slot card devices are not present in the emulated system.
+
+
+.. _luascript-ref-renderlayview:
+
+Layout view
+-----------
+
+Wraps MAME’s ``layout_view`` class, representing a view that can be displayed in
+a render target. Views are created from XML layout files, which may be loaded
+from external artwork, internal to MAME, or automatically generated based on the
+screens in the emulated system. Note that layout view callbacks are not run as
+coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.render.targets[index].current_view
+ Gets the currently selected view for a given render target.
+file.views[name]
+ Gets the view with the specified name from a
+ :ref:`layout file <luascript-ref-renderlayfile>`. This is how layout
+ scripts generally obtain views.
+
+Methods
+~~~~~~~
+
+view:has_screen(screen)
+ Returns a Boolean indicating whether the screen is present in the view.
+ This is true for screens that are present but not visible because the user
+ has hidden the item collection they belong to.
+view:set_prepare_items_callback(cb)
+ Set a function to perform additional tasks before the view items are added
+ to the render target in preparation for drawing a video frame. The function
+ must accept no arguments. Call with ``nil`` to remove the callback.
+view:set_preload_callback(cb)
+ Set a function to perform additional tasks after preloading visible view
+ items. The function must accept no arguments. Call with ``nil`` to remove
+ the callback.
+
+ This function may be called when the user selects a view or makes an item
+ collection visible. It may be called multiple times for a view, so avoid
+ repeating expensive tasks.
+view:set_recomputed_callback(cb)
+ Set a function to perform additional tasks after the view’s dimensions are
+ recomputed. The function must accept no arguments. Call with ``nil`` to
+ remove the callback.
+
+ View coordinates are recomputed in various events, including the window
+ being resized, entering or leaving full-screen mode, and changing the zoom
+ to screen area setting.
+
+Properties
+~~~~~~~~~~
+
+view.items[] (read-only)
+ The screen and layout element :ref:`items <luascript-ref-renderlayitem>` in
+ the view. This container does not support iteration by key using ``pairs``;
+ only iteration by index using ``ipairs`` is supported. The key is the value
+ of the ``id`` attribute if present. Only items with ``id`` attributes can
+ be looked up by key. The index get method has O(1) complexity, and the
+ ``at`` and ``index_of`` methods have O(n) complexity.
+view.name (read-only)
+ The display name for the view. This may be qualified to indicate the device
+ that caused the layout file to be loaded when it isn’t the root machine
+ device.
+view.unqualified_name (read-only)
+ The unqualified name of the view, exactly as it appears in the ``name``
+ attribute in the XML layout file.
+view.visible_screen_count (read-only)
+ The number of screens items currently enabled in the view.
+view.effective_aspect (read-only)
+ The effective width-to-height aspect ratio of the view in its current
+ configuration.
+view.bounds (read-only)
+ A :ref:`render bounds <luascript-ref-renderbounds>` object representing the
+ effective bounds of the view in its current configuration. The coordinates
+ are in view units, which are arbitrary but assumed to have square aspect
+ ratio.
+view.has_art
+ A Boolean indicating whether the view has any non-screen items, including
+ items that are not visible because the user has hidden the item collection
+ that they belong to.
+
+
+.. _luascript-ref-renderlayitem:
+
+Layout view item
+----------------
+
+Wraps MAME’s ``layout_view_item`` class, representing an item in a :ref:`layout
+view <luascript-ref-renderlayview>`. An item is drawn as a rectangular textured
+surface. The texture is supplied by an emulated screen or a layout element.
+Note that layout view item callbacks are not run as coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+layout.views[name].items[id]
+ Get a view item by ID. The item must have an ``id`` attribute in the XML
+ layout file to be looked up by ID.
+
+Methods
+~~~~~~~
+
+item:set_state(state)
+ Set the value used as the element state and animation state in the absence
+ of bindings. The argument must be an integer.
+item:set_element_state_callback(cb)
+ Set a function to call to obtain the element state for the item. The
+ function must accept no arguments and return an integer. Call with ``nil``
+ to restore the default element state callback (based on bindings in the XML
+ layout file).
+
+ Note that the function must not access the item’s ``element_state``
+ property, as this will result in infinite recursion.
+
+ This callback will not be used to obtain the animation state for the item,
+ even if the item lacks explicit animation state bindings in the XML layout
+ file.
+item:set_animation_state_callback(cb)
+ Set a function to call to obtain the animation state for the item. The
+ function must accept no arguments and return an integer. Call with ``nil``
+ to restore the default animation state callback (based on bindings in the
+ XML layout file).
+
+ Note that the function must not access the item’s ``animation_state``
+ property, as this will result in infinite recursion.
+item:set_bounds_callback(cb)
+ Set a function to call to obtain the bounds for the item. The function must
+ accept no arguments and return a
+ :ref:`render bounds <luascript-ref-renderbounds>` object in render target
+ coordinates. Call with ``nil`` to restore the default bounds callback
+ (based on the item’s animation state and ``bounds`` child elements in the
+ XML layout file).
+
+ Note that the function must not access the item’s ``bounds`` property, as
+ this will result in infinite recursion.
+item:set_color_callback(cb)
+ Set a function to call to obtain the multiplier colour for the item. The
+ function must accept no arguments and return a
+ :ref:`render colour <luascript-ref-rendercolor>` object. Call with ``nil``
+ to restore the default colour callback (based on the item’s animation state
+ and ``color`` child elements in the XML layout file).
+
+ Note that the function must not access the item’s ``color`` property, as
+ this will result in infinite recursion.
+item:set_scroll_size_x_callback(cb)
+ Set a function to call to obtain the size of the horizontal scroll window as
+ a proportion of the associated element’s width. The function must accept no
+ arguments and return a floating-point value. Call with ``nil`` to restore
+ the default horizontal scroll window size callback (based on the ``xscroll``
+ child element in the XML layout file).
+
+ Note that the function must not access the item’s ``scroll_size_x``
+ property, as this will result in infinite recursion.
+item:set_scroll_size_y_callback(cb)
+ Set a function to call to obtain the size of the vertical scroll window as a
+ proportion of the associated element’s height. The function must accept no
+ arguments and return a floating-point value. Call with ``nil`` to restore
+ the default vertical scroll window size callback (based on the ``yscroll``
+ child element in the XML layout file).
+
+ Note that the function must not access the item’s ``scroll_size_y``
+ property, as this will result in infinite recursion.
+item:set_scroll_pos_x_callback(cb)
+ Set a function to call to obtain the horizontal scroll position. A value of
+ zero places the horizontal scroll window at the left edge of the associated
+ element. If the item does not wrap horizontally, a value of 1.0 places the
+ horizontal scroll window at the right edge of the associated element; if the
+ item wraps horizontally, a value of 1.0 corresponds to wrapping back to the
+ left edge of the associated element. The function must accept no arguments
+ and return a floating-point value. Call with ``nil`` to restore the default
+ horizontal scroll position callback (based on bindings in the ``xscroll``
+ child element in the XML layout file).
+
+ Note that the function must not access the item’s ``scroll_pos_x`` property,
+ as this will result in infinite recursion.
+item:set_scroll_pos_y_callback(cb)
+ Set a function to call to obtain the vertical scroll position. A value of
+ zero places the vertical scroll window at the top edge of the associated
+ element. If the item does not wrap vertically, a value of 1.0 places the
+ vertical scroll window at the bottom edge of the associated element; if the
+ item wraps vertically, a value of 1.0 corresponds to wrapping back to the
+ left edge of the associated element. The function must accept no arguments
+ and return a floating-point value. Call with ``nil`` to restore the default
+ vertical scroll position callback (based on bindings in the ``yscroll``
+ child element in the XML layout file).
+
+ Note that the function must not access the item’s ``scroll_pos_y`` property,
+ as this will result in infinite recursion.
+
+Properties
+~~~~~~~~~~
+
+item.id (read-only)
+ Get the optional item identifier. This is the value of the ``id`` attribute
+ in the XML layout file if present, or ``nil``.
+item.element (read-only)
+ The :ref:`element <luascript-ref-renderlayelem>` used to draw the item, or
+ ``nil`` for screen items.
+item.bounds_animated (read-only)
+ A Boolean indicating whether the item’s bounds depend on its animation
+ state.
+item.color_animated (read-only)
+ A Boolean indicating whether the item’s colour depends on its animation
+ state.
+item.bounds (read-only)
+ The item’s bounds for the current state. This is a
+ :ref:`render bounds <luascript-ref-renderbounds>` object in render target
+ coordinates.
+item.color (read-only)
+ The item’s colour for the current state. The colour of the screen or
+ element texture is multiplied by this colour. This is a
+ :ref:`render colour <luascript-ref-rendercolor>` object.
+item.scroll_wrap_x (read-only)
+ A Boolean indicating whether the item wraps horizontally.
+item.scroll_wrap_y (read-only)
+ A Boolean indicating whether the item wraps vertically.
+item.scroll_size_x (read/write)
+ Get the item’s horizontal scroll window size for the current state, or set
+ the horizontal scroll window size to use in the absence of bindings. This
+ is a floating-point value representing a proportion of the associated
+ element’s width.
+item.scroll_size_y (read/write)
+ Get the item’s vertical scroll window size for the current state, or set the
+ vertical scroll window size to use in the absence of bindings. This is a
+ floating-point value representing a proportion of the associated element’s
+ height.
+item.scroll_pos_x (read/write)
+ Get the item’s horizontal scroll position for the current state, or set the
+ horizontal scroll position size to use in the absence of bindings. This is
+ a floating-point value.
+item.scroll_pos_y (read/write)
+ Get the item’s vertical scroll position for the current state, or set the
+ vertical position size to use in the absence of bindings. This is a
+ floating-point value.
+item.blend_mode (read-only)
+ Get the item’s blend mode. This is an integer value, where 0 means no
+ blending, 1 means alpha blending, 2 means RGB multiplication, 3 means
+ additive blending, and -1 allows the items within a container to specify
+ their own blending modes.
+item.orientation (read-only)
+ Get the item orientation flags. This is an integer bit mask, where bit 0
+ (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
+ vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
+ right diagonal.
+item.element_state (read-only)
+ Get the current element state. This will call the element state callback
+ function to handle bindings.
+item.animation_state (read-only)
+ Get the current animation state. This will call the animation state
+ callback function to handle bindings.
+
+
+.. _luascript-ref-renderlayelem:
+
+Layout element
+--------------
+
+Wraps MAME’s ``layout_element`` class, representing a visual element that can be
+drawn in a :ref:`layout view <luascript-ref-renderlayview>`. Elements are
+created from XML layout files, which may be loaded from external artwork or
+internal to MAME. Note that layout element callbacks are not run as coroutines.
+
+Instantiation
+~~~~~~~~~~~~~
+
+layout.elements[name]
+ Gets a layout element by name.
+layout.views[name].items[id].element
+ Gets the layout element used to draw a
+ :ref:`view item <luascript-ref-renderlayitem>`.
+
+Methods
+~~~~~~~
+
+element:invalidate()
+ Invalidate all cached textures for the element, ensuring it will be redrawn
+ when the next video frame is drawn.
+element.set_draw_callback(cb)
+ Set a function to call the perform additional drawing after the element’s
+ components have been drawn. The function is passed two arguments: the
+ element state (an integer) and the 32-bit ARGB
+ :ref:`bitmap <luascript-ref-bitmap>` at the required size. The function
+ must not attempt to resize the bitmap. Call with ``nil`` to remove the
+ callback.
+
+Properties
+~~~~~~~~~~
+
+element.default_state (read-only)
+ The integer default state for the element if set or ``nil``.
diff --git a/docs/source/plugins/autofire.rst b/docs/source/plugins/autofire.rst
index 56adef9b66f..2cb974626d2 100644
--- a/docs/source/plugins/autofire.rst
+++ b/docs/source/plugins/autofire.rst
@@ -46,13 +46,13 @@ button are the same.
Select **Input** to set the emulated button that you want to simulate pressing
repeatedly. Currently, only player buttons are supported. Typically you’ll set
this to the primary fire button for shooting games. This is most often *P1
-Button 1* or the equivalent for another player, but it might have have a
-different name. On Konami’s Gradius games, *P1 Button 2* is the primary fire
+Button 1* or the equivalent for another player, but it might have a
+different name. On Konami’s Gradius games, *P1 Button 2* is the primary fire
button.
-Select **Hotkey** to set the input combination you’ll use to activate the
-autofire button. This can be any combination that MAME supports for activating
-a digital input.
+Select **Hotkey** to set the control (or combination of controls) you’ll use to
+activate the autofire button. This can be any combination that MAME supports
+for activating a digital input.
**On frames** and **Off frames** are the number of consecutive emulated video
frames that the emulated button will be held and released for, respectively.
@@ -66,10 +66,10 @@ Experiment with different values to get the best effect.
When adding a new autofire button, there is a **Cancel** option that changes to
**Create** after you set the input and hotkey. Select **Create** to finish
creating the autofire button and return to the list of autofire buttons. The
-new autofire button will be added at the end of the list. Press the UI Cancel
-key (Escape/Esc on the keyboard by default), or select **Cancel** before setting
-the input/hotkey, to return to the previous menu without creating the new
-autofire button.
+new autofire button will be added at the end of the list. Press the UI Back key
+(Escape/Esc on the keyboard by default), or select **Cancel** before setting the
+input/hotkey, to return to the previous menu without creating the new autofire
+button.
When modifying an existing autofire button, select **Done** or press the UI
Cancel key to return to the list of autofire buttons. Changes take effect
@@ -81,10 +81,10 @@ immediately.
Notes and potential pitfalls
----------------------------
-Autofire buttons act as if they’re wired in parallel with MAME’s regular inputs.
-This means that if you set the activation hotkey for an autofire button to a
-button or key that’s also assigned to one of the emulated inputs directly, you
-may get unexpected results. Using Gradius as an example:
+Autofire buttons act as if they’re wired in parallel with MAME’s regular
+controls. This means that if you set the activation hotkey for an autofire
+button to a button or key that’s also assigned to one of the emulated inputs
+directly, you may get unexpected results. Using Gradius as an example:
* Suppose you set button 1 on your controller to fire, and set an autofire
hotkey to button 1 as well. Holding the button down to shoot will not trigger
@@ -97,8 +97,8 @@ may get unexpected results. Using Gradius as an example:
powerup because the powerup button is also being held down along with the
autofire button.
-It is suggested you choose input combinations for autofire hotkeys that are not
-assigned to any other emulated inputs in the system.
+It is recommended that you choose control combinations for autofire hotkeys that
+are not assigned to any other emulated inputs in the system.
Autofire is not necessarily desirable in all situations. For example using
autofire in Super-X with the blue “lightning” weapon equipped at high power
diff --git a/docs/source/plugins/console.rst b/docs/source/plugins/console.rst
index 0afdb1f796c..79aa6c929a3 100644
--- a/docs/source/plugins/console.rst
+++ b/docs/source/plugins/console.rst
@@ -6,4 +6,4 @@ Console Plugin
The console plugin provides functionality for MAME’s interactive Lua console.
It is not used directly. Use the
:ref:`console option <mame-commandline-console>` to activate the interactive Lua
-console. See :ref:`luaengine` for more information about MAME’s Lua API.
+console. See :ref:`luascript` for more information about MAME’s Lua API.
diff --git a/docs/source/plugins/data.rst b/docs/source/plugins/data.rst
index 8c19db64779..01c5d641307 100644
--- a/docs/source/plugins/data.rst
+++ b/docs/source/plugins/data.rst
@@ -23,8 +23,7 @@ files.
The following files are supported:
history.xml
- From `Gaming-History <https://www.arcade-history.com/>`_ (formerly
- Arcade-History)
+ From Gaming-History (formerly Arcade-History)
mameinfo.dat
From `MASH’s MAMEINFO <https://mameinfo.mameworld.info/>`_
messinfo.dat
@@ -53,6 +52,7 @@ plugin can also show high scores from non-volatile memory or saved by the
Note that you can only use a single file of each type at a time. You cannot,
for example, use the English and Japanese **mameinfo.dat** files simultaneously.
-The data plugin creates a **history.db** file in the first configured DATs
-folder. This file stores the information from the support files in a format
-suitable for rapid loading. It uses the SQLite3 database format.
+The data plugin creates a **history.db** file in the **data** folder in the
+plugin data folder (see the :ref:`homepath option <mame-commandline-homepath>`).
+This file stores the information from the support files in a format suitable for
+rapid loading. It uses the SQLite3 database format.
diff --git a/docs/source/plugins/discord.rst b/docs/source/plugins/discord.rst
index c3cefe22eef..7d0aac9c90d 100644
--- a/docs/source/plugins/discord.rst
+++ b/docs/source/plugins/discord.rst
@@ -3,7 +3,7 @@
Discord Presence Plugin
=======================
-The Dicord presence plugin works with the Discord app for Windows, macOS or
+The Discord presence plugin works with the Discord app for Windows, macOS or
Linux to set your activity to show what you’re doing in MAME. The activity is
set to *In menu* if you’re using the system or software selection menu,
*Playing* if emulation is running, or *Paused* if emulation is paused. The
diff --git a/docs/source/plugins/dummy.rst b/docs/source/plugins/dummy.rst
index 78cc262c53e..21c4c72309c 100644
--- a/docs/source/plugins/dummy.rst
+++ b/docs/source/plugins/dummy.rst
@@ -4,6 +4,5 @@ Dummy Test Plugin
=================
This is a sample plugin that shows how to set necessary plugin metadata,
-register callbacks, and display a simple menu. It prints status messages if the
-:ref:`verbose <mame-commandline-verbose>` option is on, and it adds a **Dummy**
-option to the **Plugin Options** menu.
+register callbacks, and display a simple menu. It prints status messages, and
+it adds a **Dummy** option to the **Plugin Options** menu.
diff --git a/docs/source/plugins/index.rst b/docs/source/plugins/index.rst
index 7807c333952..38dfb393f3e 100644
--- a/docs/source/plugins/index.rst
+++ b/docs/source/plugins/index.rst
@@ -14,7 +14,7 @@ Introduction
MAME supports plugins that can provide additional functionality. Plugins
have been written to communicate with external programs, play games
automatically, display internal game structures like hitboxes, provide alternate
-user interfaces, and automatically test emulation. See :ref:`luaengine` for
+user interfaces, and automatically test emulation. See :ref:`luascript` for
more information about MAME’s Lua API.
@@ -35,7 +35,7 @@ in an INI file or on the command line).
Many plugins need to store settings and/or data. The
:ref:`homepath option <mame-commandline-homepath>` sets the folder where plugins
should save data (defaults to the working directory). You can change this by
-selecting **Configure Options** from the system selection menu, thens selecting
+selecting **Configure Options** from the system selection menu, then selecting
**Configure Directories**, and then selecting **Plugin Data**.
To turn individual plugins on or off, first make sure plugins are enabled, then
diff --git a/docs/source/plugins/inputmacro.rst b/docs/source/plugins/inputmacro.rst
index 99f8a3448fc..959faa05fbe 100644
--- a/docs/source/plugins/inputmacro.rst
+++ b/docs/source/plugins/inputmacro.rst
@@ -55,12 +55,12 @@ whole:
descriptive. Press the UI Select key (Return/Enter on the keyboard or the
first button on the first joystick by default) to edit the current name, or
press the UI Clear key to type a new name. Press the UI Select key before
- moving to another menu item to save the new name; press the UI Cancel key
+ moving to another menu item to save the new name; press the UI Back key
(Escape/Esc on the keyboard by default) to change discard the new name.
-* Select **Activation sequence** to set the key or button combination you want
- to use to activate the macro. Keep in mind that regular input settings still
- apply, so you probably want to use a combination that isn’t being used for any
- other emulated input in the system.
+* Select **Activation combination** to set the control (or combination of
+ controls) you want to use to activate the macro. Keep in mind that regular
+ input assignments still apply, so you will probably want to use a combination
+ that isn’t being used for any other emulated input in the system.
* Set **On release** to specify what should happen if the activation sequence is
released before the macro completes. When set to *Stop immediately*, any
emulated inputs activated by the macro will be released immediately, and no
@@ -112,11 +112,11 @@ When creating a new macro, there is a **Cancel** option that changes to
**Create** after you set the activating sequence and the first input for the
initially created step. Select **Create** to finish creating the macro and
return to the list of input macros. The new macro will be added at the end of
-the list. Press the UI Cancel key, or select **Cancel** before setting the
+the list. Press the UI Back key, or select **Cancel** before setting the
activation sequence/input, to return to the previous menu without creating the
new macro.
-When editing an existing macro, select **Done** or press the UI Cancel key to
+When editing an existing macro, select **Done** or press the UI Back key to
return to the list of input macros. Changes take effect immediately.
@@ -133,7 +133,7 @@ thing could be achieved using the :ref:`plugins-autofire`, but this demonstrates
a simple looping macro:
* **Name**: P1 Autofire
-* **Activation sequence**: Kbd Space
+* **Activation combination**: Kbd Space
* **On release**: Stop immediately
* **When held**: Loop to step 2
* **Step 1**:
@@ -159,7 +159,7 @@ This allows you to run in Konami Track & Field by holding a single button. This
takes most of the skill (and fun) out of the game:
* **Name**: P1 Sprint
-* **Activation sequence**: Kbd Shift
+* **Activation combination**: Kbd Shift
* **On release**: Stop immediately
* **When held**: Loop to step 2
* **Step 1**:
@@ -188,7 +188,7 @@ This macro allows you to perform a right-facing Shōryūken (Dragon Punch) by
pressing a single key:
* **Name**: 1P Shoryuken LP
-* **Activation sequence**: Kbd M
+* **Activation combination**: Kbd M
* **On release**: Complete macro
* **When held**: Prolong step 6
* **Step 1**:
@@ -224,7 +224,7 @@ pressing a single key:
* **Duration (frames)**: 1
* **Input 1**: P1 Jab Punch
-This macro has has involves steps that activate multiple inputs. The macro will
+This macro involves steps that activate multiple inputs. The macro will
complete if the activation sequence is released early, allowing you to tap the
key momentarily to perform the move. Holding the activation sequence holds down
the attack button.
diff --git a/docs/source/security.rst b/docs/source/security.rst
index d8fc372c614..4e26c4ae97a 100644
--- a/docs/source/security.rst
+++ b/docs/source/security.rst
@@ -1,7 +1,7 @@
MAME and security concerns
==========================
-MAME is not intended or designed to run in secure sites. It has not been security audited for such types of usage, and has been known in the past to have flaws that could be used for malicious intent if run as administator or root.
+MAME is not intended or designed to run in secure sites. It has not been security audited for such types of usage, and has been known in the past to have flaws that could be used for malicious intent if run as administrator or root.
**We do not suggest or condone the use of MAME as administrator or root and use as such is done at your own risk.**
diff --git a/docs/source/techspecs/device_disasm_interface.rst b/docs/source/techspecs/device_disasm_interface.rst
index beacaf8e6df..a2ab4fa7eec 100644
--- a/docs/source/techspecs/device_disasm_interface.rst
+++ b/docs/source/techspecs/device_disasm_interface.rst
@@ -168,7 +168,7 @@ A CPU core derives from **device_disasm_interface** through
That method must return a pointer to a newly allocated disassembler
object. The caller takes ownership and handles the lifetime.
-THis method will be called at most one in the lifetime of the cpu
+This method will be called at most one in the lifetime of the cpu
object.
4. Disassembler configuration and communication
@@ -184,7 +184,7 @@ model name), feel free to use a parameter. Otherwise derive the
class.
Dynamic configuration must be done by first defining a nested public
-struct called "config" in the disassembler, with virtual destructor
+struct called ``config`` in the disassembler, with virtual destructor
and pure virtual methods to pull the required information. A pointer
to that struct should be passed to the disassembler constructor. The
cpu core should then add a derivation from that config struct and
@@ -195,9 +195,9 @@ the config class to give the information.
----------------
There currently is no way for the debugger GUI to add per-core
-configuration. It is needed for in particular the s2650 and the
-saturn cores. It should go through the cpu core class itself, since
-it's pulled from the config struct.
+configuration. In particular, it is needed for the s2650 and Saturn
+cores. It should go through the cpu core class itself, since it's
+pulled from the config struct.
There is support missing in unidasm for per-cpu configuration. That's
needed for a lot of things, see the unidasm source code for the
diff --git a/docs/source/techspecs/device_memory_interface.rst b/docs/source/techspecs/device_memory_interface.rst
index 2eae46f3906..1f8e2b1c37b 100644
--- a/docs/source/techspecs/device_memory_interface.rst
+++ b/docs/source/techspecs/device_memory_interface.rst
@@ -68,7 +68,7 @@ describing its configuration. Some examples to look up when needed:
The ``has_configured_map`` method allows to test whether an
``address_map`` has been associated with a given space in the
-``memory_space_config`` method . That allows optional memory spaces to
+``memory_space_config`` method. That allows optional memory spaces to
be implemented, such as ``AS_OPCODES`` in certain CPU cores.
@@ -152,14 +152,17 @@ Indicates whether a given space actually exists.
.. code-block:: C++
- bool translate(int spacenum, int intention, offs_t &address);
+ bool translate(int spacenum, int intention, offs_t &address, address_space *&target_space);
Does a logical to physical address translation through the device's
MMU. spacenum gives the space number, intention for the type of the
-future access (``TRANSLATE_(READ\|WRITE\|FETCH)(\|_USER\|_DEBUG)``)
-and address is an in/out parameter holding the address to translate on
-entry and the translated version on return. Should return ``true`` if
-the translation went correctly, or ``false`` if the address is unmapped.
+future access (``TR_(READ\|WRITE\|FETCH)``), address is an in/out
+parameter holding the address to translate on entry and the translated
+version on return, and finally target_space is the actual space the
+access would end up in, which may be in a different device. Should
+return ``true`` if the translation went correctly, or ``false`` if the
+address is unmapped. The call must not change the state of the
+device.
Note that for some historical reason, the device itself must override
the virtual method ``memory_translate`` with the same signature.
diff --git a/docs/source/techspecs/floppy.rst b/docs/source/techspecs/floppy.rst
index 609e5c53013..39060d4eddf 100644
--- a/docs/source/techspecs/floppy.rst
+++ b/docs/source/techspecs/floppy.rst
@@ -23,7 +23,7 @@ The new floppy subsystem aims at emulating the behaviour of floppies and floppy
A floppy disk is a disc that stores magnetic orientations on their surface disposed in a series on concentric circles called tracks or cylinders [1]_. Its main characteristics are its size (goes from a diameter of around 2.8" to 8") , its number of writable sides (1 or 2) and its magnetic resistivity. The magnetic resistivity indicates how close magnetic orientation changes can happen and the information kept. That's one third of what defines the term "density" that is so often used for floppies (the other two are floppy drive head size and bit-level encoding).
-The magnetic orientations are always binary, e.g. they're one way or the opposite, there's no intermediate state. Their direction can either be tengentially to the track, e.g in the direction or opposite to the rotation, or in the case of perpendicular recording the direction is perpendicular to the disc surface (hence the name). Perpendicular recording allows for closer orientation changes by writing the magnetic information more deeply, but arrived late in the technology lifetime. 2.88Mb disks and the floppy children (Zip drives, etc) used perpendicular recording. For simulation purposes the direction is not important, only the fact that only two orientations are possible is. Two more states are possible though: a portion of a track can be demagnetized (no orientation) or damaged (no orientation and can't be written to).
+The magnetic orientations are always binary, e.g. they're one way or the opposite, there's no intermediate state. Their direction can either be tangentially to the track, i.e. in the direction of or opposite to the rotation, or in the case of perpendicular recording the direction is perpendicular to the disc surface (hence the name). Perpendicular recording allows for closer orientation changes by writing the magnetic information more deeply, but arrived late in the technology lifetime. 2.88Mb disks and the floppy children (Zip drives, etc.) used perpendicular recording. For simulation purposes the direction is not important, only the fact that only two orientations are possible is. Two more states are possible though: a portion of a track can be demagnetized (no orientation) or damaged (no orientation and can't be written to).
A specific position in the disk rotation triggers an index pulse. That position can be detected through a hole in the surface (very visible in 5.25" and 3" floppies for instance) or through a specific position of the rotating center (3.5" floppies, perhaps others). This index pulse is used to designate the beginning of the track, but is not used by every system. Older 8" floppies have multiple index holes used to mark the beginning of sectors (called hard sectoring) but one of them is positioned differently to be recognized as the track start, and the others are at fixed positions relative to the origin one.
@@ -70,7 +70,7 @@ In every cell there may or may not be a magnetic orientation transition, e.g. a
Of course protections play with that to make formats not reproducible by the system controller, either breaking the three-zeroes rule or playing with the cells durations/sizes.
-Bit endocing is then the art of transforming raw data into a cell 0/1 configuration that respects the two constraints.
+Bit encoding is then the art of transforming raw data into a cell 0/1 configuration that respects the two constraints.
2.3.1.2. FM encoding
````````````````````
@@ -108,9 +108,9 @@ Other encodings exist, like M2FM, but they're very rare and system-specific.
2.3.1.6. Reading back encoded data
``````````````````````````````````
-Writing encoded data is easy, you only need a clock at the appropriate frequency and send or not a pulse on the clock edges. Reading back the data is where the fun is. Cells are a logical construct and not a physical measurable entity. Rotational speeds very around the defined one (+/- 2% is not rare) and local perturbations (air turbulence, surface distance...) make the instant speed very variable in general. So to extract the cell values stream the controller must dynamically synchronize with the pulse train that the floppy head picks up. The principle is simple: a cell-sized duration window is build within which the presence of at least one pulse indicates the cell is a '1', and the absence of any a '0'. After reaching the end of the window the starting time is moved appropriately to try to keep the observed pulse at the exact middle of the window. This allows to correct the phase on every '1' cell, making the synchronization work if the rotational speed is not too off. Subsequent generations of controllers used a Phase-Locked Loop (PLL) which vary both phase and window duration to adapt better to wrong rotational speeds, with usually a tolerance of +/- 15%.
+Writing encoded data is easy: you only need a clock at the appropriate frequency and send or not a pulse on the clock edges. Reading back the data is where the fun is. Cells are a logical construct and not a physical measurable entity. Rotational speeds very around the defined one (±2% is not rare), and local perturbations (air turbulence, surface distance…) make the instantaneous speed very variable in general. So to extract the cell values stream, the controller must dynamically synchronize with the pulse train that the floppy head picks up. The principle is simple: a cell-sized duration window is built within which the presence of at least one pulse indicates the cell is a '1', and the absence of any a '0'. After reaching the end of the window, the starting time is moved appropriately to try to keep the observed pulse at the exact middle of the window. This allows the phase to be corrected on every '1' cell, making the synchronization work if the rotational speed is not too off. Subsequent generations of controllers used Phase-Locked Loops (PLLs) which vary both phase and window duration to adapt better to inaccuarate rotational speeds, usually with a tolerance of ±15%.
-Once the cell data stream is extracted decoding depends on the encoding. In the FM and MFM case the only question is to recognize data bits from clock bits, while in GCR the start position of the first group should be found. That second level of synchronization is handled at a higher level using patterns not found in a normal stream.
+Once the cell data stream is extracted, decoding depends on the encoding. In the FM and MFM case the only question is to recognize data bits from clock bits, while in GCR the start position of the first group should be found. That second level of synchronization is handled at a higher level using patterns not found in a normal stream.
2.3.2. Sector-level organization
diff --git a/docs/source/techspecs/index.rst b/docs/source/techspecs/index.rst
index 40d4048e522..ee41de889d8 100644
--- a/docs/source/techspecs/index.rst
+++ b/docs/source/techspecs/index.rst
@@ -5,19 +5,18 @@ This section covers technical specifications useful to programmers working on
MAME’s source or working on scripts that run within the MAME framework.
.. toctree::
- :titlesonly:
+ :titlesonly:
- naming
- layout_files
- layout_script
- object_finders
- device_memory_interface
- device_rom_interface
- device_disasm_interface
- memory
- floppy
- nscsi
- luaengine
- luareference
- m6502
- poly_manager
+ naming
+ layout_files
+ layout_script
+ object_finders
+ inputsystem
+ device_memory_interface
+ device_rom_interface
+ device_disasm_interface
+ memory
+ floppy
+ nscsi
+ m6502
+ poly_manager
diff --git a/docs/source/techspecs/inputsystem.rst b/docs/source/techspecs/inputsystem.rst
new file mode 100644
index 00000000000..7a027b0ff22
--- /dev/null
+++ b/docs/source/techspecs/inputsystem.rst
@@ -0,0 +1,460 @@
+.. _inputsystem:
+
+Input System
+============
+
+.. contents::
+ :local:
+ :depth: 2
+
+
+.. _inputsystem-intro:
+
+Introduction
+------------
+
+The variety of systems MAME emulates, as well as the variation in host
+systems and peripherals, necessitates a flexible, configurable input
+system.
+
+Note that the input system is concerned with low-level user input.
+High-level user interaction, involving things like text input and
+pointing devices, is handled separately.
+
+
+.. _inputsystem-components:
+
+Components
+----------
+
+From the emulated system’s point of view, the input system has the
+following conceptual components.
+
+Input device
+~~~~~~~~~~~~
+
+Input devices supply input values. An input device typically
+corresponds to a physical device in the host system, for example a
+keyboard, mouse or game controller. However, there isn’t always a
+one-to-one correspondence between input devices and physical devices.
+For example the SDL keyboard provider module aggregates all keyboards
+into a single input device, and the Win32 lightgun provider module can
+present two input devices using input from a single mouse.
+
+Input devices are identified by their device class (keyboard, mouse,
+joystick or lightgun) and device number within the class. Input
+provider modules can also supply an implementation-dependent identifier
+to allow the user to configure stable device numbering.
+
+Note that input devices are unrelated to emulated devices (``device_t``
+implementations) despite the similar name.
+
+Input device item
+~~~~~~~~~~~~~~~~~
+
+Also known as a **control**, and input device item corresponds to a
+input source that produces a single value. This usually corresponds to
+a physical control or sensor, for example a joystick axis, a button or
+an accelerometer.
+
+MAME supports three kinds of controls: **switches**, **absolute axes**
+and **relative axes**:
+
+* Switches produce the value 0 when inactive (released or off) or 1 when
+ active (pressed or on).
+* Absolute axes produce a value normalised to the range -65,536 to
+ 65,536 with zero corresponding to the neutral position.
+* Relative axes produce a value corresponding to the movement since the
+ previous input update. Mouse-like devices scale values to
+ approximately 512 per nominal 100 DPI pixel.
+
+Negative axis values should correspond to directions up, to the left,
+away from the player, or anti-clockwise. For single-ended axes (e.g.
+pedals or displacement-sensitive triggers and buttons), only zero and
+the negative portion of the range should be used.
+
+Switches are used to represent controls that naturally have two distinct
+states, like buttons and toggle switches.
+
+Absolute axes are used to represent controls with a definite range
+and/or neutral position. Examples include steering wheels with limit
+stops, joystick axes, and displacement-sensitive triggers.
+
+Relative axes are used to represent controls with an effectively
+infinite range. Examples include mouse/trackball axes, incremental
+encoder dials, and gyroscopes.
+
+Accelerometers and force sensing joystick axes should be represented as
+absolute axes, even though the range is theoretically open-ended. In
+practice, there is a limit to the range the transducers can report,
+which is usually substantially larger than needed for normal operation.
+
+Input device items are identified by their associated device’s class and
+device number along with an **input item ID**. MAME supplies item IDs
+for common types of controls. Additional controls or controls that do
+not correspond to a common type are dynamically assigned item IDs. MAME
+supports hundreds to items per input device.
+
+I/O port field
+~~~~~~~~~~~~~~
+
+An I/O port field represents an input source in an emulated device or
+system. Most types of I/O port fields can be assigned one or more
+combinations of controls, allowing the user to control the input to
+the emulated system.
+
+Similarly to input device items, there are multiple types of I/O port
+fields:
+
+* **Digital fields** function as switches that produce one of two
+ distinct values. They are used for keyboard keys, eight-way joystick
+ direction switches, toggle switches, photointerruptors and other
+ emulated inputs that function as two-position switches.
+* **Absolute analog fields** have a range with defined minimum, maximum
+ and neutral positions. They are used for analog joystick axes,
+ displacement-sensitive pedals, paddle knobs, and other emulated inputs
+ with a defined range.
+* **Relative analog fields** have a range with defined minimum, maximum
+ and starting positions. On each update, the value accumulates and
+ wraps when it passes either end of the range. Functionally, this is
+ like the output of an up/down counter connected to an incremental
+ encoder. They are used for mouse/trackball axes, steering wheels
+ without limit stops, and other emulated inputs that have no range
+ limits.
+* DIP switch, configuration and adjuster fields allow the user to set
+ the value through MAME’s user interface.
+* Additional special field types are used to produce fixed or
+ programmatically generated values.
+
+A digital field appears to the user as a single assignable input, which
+accepts switch values.
+
+An analog field appears to the user as three assignable inputs: an
+**axis input**, which accepts axis values; and an **increment input**
+and a **decrement input** which accept switch values.
+
+Input manager
+~~~~~~~~~~~~~
+
+The input manager has several responsibilities:
+
+* Tracking the available input devices in the system.
+* Reading input values.
+* Converting between internal identifier values, configuration token
+ strings and display strings.
+
+In practice, emulated devices and systems rarely interact with the input
+manager directly. The most common reason to access the input manager is
+implementing special debug controls, which should be disabled in release
+builds. Plugins that respond to input need to call the input manager to
+read inputs.
+
+I/O port manager
+~~~~~~~~~~~~~~~~
+
+The I/O port manager’s primary responsibilities include:
+
+* Managing assignments of controls to I/O port fields and user interface
+ actions.
+* Reading input values via the input manager and updating I/O port field
+ values.
+
+Like the input manager, the I/O port manager is largely transparent to
+emulated devices and systems. You just need to set up your I/O ports
+and fields, and the I/O port manager handles the rest.
+
+
+.. _inputsystem-structures:
+
+Structures and data types
+-------------------------
+
+The following data types are used for dealing with input.
+
+Input code
+~~~~~~~~~~
+
+An input code specifies an input device item and how it should be
+interpreted. It is a tuple consisting of the following values: **device
+class**, **device number**, **item class**, **item modifier** and **item
+ID**:
+
+* The device class, device number and item ID together identify the
+ input device item to read.
+* The item class specifies the type of output value desired: switch,
+ absolute axis or relative axis. Axis values can be converted to
+ switch values by specifying an appropriate modifier.
+* The modifier specifies how a value should be interpreted. Valid
+ options depend on the type of input device item and the specified
+ item class.
+
+If the specified input item is a switch, it can only be read using the
+switch class, and no modifiers are supported. Attempting to read a
+switch as an absolute or relative axis always returns zero.
+
+If the specified input item is an absolute axis, it can be read as an
+absolute axis or as a switch:
+
+* Reading an absolute axis item as an absolute axis returns the current
+ state of the control, potentially transformed if a modifier is
+ specified. Supported modifiers are **reverse** to reverse the range
+ of the control, **positive** to map the positive range of the control
+ onto the output (zero corresponding to -65,536 and 65,536
+ corresponding to 65,536), and **negative** to map the negative range
+ of the control onto the output (zero corresponding to -65,536 and
+ -65,536 corresponding to 65,536).
+* Reading an absolute axis item as a switch returns zero or 1 depending
+ on whether the control is past a threshold in the direction specified
+ by the modifier. Use the **negative** modifier to return 1 when the
+ control is beyond the threshold in the negative direction (up or
+ left), or the **positive** modifier to return 1 when the control is
+ beyond the threshold in the positive direction (down or right). There
+ are two special pairs of modifiers, **left**/**right** and
+ **up**/**down** that are only applicable to the primary X/Y axes of
+ joystick devices. The user can specify a *joystick map* to control
+ how these modifiers interpret joystick movement.
+* Attempting to read an absolute axis item as a relative axis always
+ returns zero.
+
+If the specified input item is a relative axis, it can be read as a
+relative axis or as a switch:
+
+* Reading a relative axis item as a relative axis returns the change in
+ value since the last input update. The only supported modifier is
+ **reverse**, which negates the value, reversing the direction.
+* Reading a relative axis as a switch returns 1 if the control moved in
+ the direction specified by the modifier since the last input update.
+ Use the **negative**/**left**/**up** modifiers to return 1 when the
+ control has been moved in the negative direction (up or left), or the
+ **positive**/**right**/**down** modifiers to return 1 when the control
+ has moved in the positive direction (down or right).
+* Attempting to read a relative axis item as an absolute axis always
+ returns zero.
+
+There are also special input codes used for specifying how multiple
+controls are to be combined in an input sequence.
+
+The most common place you’ll encounter input codes in device and system
+driver code is when specifying initial assignments for I/O port fields
+that don’t have default assignments supplied by the core. The
+``PORT_CODE`` macro is used for this purpose.
+
+MAME provides macros and helper functions for producing commonly used
+input codes, including standard keyboard keys and
+mouse/joystick/lightgun axes and buttons.
+
+Input sequence
+~~~~~~~~~~~~~~
+
+An input sequence specifies a combination controls that can be assigned
+to an input. The name refers to the fact that it is implemented as a
+sequence container with input codes as elements. It is somewhat
+misleading, as input sequences are interpreted using instantaneous
+control values. Input sequences are interpreted differently for switch
+and axis input.
+
+Input sequences for switch input must only contain input codes with the
+item class set to switch along with the special **or** and **not** input
+codes. The input sequence is interpreted using sum-of-products logic.
+A **not** code causes the value returned by the immediately following
+code to be inverted. The conjunction of values returned by successive
+codes is evaluated until an **or** code is encountered. If the current
+value is 1 when an **or** code is encountered it is returned, otherwise
+evaluation continues.
+
+Input sequences for axis input can contain input codes with the item
+class set to switch, absolute axis or relative axis along with the
+special **or** and **not** codes. It’s helpful to think of the input
+sequence as containing one or more groups of input codes separated by
+**or** codes:
+
+* A **not** code causes the value returned by an immediately following
+ switch code to be inverted. It has no effect on absolute or relative
+ axis codes.
+* Within a group, the conjunction of the values returned by switch codes
+ is evaluated. If it is zero, the group is ignored.
+* Within a group, multiple axis values of the same type are summed.
+ Values returned by absolute axis codes are summed, and values returned
+ by relative axis codes are summed.
+* If any absolute axis code in a group returns a non-zero value, the sum
+ of relative axes in the group is ignored. Any non-zero absolute axis
+ value takes precedence over relative axis values.
+* The same logic is applied when combining group values: group values
+ produced from the same axis type are summed, and values produced from
+ absolute axes take precedence over values produced from relative axes.
+* After the group values are summed, if the value was produced from
+ absolute axes it is clamped to the range -65,536 to 65,536 (values
+ produced from relative axes are not clamped).
+
+Emulation code rarely needs to deal with input sequences directly, as
+they’re handled internally between the I/O port manager and input
+manager. The input manager also converts input sequences to and from
+the token strings stored in configuration files and produces text for
+displaying input sequences to users.
+
+Plugins with controls or hotkeys need to use input sequences to allow
+configuration. Utility classes are provided to allow input sequences to
+be entered by the user in a consistent way, and the input manager can be
+used for conversions to and from configuration and display strings. It
+is very rare to need to directly manipulate input sequences.
+
+
+.. _inputsystem-providermodules:
+
+Input provider modules
+----------------------
+
+Input provider modules are part of the OS-dependent layer (OSD), and are
+not directly exposed to emulation and user interface code. Input
+provider modules are responsible for detecting available host input
+devices, setting up input devices for the input manager, and providing
+callbacks to read the current state of input device items. Input
+provider modules may also provide additional default input assignments
+suitable for host input devices that are present.
+
+The user is given a choice of input modules to use. One input provider
+module is used for each of the four input device classes (keyboard,
+mouse, joystick and lightgun). The available modules depend on the host
+operating system and OSD implementation. Different modules may use
+different APIs, support different kinds of devices, or present devices
+in different ways.
+
+
+.. _inputsystem-playerpositions:
+
+Player positions
+----------------
+
+MAME uses a concept called *player positions* to help manage input
+assignments. The number of player positions supported depends on the
+I/O port field type:
+
+* Ten player positions are supported for common game inputs, including
+ joystick, pedal, paddle, dial, trackball, lightgun and mouse.
+* Four player positions are supported for mahjong and hanafuda inputs.
+* One player position is supported for gambling system inputs.
+* Other inputs do not use player positions. This includes coin slots,
+ arcade start buttons, tilt switches, service switches and
+ keyboard/keypad keys.
+
+The user can configure default input assignments per player position for
+supported I/O port field types which are saved in the file
+**default.cfg**. These assignments are used for all systems unless the
+device/system driver supplies its own default assignments, or the user
+configures system-specific input assignments.
+
+In order to facilitate development of reusable emulated devices with
+inputs, particularly slot devices, the I/O port manager automatically
+renumbers player positions when setting up the emulated system:
+
+* The I/O port manager starts at player position 1 and begins
+ iterating the emulated device tree in depth first order, starting from
+ the root device.
+* If a device has I/O port fields that support player positions, they
+ are renumbered to start from the I/O port manager’s current player
+ position.
+* Before advancing to the next device, the I/O port manager sets its
+ current player position to the last seen player position plus one.
+
+For a simple example, consider what happens when you run a Sega Mega
+Drive console with two game pads connected:
+
+* The I/O port manager starts at player position 1 at the root device.
+* The first device encountered with I/O port fields that support player
+ positions is the first game pad. The inputs are renumbered to start
+ at player position 1. This has no visible effect, as the I/O port
+ fields are initially numbered starting at player position 1.
+* Before moving to the next device, the I/O port manager sets its
+ current player position to 2 (the last player position seen plus one).
+* The next device encountered with I/O port fields that support player
+ positions is the second game pad. The inputs are renumbered to start
+ at player position 2. This avoids I/O port field type conflicts with
+ the first game pad.
+* Before moving to the next device, the I/O port manager sets its
+ current player position to 3 (the last player position seen plus one).
+* No more devices with I/O port fields that support player positions are
+ encountered.
+
+
+.. _inputsystem-updatingfields:
+
+Updating I/O port fields
+------------------------
+
+The I/O port manager updates I/O port fields once for each video frame
+produced by the first emulated screen in the system. How a field is
+updated depends on whether it is a digital or analog field.
+
+Updating digital fields
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Updating digital I/O port fields is simple:
+
+* The I/O port manager reads the current value for the field’s assigned
+ input sequence (via the input manager).
+* If the value is zero, the field’s default value is set.
+* If the value is non-zero, the binary complement of the field’s default
+ value is set.
+
+Updating absolute analog fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Updating absolute analog I/O port fields is more complex due to the need
+to support a variety of control setups:
+
+* The I/O port manager reads the current value for the field’s assigned
+ axis input sequence (via the input manager).
+* If the current value changed since the last update and the input
+ device item that produced the current value was an absolute axis, the
+ field’s value is set to the current value scaled to the correct range,
+ and no further processing is performed.
+* If the current value is non-zero and the input device item that
+ produced the current value was a relative axis, the current value is
+ added to the field’s value, scaled by the field’s sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ increment input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is added
+ to its value, scaled by its sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ decrement input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is
+ subtracted from its value, scaled by its sensitivity setting.
+* If the current axis input, increment input and decrement input values
+ are all zero, but either or both of the increment input and decrement
+ input values were non-zero the last time the field’s value changed in
+ response to user input, the field’s auto-centring speed setting value
+ is added to or subtracted from its value to move it toward its default
+ value.
+
+Note that the sensitivity setting value for absolute analog fields
+affects the response to relative axis input device items and
+increment/decrement inputs, but it does not affect the response to
+absolute axis input device items or the auto-centring speed.
+
+Updating relative analog fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Relative analog I/O port fields also need special handling to cater for
+multiple control setups, but they are a little simpler than absolute
+analog fields:
+
+* The I/O port manager reads the current value for the field’s assigned
+ axis input sequence (via the input manager).
+* If the current value is non-zero and the input device item that
+ produced the current value was an absolute axis, the current value is
+ added to the field’s value, scaled by the field’s sensitivity setting,
+ and no further processing is performed.
+* If the current value is non-zero and the input device item that
+ produced the current value was a relative axis, the current value is
+ added to the field’s value, scaled by the field’s sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ increment input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is added
+ to its value, scaled by its sensitivity setting.
+* The I/O port manager reads the current value for the field’s assigned
+ decrement input sequence (via the input manager); if this value is
+ non-zero, the field’s increment/decrement speed setting value is
+ subtracted from its value, scaled by its sensitivity setting.
+
+Note that the sensitivity setting value for relative analog fields
+affects the response to all user input.
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index c43a7df8e1b..d9976faf00d 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -396,8 +396,8 @@ Elements
~~~~~~~~
Elements are one of the basic visual objects that may be arranged, along with
-screens, to make up a view. Elements may be built up one or more *components*,
-but an element is treated as as single surface when building the scene graph
+screens, to make up a view. Elements may be built up of one or more *components*,
+but an element is treated as a single surface when building the scene graph
and rendering. An element may be used in multiple views, and may be used
multiple times within a view.
@@ -497,15 +497,15 @@ image
human-readable SVG graphics. A ``file`` attribute or ``data`` child element
must be supplied; it is an error if neither or both are supplied.
- If the ``alphafile`` attribute refers refers to a file, it must have the
- same dimensions (in pixels) as the file referred to by the ``file``
- attribute, and must have a bit depth no greater than eight bits per channel
- per pixel. The intensity from this image (brightness) is copied to the
- alpha channel, with full intensity (white in a greyscale image)
- corresponding to fully opaque, and black corresponding to fully transparent.
- The ``alphafile`` attribute will be ignored if the ``file`` attribute refers
- to an SVG image or the ``data`` child element contains SVG data; it is only
- used in conjunction with bitmap images.
+ If the ``alphafile`` attribute refers to a file, it must have the same
+ dimensions (in pixels) as the file referred to by the ``file`` attribute,
+ and must have a bit depth no greater than eight bits per channel per pixel.
+ The intensity from this image (brightness) is copied to the alpha channel,
+ with full intensity (white in a greyscale image) corresponding to fully
+ opaque, and black corresponding to fully transparent. The ``alphafile``
+ attribute will be ignored if the ``file`` attribute refers to an SVG image
+ or the ``data`` child element contains SVG data; it is only used in
+ conjunction with bitmap images.
The image file(s) should be placed in the same directory/archive as the
layout file. Image file formats are detected by examining the content of
@@ -517,21 +517,6 @@ text
be an integer, where 0 (zero) means centred, 1 (one) means left-aligned, and
2 (two) means right-aligned. If the ``align`` attribute is absent, the text
will be centred.
-dotmatrix
- Draws an eight-pixel horizontal segment of a dot matrix display, using
- circular pixels in the specified colour. The bits of the element’s state
- determine which pixels are lit, with the least significant bit corresponding
- to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff).
-dotmatrix5dot
- Draws a five-pixel horizontal segment of a dot matrix display, using
- circular pixels in the specified colour. The bits of the element’s state
- determine which pixels are lit, with the least significant bit corresponding
- to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff).
-dotmatrixdot
- Draws a single element of a dot matrix display as a circular pixels in the
- specified colour. The least significant bit of the element’s state
- determines whether the pixel is lit. An unlit pixel is drawn at low
- intensity (0x20/0xff).
led7seg
Draws a standard seven-segment (plus decimal point) digital LED/fluorescent
display in the specified colour. The low eight bits of the element’s state
@@ -539,14 +524,6 @@ led7seg
the bits correspond to the top segment, the upper right-hand segment,
continuing clockwise to the upper left segment, the middle bar, and the
decimal point. Unlit segments are drawn at low intensity (0x20/0xff).
-led8seg_gts1
- Draws an eight-segment digital fluorescent display of the type used in
- Gottlieb System 1 pinball machines (actually a Futaba part). Compared to
- standard seven-segment displays, these displays have no decimal point, the
- horizontal middle bar is broken in the centre, and there is a broken
- vertical middle bar controlled by the bit that would control the decimal
- point in a standard seven-segment display. Unlit segments are drawn at low
- intensity (0x20/0xff).
led14seg
Draws a standard fourteen-segment alphanumeric LED/fluorescent display in
the specified colour. The low fourteen bits of the element’s state control
@@ -754,7 +731,7 @@ screen
collection
Adds screens and/or items in a collection that can be shown or hidden by the
user (see :ref:`layfile-parts-collections`). The name of the collection is
- specified using the required ``name`` attribute.. There is a limit of 32
+ specified using the required ``name`` attribute. There is a limit of 32
collections per view.
group
Adds the content of the group to the view (see :ref:`layfile-parts-groups`).
@@ -1292,7 +1269,7 @@ View item animation
Items’ colour and position/size within their containing view may be animated.
This is achieved by supplying multiple ``color`` and/or ``bounds`` child
elements with ``state`` attributes. The ``state`` attribute of each ``color``
-or ``bounds`` child element must be a non-negative integer. Withing a view
+or ``bounds`` child element must be a non-negative integer. Within a view
item, no two ``color`` elements may have equal state ``state`` attributes, and
no two ``bounds`` elements may have equal ``state`` attributes.
@@ -1484,33 +1461,36 @@ Example layout files
These layout files demonstrate various artwork system features. They are all
internal layouts included in MAME.
-`sstrangr.lay <https://git.redump.net/mame/tree/src/mame/layout/sstrangr.lay?h=mame0235>`_
+`sstrangr.lay <https://git.redump.net/mame/tree/src/mame/layout/sstrangr.lay?h=mame0261>`_
A simple case of using translucent colour overlays to visually separate and
highlight elements on a black and white screen.
-`seawolf.lay <https://git.redump.net/mame/tree/src/mame/layout/seawolf.lay?h=mame0235>`_
+`seawolf.lay <https://git.redump.net/mame/tree/src/mame/layout/seawolf.lay?h=mame0261>`_
This system uses lamps for key gameplay elements. Blending modes are used
for the translucent colour overlay placed over the monitor, and the lamps
reflected in front of the monitor. Also uses collections to allow parts of
- the layout to be disabled selectively. The shapes on the overlay are drawn
- using embedded SVG images.
-`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0235>`_
+ the layout to be disabled selectively.
+`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0261>`_
This game’s monitor is viewed directly through a translucent colour overlay
rather than being reflected from inside the cabinet. This means the overlay
reflects ambient light as well as affecting the colour of the video image.
-`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0235>`_
+ The shapes on the overlay are drawn using embedded SVG images.
+`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0261>`_
A multi-segment alphanumeric display and keypad. The keys are clickable,
and provide visual feedback when pressed.
-`esq2by16.lay <https://git.redump.net/mame/tree/src/mame/layout/esq2by16.lay?h=mame0235>`_
+`esq2by16.lay <https://git.redump.net/mame/tree/src/mame/layout/esq2by16.lay?h=mame0261>`_
Builds up a multi-line dot matrix character display. Repeats are used to
avoid repetition for the rows in a character, characters in a line, and
lines in a page. Group colors allow a single element to be used for all
four display colours.
-`cgang.lay <https://git.redump.net/mame/tree/src/mame/layout/cgang.lay?h=mame0235>`_
+`cgang.lay <https://git.redump.net/mame/tree/src/mame/layout/cgang.lay?h=mame0261>`_
Animates the position of element items to simulate an electromechanical
shooting gallery game. Also demonstrates effective use of components to
build up complex graphics.
-`unkeinv.lay <https://git.redump.net/mame/tree/src/mame/layout/unkeinv.lay?h=mame0235>`_
+`minspace.lay <https://git.redump.net/mame/tree/src/mame/layout/minspace.lay?h=mame0261>`_
Shows the position of a slider control with LEDs on it.
-`md6802.lay <https://git.redump.net/mame/tree/src/mame/layout/md6802.lay?h=mame0235>`_
+`md6802.lay <https://git.redump.net/mame/tree/src/mame/layout/md6802.lay?h=mame0261>`_
Effectively using groups as a procedural programming language to build up an
image of a trainer board.
+`beena.lay <https://git.redump.net/mame/tree/src/mame/layout/beena.lay?h=mame0261>`_
+ Using event-based scripting to dynamically position elements and draw elemnt
+ content programmatically.
diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst
index f2b8ef1cbc3..be6166a7146 100644
--- a/docs/source/techspecs/layout_script.rst
+++ b/docs/source/techspecs/layout_script.rst
@@ -36,9 +36,8 @@ Practical examples
Before diving into the technical details of how it works, we’ll start with some
example layout files using Lua script for enhancement. It’s assumed that you’re
familiar with MAME’s artwork system and have a basic understanding of Lua
-scripting. For details on MAME’s layout file, see :ref:`layfile`; for an
-introduction to Lua scripting in MAME, see :ref:`luaengine`; for detailed
-descriptions of MAME’s Lua classes, see :ref:`luareference`.
+scripting. For details on MAME’s layout file, see :ref:`layfile`; for detailed
+descriptions of MAME’s Lua interface, see :ref:`luascript`.
.. _layscript-examples-espial:
@@ -188,19 +187,21 @@ as a function by the layout plugin when the layout file is loaded. The layout
views have been built at this point, but the emulated system has not finished
starting. In particular, it’s not safe to access inputs and outputs at this
time. The key variable in the script environment is ``file``, which gives the
-script access to its layout file.
+script access to its :ref:`layout file <luascript-ref-renderlayfile>`.
We supply a function to be called after tags in the layout file have been
resolved. At this point, the emulated system will have completed starting.
This function does the following tasks:
-* Looks up the two I/O ports used for player input. I/O ports can be looked up
- by tag relative to the device that caused the layout file to be loaded.
-* Looks up the two view items used to display joystick state. Views can be
- looked up by name (i.e. value of the ``name`` attribute), and items within a
- view can be looked up by ID (i.e. the value of the ``id`` attribute).
+* Looks up the two :ref:`I/O ports <luascript-ref-ioport>` used for player
+ input. I/O ports can be looked up by tag relative to the device that caused
+ the layout file to be loaded.
+* Looks up the two :ref:`view items <luascript-ref-renderlayitem>` used to
+ display joystick state. Views can be looked up by name (i.e. value of the
+ ``name`` attribute), and items within a view can be looked up by ID (i.e. the
+ value of the ``id`` attribute).
* Supplies a function to be called before view items are added to the render
- target.
+ target when drawing a frame.
* Hides the warning that reminds the user to enable the layout plugin by setting
the element state for the item to 0 (the text component is only drawn when
the element state is 1).
@@ -414,20 +415,20 @@ Here’s our layout file:
The layout has a ``script`` element containing the Lua script, to be called as a
function by the layout plugin when the layout file is loaded. This happens
after the layout views have been build, but before the emulated system has
-finished starting. The layout file object is supplied to the script in the
-``file`` variable.
+finished starting. The :ref:`layout file <luascript-ref-renderlayfile>` object
+is supplied to the script in the ``file`` variable.
We supply a function to be called after tags in the layout file have been
resolved. This function does the following:
-* Looks up the analog axis inputs.
-* Looks up the view item that draws the outline of area where the yoke position
- is displayed.
+* Looks up the analog axis :ref:`inputs <luascript-ref-ioport>`.
+* Looks up the :ref:`view item <luascript-ref-renderlayitem>` that draws the
+ outline of area where the yoke position is displayed.
* Declares some variables to hold calculated values across function calls.
* Supplies a function to be called when the view’s dimensions have been
recomputed.
* Supplies a function to be called before adding view items to the render
- container.
+ container when drawing a frame.
* Supplies functions that will supply the bounds for the animated items.
* Hides the warning that reminds the user to enable the layout plugin by setting
the element state for the item to 0 (the text component is only drawn when
@@ -472,18 +473,31 @@ The layout script environment
The Lua environment is provided by the layout plugin. It’s fairly minimal, only
providing what’s needed:
-* ``file`` giving the script’s layout file object. Has a ``device`` property
- for obtaining the device that caused the layout file to be loaded, and a
- ``views`` property for obtaining the layout’s views (indexed by name).
-* ``machine`` giving MAME’s current running machine.
-* ``emu.render_bounds`` and ``emu.render_color`` functions for creating bounds
- and colour objects.
-* ``emu.print_error``, ``emu.print_info`` and ``emu.print_debug`` functions for
- diagnostic output.
-* Standard Lua ``pairs``, ``ipairs``, ``table.insert`` and ``table.remove``
- functions for manipulating tables and other containers.
+* ``file`` giving the script’s :ref:`layout file <luascript-ref-renderlayfile>`
+ object. Has a ``device`` property for obtaining the :ref:`device
+ <luascript-ref-device>` that caused the layout file to be loaded, and a
+ ``views`` property for obtaining the layout’s :ref:`views
+ <luascript-ref-renderlayview>` (indexed by name).
+* ``machine`` giving MAME’s current :ref:`running machine
+ <luascript-ref-machine>`.
+* ``emu.device_enumerator``, ``emu.palette_enumerator``,
+ ``emu.screen_enumerator``, ``emu.cassette_enumerator``,
+ ``emu.image_enumerator`` and ``emu.slot_enumerator`` functions for obtaining
+ specific device interfaces.
+* ``emu.attotime``, ``emu.render_bounds`` and ``emu.render_color`` functions for
+ creating :ref:`attotime <luascript-ref-attotime>`, :ref:`bounds
+ <luascript-ref-renderbounds>` and :ref:`colour <luascript-ref-rendercolor>`
+ objects.
+* ``emu.bitmap_ind8``, ``emu.bitmap_ind16``, ``emu.bitmap_ind32``,
+ ``emu.bitmap_ind64``, ``emu.bitmap_yuy16``, ``emu.bitmap_rgb32`` and
+ ``emu.bitmap_argb32`` objects for creating
+ :ref:`bitmaps <luascript-ref-bitmap>`.
+* ``emu.print_verbose``, ``emu.print_error``, ``emu.print_warning``,
+ ``emu.print_info`` and ``emu.print_debug`` functions for diagnostic output.
+* Standard Lua ``tonumber``, ``tostring``, ``pairs`` and ``ipairs`` functions,
+ and ``table`` and ``string`` objects for manipulating strings, tables and
+ other containers.
* Standard Lua ``print`` function for text output to the console.
-* Standard Lua ``string.format`` function for string formatting.
.. _layscript-events:
@@ -617,7 +631,7 @@ Get item horizontal scroll window size
horizontal window size as a proportion of the associated element’s width,
and takes no parameters. A value of 1.0 will display the entire width of
the element; smaller values will display proportionally smaller parts of the
- element. Call with ``nil`` as the argument to to restore the default
+ element. Call with ``nil`` as the argument to restore the default
horizontal scroll window size handler (based on the ``xscroll`` child
element).
Get item vertical scroll window size
@@ -632,7 +646,7 @@ Get item vertical scroll window size
vertical window size as a proportion of the associated element’s height, and
takes no parameters. A value of 1.0 will display the entire height of the
element; smaller values will display proportionally smaller parts of the
- element. Call with ``nil`` as the argument to to restore the default
+ element. Call with ``nil`` as the argument to restore the default
vertical scroll window size handler (based on the ``xscroll`` child
element).
Get item horizontal scroll position
@@ -661,3 +675,21 @@ Get item vertical scroll position
item; larger values pan down. Call with ``nil`` as the argument to restore
the default vertical scroll position handler (based on bindings in the
``yscroll`` child element).
+
+.. _layscript-events-element:
+
+Layout element events
+~~~~~~~~~~~~~~~~~~~~~
+
+Layout element events apply to an individual visual element definition.
+
+Draw
+ ``element:set_draw_callback(cb)``
+
+ Set callback for additional drawing after the element’s components have been
+ drawn. This gives the script direct control over the final texture when an
+ element item is drawn.
+
+ The callback is passed two arguments: the element state (an integer) and the
+ 32-bit ARGB bitmap at the required size. The callback must not attempt to
+ resize the bitmap.
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst
deleted file mode 100644
index 5e97d4e3885..00000000000
--- a/docs/source/techspecs/luaengine.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-.. _luaengine:
-
-Scripting MAME via Lua
-======================
-
-.. contents:: :local:
-
-
-.. _luaengine-intro:
-
-Introduction
-------------
-
-It is now possible to externally drive MAME via Lua scripts. This feature
-initially appeared in version 0.148, when a minimal Lua engine was implemented.
-Today, the Lua interface is rich enough to let you inspect and manipulate
-devices’ state, access CPU registers, read and write memory, and draw a custom
-HUD on screen.
-
-Internally, MAME makes extensive use of `Sol3 <https://github.com/ThePhD/sol2>`_
-to implement this feature. The idea is to transparently expose as many of the
-useful internals as possible.
-
-Finally, a warning: the Lua API is not yet declared stable and may suddenly
-change without prior notice. However, we expose methods to let you know at
-runtime which API version you are running against, and most of the objects
-support runtime you can introspection.
-
-
-.. _luaengine-features:
-
-Features
---------
-
-The API is not yet complete, but this is a partial list of capabilities
-currently available to Lua scripts:
-
-- session information (app version, current emulated system, ROM details)
-- session control (starting, pausing, resetting, stopping)
-- event hooks (on frame painting and on user events)
-- device introspection (device tree listing, memory and register enumeration)
-- screen introspection (screens listing, screen details, frame counting)
-- screen overlay drawing (text, lines, boxes on multiple screens)
-- memory read/write (8/16/32/64 bits, signed and unsigned)
-- register and state control (state enumeration, get and set)
-
-Many of the classes are documented on the
-:ref:`Lua class reference <luareference>` page.
-
-
-.. _luaengine-usage:
-
-Usage
------
-
-MAME supports external scripting via Lua (>= 5.3) scripts, either entered at the
-interactive console or loaded as a file. To reach the console, enable the
-console plugin (e.g. run MAME with ``-plugin console``) and you will be greeted
-with a ``[MAME]>`` prompt where you can enter Lua script interactively.
-
-To load a whole script at once, store it in a plain text file and pass it using
-``-autoboot_script``. Please note that script loading may be delayed (a few
-seconds by default), but you can override the default with the
-``-autoboot_delay`` option.
-
-To control the execution of your code, you can use a loop-based or event-based
-approach. The former is not encouraged as it is resource-intensive and makes
-control flow unnecessarily complex. Instead, we suggest to register custom
-hooks to be invoked on specific events (e.g. at each frame rendering).
-
-
-.. _luaengine-walkthrough:
-
-Walkthrough
------------
-
-Let’s first run MAME in a terminal to reach the Lua console:
-
-::
-
- $ mame -console YOUR_ROM
- /| /| /| /| /| _______
- / | / | / | / | / | / /
- / |/ | / | / |/ | / ____/
- / | / | / | / /_
- / |/ | / |/ __/
- / /| /| /| |/ /| /| /____
- / / | / | / | / | / | /
- / _/ |/ / / |___/ |/ /_______/
- / /
- / _/
-
- mame 0.227
- Copyright (C) Nicola Salmoria and the MAME team
-
- Lua 5.3
- Copyright (C) Lua.org, PUC-Rio
-
- [MAME]>
-
-At this point, your game is probably running in demo mode, let’s pause it:
-
-::
-
- [MAME]> emu.pause()
- [MAME]>
-
-Even without textual feedback on the console, you’ll notice the game is now
-paused. In general, commands are quiet and only print back error messages.
-
-You can check at runtime which version of MAME you are running, with:
-
-::
-
- [MAME]> print(emu.app_name() .. " " .. emu.app_version())
- mame 0.227
-
-We now start exploring screen related methods. First, let's enumerate available
-screens:
-
-::
-
- [MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end
- :screen
-
-``manager.machine`` is the :ref:`running machine <luareference-core-machine>`
-object for your current emulation session. We will be using this frequently.
-``screens`` is a :ref:`device enumerator <luareference-dev-enum>` that yields
-all emulated screens in the system; most arcade games only have one main screen.
-In our case, the main and only screen is tagged as ``:screen``, and we can
-further inspect it:
-
-::
-
- [MAME]> -- keep a reference to the main screen in a variable
- [MAME]> s = manager.machine.screens[":screen"]
- [MAME]> print(s.width .. "x" .. s.height)
- 320x224
-
-We have several methods to draw a HUD on the screen composed of lines, boxes and
-text:
-
-::
-
- [MAME]> -- we define a HUD-drawing function, and then call it
- [MAME]> function draw_hud()
- [MAME]>> s:draw_text(40, 40, "foo") -- (x0, y0, msg)
- [MAME]>> s:draw_box(20, 20, 80, 80, 0xff00ffff, 0) -- (x0, y0, x1, y1, line-color, fill-color)
- [MAME]>> s:draw_line(20, 20, 80, 80, 0xff00ffff) -- (x0, y0, x1, y1, line-color)
- [MAME]>> end
- [MAME]> draw_hud()
-
-This will draw some useless art on the screen. However, when resuming the game,
-your HUD needs to be refreshed otherwise it will just disappear. In order to do
-this, you have to register your hook to be called on every frame repaint:
-
-::
-
- [MAME]> emu.register_frame_done(draw_hud, "frame")
-
-All colors are specified in ARGB format (eight bits per channel), while screen
-origin (0,0) normally corresponds to the top-left corner.
-
-Similarly to screens, you can inspect all the devices attached to a machine:
-
-::
-
- [MAME]> for tag, device in pairs(manager.machine.devices) do print(tag) end
- :audiocpu
- :maincpu
- :saveram
- :screen
- :palette
- [...]
-
-On some of them, you can also inspect and manipulate memory and state:
-
-::
-
- [MAME]> cpu = manager.machine.devices[":maincpu"]
- [MAME]> -- enumerate, read and write state registers
- [MAME]> for k, v in pairs(cpu.state) do print(k) end
- D5
- SP
- A4
- A3
- D0
- PC
- [...]
- [MAME]> print(cpu.state["D0"].value)
- 303
- [MAME]> cpu.state["D0"].value = 255
- [MAME]> print(cpu.state["D0"].value)
- 255
-
-::
-
- [MAME]> -- inspect memory
- [MAME]> for name, space in pairs(cpu.spaces) do print(name) end
- program
- [MAME]> mem = cpu.spaces["program"]
- [MAME]> print(mem:read_i8(0xc000))
- 41
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
deleted file mode 100644
index 85c7ea8cb8a..00000000000
--- a/docs/source/techspecs/luareference.rst
+++ /dev/null
@@ -1,3184 +0,0 @@
-.. _luareference:
-
-MAME Lua Class Reference
-========================
-
-.. contents::
- :local:
- :depth: 2
-
-
-.. _luareference-intro:
-
-Introduction
-------------
-
-Various aspects of MAME can be controlled using Lua scripting. Many key classes
-are exposed as Lua objects.
-
-.. _luareference-intro-containers:
-
-Containers
-~~~~~~~~~~
-
-Many properties yield container wrappers. Container wrappers are cheap to
-create, and provide an interface that is similar to a read-only table. The
-complexity of operations may vary. Container wrappers usually provide most of
-these operations:
-
-#c
- Get the number of items in the container.
-c[k]
- Returns the item corresponding to the key ``k``, or ``nil`` if the key is
- not present.
-pairs(c)
- Iterate container by key and value. The key is what you would pass to the
- index operator or the ``get`` method to get the value.
-ipairs(c)
- Iterate container by index and value. The index is what you would pass to
- the ``at`` method to get the value (this may be the same as the key for some
- containers).
-c:empty()
- Returns a Boolean indicating whether there are no items in the container.
-c:get(k)
- Returns the item corresponding to the key ``k``, or ``nil`` if the key is
- not present. Usually equivalent to the index operator.
-c:at(i)
- Returns the value at the 1-based index ``i``, or ``nil`` if it is out of
- range.
-c:find(v)
- Returns the key for item ``v``, or ``nil`` if it is not in the container.
- The key is what you would pass to the index operator to get the value.
-c:index_of(v)
- Returns the 1-based index for item ``v``, or ``nil`` if it is not in the
- container. The index is what you would pass to the ``at`` method to get the
- value.
-
-
-.. _luareference-core:
-
-Core classes
-------------
-
-Many of MAME’s core classes used to implement an emulation session are available
-to Lua scripts.
-
-.. _luareference-core-attotime:
-
-Attotime
-~~~~~~~~
-
-Wraps MAME’s ``attotime`` class, which represents a high-precision time
-interval. Attotime values support addition and subtraction with other attotime
-values, and multiplication and division by integers.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.attotime()
- Creates an attotime value representing zero (i.e. no elapsed time).
-emu.attotime(seconds, attoseconds)
- Creates an attotime with the specified whole and fractional parts.
-emu.attotime(attotime)
- Creates a copy of an existing attotime value.
-emu.attotime.from_double(seconds)
- Creates an attotime value representing the specified number of seconds.
-emu.attotime.from_ticks(periods, frequency)
- Creates an attotime representing the specified number of periods of the
- specified frequency in Hertz.
-emu.attotime.from_seconds(seconds)
- Creates an attotime value representing the specified whole number of
- seconds.
-emu.attotime.from_msec(milliseconds)
- Creates an attotime value representing the specified whole number of
- milliseconds.
-emu.attotime.from_usec(microseconds)
- Creates an attotime value representing the specified whole number of
- microseconds.
-emu.attotime.from_nsec(nanoseconds)
- Creates an attotime value representing the specified whole number of
- nanoseconds.
-
-Methods
-^^^^^^^
-
-t:as_double()
- Returns the time interval in seconds as a floating-point value.
-t:as_hz()
- Interprets the interval as a period and returns the corresponding frequency
- in Hertz as a floating-point value. Returns zero if ``t.is_never`` is true.
- The interval must not be zero.
-t:as_khz()
- Interprets the interval as a period and returns the corresponding frequency
- kilohertz as a floating-point value. Returns zero if ``t.is_never`` is
- true. The interval must not be zero.
-t:as_mhz()
- Interprets the interval as a period and returns the corresponding frequency
- megahertz as a floating-point value. Returns zero if ``t.is_never`` is
- true. The interval must not be zero.
-t:as_ticks(frequency)
- Returns the interval as a whole number of periods at the specified
- frequency. The frequency is specified in Hertz.
-
-Properties
-^^^^^^^^^^
-
-t.is_zero (read-only)
- A Boolean indicating whether the value represents no elapsed time.
-t.is_never (read-only)
- A Boolean indicating whether the value is greater than the maximum number of
- whole seconds that can be represented (treated as an unreachable time in the
- future or overflow).
-t.attoseconds (read-only)
- The fraction seconds portion of the interval in attoseconds.
-t.seconds (read-only)
- The number of whole seconds in the interval.
-t.msec (read-only)
- The number of whole milliseconds in the fractional seconds portion of the
- interval.
-t.usec (read-only)
- The number of whole microseconds in the fractional seconds portion of the
- interval.
-t.nsec (read-only)
- The number of whole nanoseconds in the fractional seconds portion of the
- interval.
-
-.. _luareference-core-mameman:
-
-MAME machine manager
-~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``mame_machine_manager`` class, which holds the running machine, UI
-manager, and other global components.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager
- The MAME machine manager is available as a global variable in the Lua
- environment.
-
-Properties
-^^^^^^^^^^
-
-manager.machine (read-only)
- The :ref:`running machine <luareference-core-machine>` for the current
- emulation session.
-manager.ui (read-only)
- The :ref:`UI manager <luareference-core-uiman>` for the current session.
-manager.options (read-only)
- The :ref:`emulation options <luareference-core-emuopts>` for the current
- session.
-manager.plugins[] (read-only)
- Gets information about the :ref:`Lua plugins <luareference-core-plugin>`
- that are present, indexed by name. The index get, ``at`` and ``index_of``
- methods have O(n) complexity.
-
-.. _luareference-core-machine:
-
-Running machine
-~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``running_machine`` class, which represents an emulation session.
-It provides access to the other core objects that implement an emulation session
-as well as the emulated device tree.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine
- Gets the running machine instance for the current emulation session.
-
-Methods
-^^^^^^^
-
-machine:exit()
- Schedules an exit from the current emulation session. This will either
- return to the system selection menu or exit the application, depending on
- how it was started. This method returns immediately, before the scheduled
- exit takes place.
-machine:hard_reset()
- Schedules a hard reset. This is implemented by tearing down the emulation
- session and starting another emulation session for the same system. This
- method returns immediately, before the scheduled reset takes place.
-machine:soft_reset()
- Schedules a soft reset. This is implemented by calling the reset method of
- the root device, which is propagated down the device tree. This method
- returns immediately, before the scheduled reset takes place.
-machine:save(filename)
- Schedules saving machine state to the specified file. If the file name is a
- relative path, it is considered to be relative to the first configured save
- state directory. This method returns immediately, before the machine state
- is saved. If this method is called when a save or load operation is already
- pending, the previously pending operation will be cancelled.
-machine:load(filename)
- Schedules loading machine state from the specified file. If the file name
- is a relative path, the configured save state directories will be searched.
- This method returns immediately, before the machine state is saved. If this
- method is called when a save or load operation is already pending, the
- previously pending operation will be cancelled.
-machine:popmessage([msg])
- Displays a pop-up message to the user. If the message is not provided, the
- currently displayed pop-up message (if any) will be hidden.
-machine:logerror(msg)
- Writes the message to the machine error log. This may be displayed in a
- debugger window, written to a file, or written to the standard error output.
-
-Properties
-^^^^^^^^^^
-
-machine.time (read-only)
- The elapsed emulated time for the current session as an
- :ref:`attotime <luareference-core-attotime>`.
-machine.system (read-only)
- The :ref:`driver metadata <luareference-core-driver>` for the current
- system.
-machine.parameters (read-only)
- The :ref:`parameters manager <luareference-core-paramman>` for the current
- emulation session.
-machine.video (read-only)
- The :ref:`video manager <luareference-core-videoman>` for the current
- emulation session.
-machine.sound (read-only)
- The :ref:`sound manager <luareference-core-soundman>` for the current
- emulation session.
-machine.output (read-only)
- The :ref:`output manager <luareference-core-outputman>` for the current
- emulation session.
-machine.memory (read-only)
- The :ref:`emulated memory manager <luareference-mem-manager>` for the
- current emulation session.
-machine.ioport (read-only)
- The :ref:`I/O port manager <luareference-input-ioportman>` for the current
- emulation session.
-machine.input (read-only)
- The :ref:`input manager <luareference-input-inputman>` for the current
- emulation session.
-machine.natkeyboard (read-only)
- Gets the :ref:`natural keyboard manager <luareference-input-natkbd>`, used
- for controlling keyboard and keypad input to the emulated system.
-machine.uiinput (read-only)
- The :ref:`UI input manager <luareference-input-uiinput>` for the current
- emulation session.
-machine.render (read-only)
- The :ref:`render manager <luareference-render-manager>` for the current
- emulation session.
-machine.debugger (read-only)
- The :ref:`debugger manager <luareference-debug-manager>` for the current
- emulation session, or ``nil`` if the debugger is not enabled.
-machine.options (read-only)
- The user-specified :ref:`options <luareference-core-emuopts>` for the
- current emulation session.
-machine.samplerate (read-only)
- The output audio sample rate in Hertz.
-machine.paused (read-only)
- A Boolean indicating whether emulation is not currently running, usually
- because the session has been paused or the emulated system has not completed
- starting.
-machine.exit_pending (read-only)
- A Boolean indicating whether the emulation session is scheduled to exit.
-machine.hard_reset_pending (read-only)
- A Boolean indicating whether a hard reset of the emulated system is pending.
-machine.devices (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`devices <luareference-dev-device>` in the emulated system.
-machine.screens (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`screen devices <luareference-dev-screen>` in the emulated system.
-machine.cassettes (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`cassette image devices <luareference-dev-cass>` in the emulated
- system.
-machine.images (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`media image devices <luareference-dev-diimage>` in the emulated system.
-machine.slots (read-only)
- A :ref:`device enumerator <luareference-dev-enum>` that yields all
- :ref:`slot devices <luareference-dev-dislot>` in the emulated system.
-
-.. _luareference-core-videoman:
-
-Video manager
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``video_manager`` class, which is responsible for coordinating
-emulated video drawing, speed throttling, and reading host inputs.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.video
- Gets the video manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-video:frame_update()
- Updates emulated screens, reads host inputs, and updates video output.
-video:snapshot()
- Saves snapshot files according to the current configuration. If MAME is
- configured to take native emulated screen snapshots, one snapshot will be
- saved for each emulated screen that is visible in a host window/screen with
- the current view configuration. If MAME is not configured to use take
- native emulated screen snapshots or if the system has no emulated screens, a
- single snapshot will be saved using the currently selected snapshot view.
-video:begin_recording([filename], [format])
- Stops any video recordings currently in progress and starts recording either
- the visible emulated screens or the current snapshot view, depending on
- whether MAME is configured to take native emulated screen snapshots.
-
- If the file name is not supplied, the configured snapshot file name is used.
- If the file name is a relative path, it is interpreted relative to the first
- configured snapshot directory. If the format is supplied, it must be
- ``"avi"`` or ``"mng"``. If the format is not supplied, it defaults to AVI.
-video:end_recording()
- Stops any video recordings that are in progress.
-video:snapshot_size()
- Returns the width and height in pixels of snapshots created with the current
- snapshot target configuration and emulated screen state. This may be
- configured explicitly by the user, or calculated based on the selected
- snapshot view and the resolution of any visible emulated screens.
-video:snapshot_pixels()
- Returns the pixels of a snapshot created using the current snapshot target
- configuration as 32-bit integers packed into a binary string in host Endian
- order. Pixels are organised in row-major order, from left to right then top
- to bottom. Pixel values are colours in RGB format packed into 32-bit
- integers.
-
-Properties
-^^^^^^^^^^
-
-video.speed_factor (read-only)
- Configured emulation speed adjustment in per mille (i.e. the ratio to normal
- speed multiplied by 1,000).
-video.throttled (read/write)
- A Boolean indicating whether MAME should wait before video updates to avoid
- running faster than the target speed.
-video.throttle_rate (read/write)
- The target emulation speed as a ratio of full speed adjusted by the speed
- factor (i.e. 1 is normal speed adjusted by the speed factor, larger numbers
- are faster, and smaller numbers are slower).
-video.frameskip (read/write)
- The number of emulated video frames to skip drawing out of every twelve, or
- -1 to automatically adjust the number of frames to skip to maintain the
- target emulation speed.
-video.speed_percent (read-only)
- The current emulated speed as a percentage of the full speed adjusted by the
- speed factor.
-video.effective_frameskip (read-only)
- The number of emulated frames that are skipped out of every twelve.
-video.skip_this_frame (read-only)
- A Boolean indicating whether the video manager will skip drawing emulated
- screens for the current frame.
-video.snap_native (read-only)
- A Boolean indicating whether the video manager will take native emulated
- screen snapshots. In addition to the relevant configuration setting, the
- emulated system must have at least one emulated screen.
-video.is_recording (read-only)
- A Boolean indicating whether any video recordings are currently in progress.
-video.snapshot_target (read-only)
- The :ref:`render target <luareference-render-target>` used to produce
- snapshots and video recordings.
-
-.. _luareference-core-soundman:
-
-Sound manager
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``sound_manager`` class, which manages the emulated sound stream
-graph and coordinates sound output.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.sound
- Gets the sound manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-sound:start_recording([filename])
- Starts recording to a WAV file. Has no effect if currently recording. If
- the file name is not supplied, uses the configured WAV file name (from
- command line or INI file), or has no effect if no WAV file name is
- configured. Returns ``true`` if recording started, or ``false`` if
- recording is already in progress, opening the output file failed, or no file
- name was supplied or configured.
-sound:stop_recording()
- Stops recording and closes the file if currently recording to a WAV file.
-sound:get_samples()
- Returns the current contents of the output sample buffer as a binary string.
- Samples are 16-bit integers in host byte order. Samples for left and right
- stereo channels are interleaved.
-
-Properties
-^^^^^^^^^^
-
-sound.muted (read-only)
- A Boolean indicating whether sound output is muted for any reason.
-sound.ui_mute (read/write)
- A Boolean indicating whether sound output is muted at the request of the
- user.
-sound.debugger_mute (read/write)
- A Boolean indicating whether sound output is muted at the request of the
- debugger.
-sound.system_mute (read/write)
- A Boolean indicating whether sound output is muted at the request of the
- emulated system.
-sound.attenuation (read/write)
- The output volume attenuation in decibels. Should generally be a negative
- integer or zero.
-sound.recording (read-only)
- A Boolean indicating whether sound output is currently being recorded to a
- WAV file.
-
-.. _luareference-core-outputman:
-
-Output manager
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``output_manager`` class, providing access to system outputs that
-can be used for interactive artwork or consumed by external programs.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.output
- Gets the output manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-output:set_value(name, val)
- Sets the specified output value. The value must be an integer. The output
- will be created if it does not already exist.
-output:set_indexed_value(prefix, index, val)
- Appends the index (formatted as a decimal integer) to the prefix and sets
- the value of the corresponding output. The value must be an integer. The
- output will be created if it does not already exist.
-output:get_value(name)
- Returns the value of the specified output, or zero if it doesn’t exist.
-output:get_indexed_value(prefix, index)
- Appends the index (formatted as a decimal integer) to the prefix and returns
- the value of the corresponding output, or zero if it doesn’t exist.
-output:name_to_id(name)
- Gets the per-session unique integer ID for the specified output, or zero if
- it doesn’t exist.
-output:id_to_name(id)
- Gets the name for the output with the specified per-session unique ID, or
- ``nil`` if it doesn’t exist. This method has O(n) complexity, so avoid
- calling it when performance is important.
-
-.. _luareference-core-paramman:
-
-Parameters manager
-~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``parameters_manager`` class, which provides a simple key-value
-store for metadata from system ROM definitions.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.parameters
- Gets the parameters manager for the current emulation session.
-
-Methods
-^^^^^^^
-
-parameters:lookup(tag)
- Gets the value for the specified parameter if it is set, or an empty string
- if it is not set.
-parameters:add(tag, value)
- Sets the specified parameter if it is not set. Has no effect if the
- specified parameter is already set.
-
-.. _luareference-core-uiman:
-
-UI manager
-~~~~~~~~~~
-
-Wraps MAME’s ``mame_ui_manager`` class, which handles menus and other user
-interface functionality.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.ui
- Gets the UI manager for the current session.
-
-Methods
-^^^^^^^
-
-ui:get_char_width(ch)
- Gets the width of a Unicode character as a proportion of the width of the UI
- container in the current font at the configured UI line height.
-ui:get_string_width(str)
- Gets the width of a string as a proportion of the width of the UI container
- in the current font at the configured UI line height.
-ui:set_aggressive_input_focus(enable)
- On some platforms, this controls whether MAME should accept input focus in
- more situations than when its windows have UI focus.
-ui:get_general_input_setting(type, [player])
- Gets a description of the configured
- :ref:`input sequence <luareference-input-iptseq>` for the specified input
- type and player suitable for using in prompts. The input type is an
- enumerated value. The player number is a zero-based index. If the player
- number is not supplied, it is assumed to be zero.
-
-Properties
-^^^^^^^^^^
-
-ui.options (read-only)
- The UI :ref:`options <luareference-core-coreopts>` for the current session.
-ui.line_height (read-only)
- The configured UI text line height as a proportion of the height of the UI
- container.
-ui.menu_active (read-only)
- A Boolean indicating whether an interactive UI element is currently active.
- Examples include menus and slider controls.
-ui.single_step (read/write)
- A Boolean controlling whether the emulated system should be automatically
- paused when the next frame is drawn. This property is automatically reset
- when the automatic pause happens.
-ui.show_fps (read/write)
- A Boolean controlling whether the current emulation speed and frame skipping
- settings should be displayed.
-ui.show_profiler (read/write)
- A Boolean controlling whether profiling statistics should be displayed.
-
-.. _luareference-core-driver:
-
-System driver metadata
-~~~~~~~~~~~~~~~~~~~~~~
-
-Provides some metadata for an emulated system.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.driver_find(name)
- Gets the driver metadata for the system with the specified short name, or
- ``nil`` if no such system exists.
-manager.machine.system
- Gets the driver metadata for the current system.
-
-Properties
-^^^^^^^^^^
-
-driver.name (read-only)
- The short name of the system, as used on the command line, in configuration
- files, and when searching for resources.
-driver.description (read-only)
- The full display name for the system.
-driver.year (read-only)
- The release year for the system. May contain question marks if not known
- definitively.
-driver.manufacturer (read-only)
- The manufacturer, developer or distributor of the system.
-driver.parent (read-only)
- The short name of parent system for organisation purposes, or ``"0"`` if the
- system has no parent.
-driver.compatible_with (read-only)
- The short name of a system that this system is compatible with software for,
- or ``nil`` if the system is not listed as compatible with another system.
-driver.source_file (read-only)
- The source file where this system driver is defined. The path format
- depends on the toolchain the emulator was built with.
-driver.rotation (read-only)
- A string indicating the rotation applied to all screens in the system after
- the screen orientation specified in the machine configuration is applied.
- Will be one of ``"rot0"``, ``"rot90"``, ``"rot180"`` or ``"rot270"``.
-driver.type (read-only)
- A string providing a system type. Will be one of ``"arcade"``,
- ``"console"``, ``"computer"`` or ``"other"``. This is for informational
- purposes only, and may not be supported in the future.
-driver.not_working (read-only)
- A Boolean indicating whether the system is marked as not working.
-driver.supports_save (read-only)
- A Boolean indicating whether the system supports save states.
-driver.no_cocktail (read-only)
- A Boolean indicating whether screen flipping in cocktail mode is
- unsupported.
-driver.is_bios_root (read-only)
- A Boolean indicating whether this system represents a system that runs
- software from removable media without media present.
-driver.requires_artwork (read-only)
- A Boolean indicating whether the system requires external artwork to be
- usable.
-driver.clickable_artwork (read-only)
- A Boolean indicating whether the system requires clickable artwork features
- to be usable.
-driver.unofficial (read-only)
- A Boolean indicating whether this is an unofficial but common user
- modification to a system.
-driver.no_sound_hw (read-only)
- A Boolean indicating whether the system has no sound output hardware.
-driver.mechanical (read-only)
- A Boolean indicating whether the system depends on mechanical features that
- cannot be properly simulated.
-driver.is_incomplete (read-only)
- A Boolean indicating whether the system is a prototype with incomplete
- functionality.
-
-.. _luareference-core-plugin:
-
-Lua plugin
-~~~~~~~~~~
-
-Provides a description of an available Lua plugin.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.plugins[name]
- Gets the description of the Lua plugin with the specified name, or ``nil``
- if no such plugin is available
-
-Properties
-^^^^^^^^^^
-
-plugin.name (read-only)
- The short name of the plugin, used in configuration and when accessing the
- plugin programmatically.
-plugin.description (read-only)
- The display name for the plugin.
-plugin.type (read-only)
- The plugin type. May be ``"plugin"`` for user-loadable plugins, or
- ``"library"`` for libraries providing common functionality to multiple
- plugins.
-plugin.directory (read-only)
- The path to the directory containing the plugin’s files.
-plugin.start (read-only)
- A Boolean indicating whether the plugin enabled.
-
-
-.. _luareference-dev:
-
-Devices
--------
-
-Several device classes and device mix-ins classes are exposed to Lua. Devices
-can be looked up by tag or enumerated.
-
-.. _luareference-dev-enum:
-
-Device enumerators
-~~~~~~~~~~~~~~~~~~
-
-Device enumerators are special containers that allow iterating over devices and
-looking up devices by tag. A device enumerator can be created to find any kind
-of device, to find devices of a particular type, or to find devices that
-implement a particular interface. When iterating using ``pairs`` or ``ipairs``,
-devices are returned by walking the device tree depth-first in creation order.
-
-The index get operator looks up a device by tag. It returns ``nil`` if no
-device with the specified tag is found, or if the device with the specified tag
-does not meet the type/interface requirements of the device enumerator. The
-complexity is O(1) if the result is cached, but an uncached device lookup is
-expensive. The ``at`` method has O(n) complexity.
-
-If you create a device enumerator with a starting point other than the root
-machine device, passing an absolute tag or a tag containing parent references to
-the index operator may return a device that would not be discovered by
-iteration. If you create a device enumerator with restricted depth, devices
-that would not be found due to being too deep in the hierarchy can still be
-looked up by tag.
-
-Creating a device enumerator with depth restricted to zero can be used to
-downcast a device or test whether a device implements a certain interface. For
-example this will test whether a device implements the media image interface:
-
-.. code-block:: Lua
-
- image_intf = emu.image_enumerator(device, 0):at(1)
- if image_intf then
- print(string.format("Device %s mounts images", device.tag))
- end
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices
- Returns a device enumerator that will iterate over
- :ref:`devices <luareference-dev-device>` in the system.
-manager.machine.screens
- Returns a device enumerator that will iterate over
- :ref:`screen devices <luareference-dev-screen>` in the system.
-manager.machine.cassettes
- Returns a device enumerator that will iterate over
- :ref:`cassette image devices <luareference-dev-cass>` in the system.
-manager.machine.images
- Returns a device enumerator that will iterate over
- :ref:`media image devices <luareference-dev-diimage>` in the system.
-manager.machine.slots
- Returns a device enumerator that will iterate over
- :ref:`slot devices <luareference-dev-dislot>` in the system.
-emu.device_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`devices <luareference-dev-device>` in the sub-tree starting at the
- specified device. The specified device will be included. If the depth is
- provided, it must be an integer specifying the maximum number of levels to
- iterate below the specified device (i.e. 1 will limit iteration to the
- device and its immediate children).
-emu.screen_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`screen devices <luareference-dev-screen>` in the sub-tree starting at
- the specified device. The specified device will be included if it is a
- screen device. If the depth is provided, it must be an integer specifying
- the maximum number of levels to iterate below the specified device (i.e. 1
- will limit iteration to the device and its immediate children).
-emu.cassette_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`cassette image devices <luareference-dev-cass>` in the sub-tree
- starting at the specified device. The specified device will be included if
- it is a cassette image device. If the depth is provided, it must be an
- integer specifying the maximum number of levels to iterate below the
- specified device (i.e. 1 will limit iteration to the device and its
- immediate children).
-emu.image_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`media image devices <luareference-dev-diimage>` in the sub-tree
- starting at the specified device. The specified device will be included if
- it is a media image device. If the depth is provided, it must be an integer
- specifying the maximum number of levels to iterate below the specified
- device (i.e. 1 will limit iteration to the device and its immediate
- children).
-emu.slot_enumerator(device, [depth])
- Returns a device enumerator that will iterate over
- :ref:`slot devices <luareference-dev-dislot>` in the sub-tree starting at
- the specified device. The specified device will be included if it is a
- slot device. If the depth is provided, it must be an integer specifying the
- maximum number of levels to iterate below the specified device (i.e. 1 will
- limit iteration to the device and its immediate children).
-
-.. _luareference-dev-device:
-
-Device
-~~~~~~
-
-Wraps MAME’s ``device_t`` class, which is a base of all device classes.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]
- Gets a device by tag relative to the root machine device, or ``nil`` if no
- such device exists.
-manager.machine.devices[tag]:subdevice(tag)
- Gets a device by tag relative to another arbitrary device, or ``nil`` if no
- such device exists.
-
-Methods
-^^^^^^^
-
-device:subtag(tag)
- Converts a tag relative to the device to an absolute tag.
-device:siblingtag(tag)
- Converts a tag relative to the device’s parent device to an absolute tag.
-device:memshare(tag)
- Gets a :ref:`memory share <luareference-mem-share>` by tag relative to the
- device, or ``nil`` if no such memory share exists.
-device:membank(tag)
- Gets a :ref:`memory bank <luareference-mem-bank>` by tag relative to the
- device, or ``nil`` if no such memory bank exists.
-device:memregion(tag)
- Gets a :ref:`memory region <luareference-mem-region>` by tag relative to the
- device, or ``nil`` if no such memory region exists.
-device:ioport(tag)
- Gets an :ref:`I/O port <luareference-input-ioport>` by tag relative to the
- device, or ``nil`` if no such I/O port exists.
-device:subdevice(tag)
- Gets a device by tag relative to the device.
-device:siblingdevice(tag)
- Gets a device by tag relative to the device’s parent.
-device:parameter(tag)
- Gets a parameter value by tag relative to the device, or an empty string if
- the parameter is not set.
-
-Properties
-^^^^^^^^^^
-
-device.tag (read-only)
- The device’s absolute tag in canonical form.
-device.basetag (read-only)
- The last component of the device’s tag (i.e. its tag relative to its
- immediate parent), or ``"root"`` for the root machine device.
-device.name (read-only)
- The full display name for the device’s type.
-device.shortname (read-only)
- The short name of the devices type (this is used, e.g. on the command line,
- when looking for resource like ROMs or artwork, and in various data files).
-device.owner (read-only)
- The device’s immediate parent in the device tree, or ``nil`` for the root
- machine device.
-device.configured (read-only)
- A Boolean indicating whether the device has completed configuration.
-device.started (read-only)
- A Boolean indicating whether the device has completed starting.
-device.debug (read-only)
- The :ref:`debugger interface <luareference-debug-devdebug>` to the device if
- it is a CPU device, or ``nil`` if it is not a CPU device or the debugger is
- not enabled.
-device.spaces[] (read-only)
- A table of the device’s :ref:`address spaces <luareference-mem-space>`,
- indexed by name. Only valid for devices that implement the memory
- interface. Note that the names are specific to the device type and have no
- special significance.
-
-.. _luareference-dev-screen:
-
-Screen device
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``screen_device`` class, which represents an emulated video output.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.screens[tag]
- Gets a screen device by tag relative to the root machine device, or ``nil``
- if no such device exists or it is not a screen device.
-
-Base classes
-^^^^^^^^^^^^
-
-* :ref:`luareference-dev-device`
-
-Methods
-^^^^^^^
-
-screen:orientation()
- Returns the rotation angle in degrees (will be one of 0, 90, 180 or 270),
- whether the screen is flipped left-to-right, and whether the screen is
- flipped top-to-bottom. This is the final screen orientation after the
- screen orientation specified in the machine configuration and the rotation
- for the system driver are applied.
-screen:time_until_pos(v, [h])
- Gets the time remaining until the raster reaches the specified position. If
- the horizontal component of the position is not specified, it defaults to
- zero (0, i.e. the beginning of the line). The result is a floating-point
- number in units of seconds.
-screen:time_until_vblank_start()
- Gets the time remaining until the start of the vertical blanking interval.
- The result is a floating-point number in units of seconds.
-screen:time_until_vblank_end()
- Gets the time remaining until the end of the vertical blanking interval.
- The result is a floating-point number in units of seconds.
-screen:snapshot([filename])
- Saves a screen snapshot in PNG format. If no filename is supplied, the
- configured snapshot path and name format will be used. If the supplied
- filename is not an absolute path, it is interpreted relative to the first
- configured snapshot path. The filename may contain conversion specifiers
- that will be replaced by the system name or an incrementing number.
-
- Returns a file error if opening the snapshot file failed, or ``nil``
- otherwise.
-screen:pixel(x, y)
- Gets the pixel at the specified location. Coordinates are in pixels, with
- the origin at the top left corner of the visible area, increasing to the
- right and down. Returns either a palette index or a colour in RGB format
- packed into a 32-bit integer. Returns zero (0) if the specified point is
- outside the visible area.
-screen:pixels()
- Returns all visible pixels as 32-bit integers packed into a binary string in
- host Endian order. Pixels are organised in row-major order, from left to
- right then top to bottom. Pixels values are either palette indices or
- colours in RGB format packed into 32-bit integers.
-screen:draw_box(left, top, right, bottom, [line], [fill])
- Draws an outlined rectangle with edges at the specified positions.
-
- Coordinates are floating-point numbers in units of emulated screen pixels,
- with the origin at (0, 0). Note that emulated screen pixels often aren’t
- square. The coordinate system is rotated if the screen is rotated, which is
- usually the case for vertical-format screens. Before rotation, the origin
- is at the top left, and coordinates increase to the right and downwards.
- Coordinates are limited to the screen area.
-
- The fill and line colours are in alpha/red/green/blue (ARGB) format.
- Channel values are in the range 0 (transparent or off) to 255 (opaque or
- full intensity), inclusive. Colour channel values are not pre-multiplied by
- the alpha value. The channel values must be packed into the bytes of a
- 32-bit unsigned integer, in the order alpha, red, green, blue from
- most-significant to least-significant byte. If the line colour is not
- provided, the UI text colour is used; if the fill colour is not provided,
- the UI background colour is used.
-screen:draw_line(x1, y1, x2, y2, [color])
- Draws a line from (x1, y1) to (x2, y2).
-
- Coordinates are floating-point numbers in units of emulated screen pixels,
- with the origin at (0, 0). Note that emulated screen pixels often aren’t
- square. The coordinate system is rotated if the screen is rotated, which is
- usually the case for vertical-format screens. Before rotation, the origin
- is at the top left, and coordinates increase to the right and downwards.
- Coordinates are limited to the screen area.
-
- The line colour is in alpha/red/green/blue (ARGB) format. Channel values
- are in the range 0 (transparent or off) to 255 (opaque or full intensity),
- inclusive. Colour channel values are not pre-multiplied by the alpha value.
- The channel values must be packed into the bytes of a 32-bit unsigned
- integer, in the order alpha, red, green, blue from most-significant to
- least-significant byte. If the line colour is not provided, the UI text
- colour is used.
-screen:draw_text(x|justify, y, text, [foreground], [background])
- Draws text at the specified position. If the screen is rotated the text
- will be rotated.
-
- If the first argument is a number, the text will be left-aligned at this X
- coordinate. If the first argument is a string, it must be ``"left"``,
- ``"center"`` or ``"right"`` to draw the text left-aligned at the
- left edge of the screen, horizontally centred on the screen, or
- right-aligned at the right edge of the screen, respectively. The second
- argument specifies the Y coordinate of the maximum ascent of the text.
-
- Coordinates are floating-point numbers in units of emulated screen pixels,
- with the origin at (0, 0). Note that emulated screen pixels often aren’t
- square. The coordinate system is rotated if the screen is rotated, which is
- usually the case for vertical-format screens. Before rotation, the origin
- is at the top left, and coordinates increase to the right and downwards.
- Coordinates are limited to the screen area.
-
- The foreground and background colours are in alpha/red/green/blue (ARGB)
- format. Channel values are in the range 0 (transparent or off) to 255
- (opaque or full intensity), inclusive. Colour channel values are not
- pre-multiplied by the alpha value. The channel values must be packed into
- the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
- from most-significant to least-significant byte. If the foreground colour
- is not provided, the UI text colour is used; if the background colour is not
- provided, it is fully transparent.
-
-Properties
-^^^^^^^^^^
-
-screen.width (read-only)
- The width of the bitmap produced by the emulated screen in pixels.
-screen.height (read-only)
- The height of the bitmap produced by the emulated screen in pixels.
-screen.refresh (read-only)
- The screen’s configured refresh rate in Hertz (this may not reflect the
- current value).
-screen.refresh_attoseconds (read-only)
- The screen’s configured refresh interval in attoseconds (this may not
- reflect the current value).
-screen.xoffset (read-only)
- The screen’s default X position offset. This is a floating-point number
- where one (1) corresponds to the X size of the screen’s container. This may
- be useful for restoring the default after adjusting the X offset via the
- screen’s container.
-screen.yoffset (read-only)
- The screen’s default Y position offset. This is a floating-point number
- where one (1) corresponds to the Y size of the screen’s container. This may
- be useful for restoring the default after adjusting the Y offset via the
- screen’s container.
-screen.xscale (read-only)
- The screen’s default X scale factor, as a floating-point number. This may
- be useful for restoring the default after adjusting the X scale via the
- screen’s container.
-screen.yscale (read-only)
- The screen’s default Y scale factor, as a floating-point number. This may
- be useful for restoring the default after adjusting the Y scale via the
- screen’s container.
-screen.pixel_period (read-only)
- The interval taken to draw a horizontal pixel, as a floating-point number in
- units of seconds.
-screen.scan_period (read-only)
- The interval taken to draw a scan line (including the horizontal blanking
- interval), as a floating-point number in units of seconds.
-screen.frame_period (read-only)
- The interval taken to draw a complete frame (including blanking intervals),
- as a floating-point number in units of seconds.
-screen.frame_number (read-only)
- The current frame number for the screen. This increments monotonically each
- frame interval.
-screen.container (read-only)
- The :ref:`render container <luareference-render-container>` used to draw the
- screen.
-
-.. _luareference-dev-cass:
-
-Cassette image device
-~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``cassette_image_device`` class, representing a compact cassette
-mechanism typically used by a home computer for program storage.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.cassettes[tag]
- Gets a cassette image device by tag relative to the root machine device, or
- ``nil`` if no such device exists or it is not a cassette image device.
-
-Base classes
-^^^^^^^^^^^^
-
-* :ref:`luareference-dev-device`
-* :ref:`luareference-dev-diimage`
-
-Methods
-^^^^^^^
-
-cassette:stop()
- Disables playback.
-cassette:play()
- Enables playback. The cassette will play if the motor is enabled.
-cassette:forward()
- Sets forward play direction.
-cassette:reverse()
- Sets reverse play direction.
-cassette:seek(time, whence)
- Jump to the specified position on the tape. The time is a floating-point
- number in units of seconds, relative to the point specified by the whence
- argument. The whence argument must be one of ``"set"``, ``"cur"`` or
- ``"end"`` to seek relative to the start of the tape, the current position,
- or the end of the tape, respectively.
-
-Properties
-^^^^^^^^^^
-
-cassette.is_stopped (read-only)
- A Boolean indicating whether the cassette is stopped (i.e. not recording and
- not playing).
-cassette.is_playing (read-only)
- A Boolean indicating whether playback is enabled (i.e. the cassette will
- play if the motor is enabled).
-cassette.is_recording (read-only)
- A Boolean indicating whether recording is enabled (i.e. the cassette will
- record if the motor is enabled).
-cassette.motor_state (read/write)
- A Boolean indicating whether the cassette motor is enabled.
-cassette.speaker_state (read/write)
- A Boolean indicating whether the cassette speaker is enabled.
-cassette.position (read-only)
- The current position as a floating-point number in units of seconds relative
- to the start of the tape.
-cassette.length (read-only)
- The length of the tape as a floating-point number in units of seconds, or
- zero (0) if no tape image is mounted.
-
-.. _luareference-dev-diimage:
-
-Image device interface
-~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``device_image_interface`` class which is a mix-in implemented by
-devices that can load media image files.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.images[tag]
- Gets an image device by tag relative to the root machine device, or ``nil``
- if no such device exists or it is not a media image device.
-
-Methods
-^^^^^^^
-
-image:load(filename)
- Loads the specified file as a media image. Returns ``"pass"`` or
- ``"fail"``.
-image:load_software(name)
- Loads a media image described in a software list. Returns ``"pass"`` or
- ``"fail"``.
-image:unload()
- Unloads the mounted image.
-image:create(filename)
- Creates and mounts a media image file with the specified name. Returns
- ``"pass"`` or ``"fail"``.
-image:display()
- Returns a “front panel display” string for the device, if supported. This
- can be used to show status information, like the current head position or
- motor state.
-
-Properties
-^^^^^^^^^^
-
-image.is_readable (read-only)
- A Boolean indicating whether the device supports reading.
-image.is_writeable (read-only)
- A Boolean indicating whether the device supports writing.
-image.must_be_loaded (read-only)
- A Boolean indicating whether the device requires a media image to be loaded
- in order to start.
-image.is_reset_on_load (read-only)
- A Boolean indicating whether the device requires a hard reset to change
- media images (usually for cartridge slots that contain hardware in addition
- to memory chips).
-image.image_type_name (read-only)
- A string for categorising the media device.
-image.instance_name (read-only)
- The instance name of the device in the current configuration. This is used
- for setting the media image to load on the command line or in INI files.
- This is not stable, it may have a number appended that may change depending
- on slot configuration.
-image.brief_instance_name (read-only)
- The brief instance name of the device in the current configuration. This is
- used for setting the media image to load on the command line or in INI
- files. This is not stable, it may have a number appended that may change
- depending on slot configuration.
-image.formatlist[] (read-only)
- The :ref:`media image formats <luareference-dev-imagefmt>` supported by the
- device, indexed by name. The index operator and ``index_of`` methods have
- O(n) complexity; all other supported operations have O(1) complexity.
-image.exists (read-only)
- A Boolean indicating whether a media image file is mounted.
-image.readonly (read-only)
- A Boolean indicating whether a media image file is mounted in read-only
- mode.
-image.filename (read-only)
- The full path to the mounted media image file, or ``nil`` if no media image
- is mounted.
-image.crc (read-only)
- The 32-bit cyclic redundancy check of the content of the mounted image file
- if the mounted media image was not loaded from a software list, is mounted
- read-only and is not a CD-ROM, or zero (0) otherwise.
-image.loaded_through_softlist (read-only)
- A Boolean indicating whether the mounted media image was loaded from a
- software list, or ``false`` if no media image is mounted.
-image.software_list_name (read-only)
- The short name of the software list if the mounted media image was loaded
- from a software list.
-image.software_longname (read-only)
- The full name of the software item if the mounted media image was loaded
- from a software list, or ``nil`` otherwise.
-image.software_publisher (read-only)
- The publisher of the software item if the mounted media image was loaded
- from a software list, or ``nil`` otherwise.
-image.software_year (read-only)
- The release year of the software item if the mounted media image was loaded
- from a software list, or ``nil`` otherwise.
-image.software_parent (read-only)
- The short name of the parent software item if the mounted media image was
- loaded from a software list, or ``nil`` otherwise.
-image.device (read-only)
- The underlying :ref:`device <luareference-dev-device>`.
-
-.. _luareference-dev-dislot:
-
-Slot device interface
-~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``device_slot_interface`` class which is a mix-in implemented by
-devices that instantiate a user-specified child device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.slots[tag]
- Gets an slot device by tag relative to the root machine device, or ``nil``
- if no such device exists or it is not a slot device.
-
-Properties
-^^^^^^^^^^
-
-slot.fixed (read-only)
- A Boolean indicating whether this is a slot with a card specified in machine
- configuration that cannot be changed by the user.
-slot.has_selectable_options (read-only)
- A Boolean indicating whether the slot has any user-selectable options (as
- opposed to options that can only be selected programmatically, typically for
- fixed slots or to load media images).
-slot.options[] (read-only)
- The :ref:`slot options <luareference-dev-slotopt>` describing the child
- devices that can be instantiated by the slot, indexed by option value. The
- ``at`` and ``index_of`` methods have O(n) complexity; all other supported
- operations have O(1) complexity.
-slot.device (read-only)
- The underlying :ref:`device <luareference-dev-device>`.
-
-.. _luareference-dev-imagefmt:
-
-Media image format
-~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``image_device_format`` class, which describes a media file format
-supported by a :ref:`media image device <luareference-dev-diimage>`.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.images[tag].formatlist[name]
- Gets a media image format supported by a given device by name.
-
-Properties
-^^^^^^^^^^
-
-format.name (read-only)
- An abbreviated name used to identify the format. This often matches the
- primary filename extension used for the format.
-format.description (read-only)
- The full display name of the format.
-format.extensions[] (read-only)
- Yields a table of filename extensions used for the format.
-format.option_spec (read-only)
- A string describing options available when creating a media image using this
- format. The string is not intended to be human-readable.
-
-.. _luareference-dev-slotopt:
-
-Slot option
-~~~~~~~~~~~
-
-Wraps MAME’s ``device_slot_interface::slot_option`` class, which represents a
-child device that a :ref:`slot device <luareference-dev-dislot>` can be
-configured to instantiate.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.slots[tag].options[name]
- Gets a slot option for a given :ref:`slot device <luareference-dev-dislot>`
- by name (i.e. the value used to select the option).
-
-Properties
-^^^^^^^^^^
-
-option.name (read-only)
- The name of the slot option. This is the value used to select this option
- on the command line or in an INI file.
-option.device_fullname (read-only)
- The full display name of the device type instantiated by this option.
-option.device_shortname (read-only)
- The short name of the device type instantiated by this option.
-option.selectable (read-only)
- A Boolean indicating whether the option may be selected by the user (options
- that are not user-selectable are typically used for fixed slots or to load
- media images).
-option.default_bios (read-only)
- The default BIOS setting for the device instantiated using this option, or
- ``nil`` if the default BIOS specified in the device’s ROM definitions will
- be used.
-option.clock (read-only)
- The configured clock frequency for the device instantiated using this
- option. This is an unsigned 32-bit integer. If the eight most-significant
- bits are all set, it is a ratio of the parent device’s clock frequency, with
- the numerator in bits 12-23 and the denominator in bits 0-11. If the eight
- most-significant bits are not all set, it is a frequency in Hertz.
-
-
-.. _luareference-mem:
-
-Memory system
--------------
-
-MAME’s Lua interface exposes various memory system objects, including address
-spaces, memory shares, memory banks, and memory regions. Scripts can read from
-and write to the emulated memory system.
-
-.. _luareference-mem-manager:
-
-Memory manager
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``memory_manager`` class, which allows the memory shares, banks and
-regions in a system to be enumerated.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory
- Gets the global memory manager instance for the emulated system.
-
-Properties
-^^^^^^^^^^
-
-memory.shares[]
- The :ref:`memory shares <luareference-mem-share>` in the system, indexed by
- absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all
- other supported operations have O(1) complexity.
-memory.banks[]
- The :ref:`memory banks <luareference-mem-bank>` in the system, indexed by
- absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity; all
- other supported operations have O(1) complexity.
-memory.regions[]
- The :ref:`memory regions <luareference-mem-region>` in the system, indexed
- by absolute tag. The ``at`` and ``index_of`` methods have O(n) complexity;
- all other supported operations have O(1) complexity.
-
-.. _luareference-mem-space:
-
-Address space
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``address_space`` class, which represent’s an address space
-belonging to a device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name]
- Gets the address space with the specified name for a given device. Note
- that names are specific to the device type.
-
-Methods
-^^^^^^^
-
-space:read_i{8,16,32,64}(addr)
- Reads a signed integer value of the size in bits from the specified address.
-space:read_u{8,16,32,64}(addr)
- Reads an unsigned integer value of the size in bits from the specified
- address.
-space:write_i{8,16,32,64}(addr, val)
- Writes a signed integer value of the size in bits to the specified address.
-space:write_u{8,16,32,64}(addr, val)
- Writes an unsigned integer value of the size in bits to the specified
- address.
-space:readv_i{8,16,32,64}(addr)
- Reads a signed integer value of the size in bits from the specified virtual
- address. The address is translated with the debug read intent. Returns
- zero if address translation fails.
-space:readv_u{8,16,32,64}(addr)
- Reads an unsigned integer value of the size in bits from the specified
- virtual address. The address is translated with the debug read intent.
- Returns zero if address translation fails.
-space:writev_i{8,16,32,64}(addr, val)
- Writes a signed integer value of the size in bits to the specified virtual
- address. The address is translated with the debug write intent. Does not
- write if address translation fails.
-space:writev_u{8,16,32,64}(addr, val)
- Writes an unsigned integer value of the size in bits to the specified
- virtual address. The address is translated with the debug write intent.
- Does not write if address translation fails.
-space:read_direct_i{8,16,32,64}(addr)
- Reads a signed integer value of the size in bits from the specified address
- one byte at a time by obtaining a read pointer for each byte address. If
- a read pointer cannot be obtained for a byte address, the corresponding
- result byte will be zero.
-space:read_direct_u{8,16,32,64}(addr)
- Reads an unsigned integer value of the size in bits from the specified
- address one byte at a time by obtaining a read pointer for each byte
- address. If a read pointer cannot be obtained for a byte address, the
- corresponding result byte will be zero.
-space:write_direct_i{8,16,32,64}(addr, val)
- Writes a signed integer value of the size in bits to the specified address
- one byte at a time by obtaining a write pointer for each byte address. If
- a write pointer cannot be obtained for a byte address, the corresponding
- byte will not be written.
-space:write_direct_u{8,16,32,64}(addr, val)
- Writes an unsigned integer value of the size in bits to the specified
- address one byte at a time by obtaining a write pointer for each byte
- address. If a write pointer cannot be obtained for a byte address, the
- corresponding byte will not be written.
-space:read_range(start, end, width, [step])
- Reads a range of addresses as a binary string. The end address must be
- greater than or equal to the start address. The width must be 8, 16, 30 or
- 64. If the step is provided, it must be a positive number of elements.
-
-Properties
-^^^^^^^^^^
-
-space.name (read-only)
- The display name for the address space.
-space.shift (read-only)
- The address granularity for the address space specified as the shift
- required to translate a byte address to a native address. Positive values
- shift towards the most significant bit (left) and negative values shift
- towards the least significant bit (right).
-space.index (read-only)
- The zero-based space index. Some space indices have special meanings for
- the debugger.
-space.address_mask (read-only)
- The address mask for the space.
-space.data_width (read-only)
- The data width for the space in bits.
-space.endianness (read-only)
- The Endianness of the space (``"big"`` or ``"little"``).
-space.map (read-only)
- The configured :ref:`address map <luareference-mem-map>` for the space or
- ``nil``.
-
-.. _luareference-mem-map:
-
-Address map
-~~~~~~~~~~~
-
-Wraps MAME’s ``address_map`` class, used to configure handlers for an address
-space.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name].map
- Gets the configured address map for an address space, or ``nil`` if no map
- is configured.
-
-Properties
-^^^^^^^^^^
-
-map.spacenum (read-only)
- The address space number of the address space the map is associated with.
-map.device (read-only)
- The device that owns the address space the map is associated with.
-map.unmap_value (read-only)
- The constant value to return from unmapped reads.
-map.global_mask (read-only)
- Global mask to be applied to all addresses when accessing the space.
-map.entries[] (read-only)
- The configured :ref:`entries <luareference-mem-mapentry>` in the address
- map. Uses 1-based integer indices. The index operator and the ``at``
- method have O(n) complexity.
-
-.. _luareference-mem-mapentry:
-
-Address map entry
-~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``address_map_entry`` class, representing an entry in a configured
-address map.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name].map.entries[index]
- Gets an entry from the configured map for an address space.
-
-Properties
-^^^^^^^^^^
-
-entry.address_start (read-only)
- Start address of the entry’s range.
-entry.address_end (read-only)
- End address of the entry’s range (inclusive).
-entry.address_mirror (read-only)
- Address mirror bits.
-entry.address_mask (read-only)
- Address mask bits. Only valid for handlers.
-entry.mask (read-only)
- Lane mask, indicating which data lines on the bus are connected to the
- handler.
-entry.cswidth (read-only)
- The trigger width for a handler that isn’t connected to all the data lines.
-entry.read (read-only)
- :ref:`Additional data <luareference-memory-handlerdata>` for the read
- handler.
-entry.write (read-only)
- :ref:`Additional data <luareference-memory-handlerdata>` for the write
- handler.
-entry.share (read-only)
- Memory share tag for making RAM entries accessible or ``nil``.
-entry.region (read-only)
- Explicit memory region tag for ROM entries, or ``nil``. For ROM entries,
- ``nil`` infers the region from the device tag.
-entry.region_offset (read-only)
- Starting offset in memory region for ROM entries.
-
-.. _luareference-memory-handlerdata:
-
-Address map handler data
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``map_handler_data`` class, which provides configuration data to
-handlers in address maps.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag].spaces[name].map.entries[index].read
- Gets the read handler data for an address map entry.
-manager.machine.devices[tag].spaces[name].map.entries[index].write
- Gets the write handler data for an address map entry.
-
-Properties
-^^^^^^^^^^
-
-data.handlertype (read-only)
- Handler type. Will be one of ``"none"``, ``"ram"``, ``"rom"``, ``"nop"``,
- ``"unmap"``, ``"delegate"``, ``"port"``, ``"bank"``, ``"submap"``, or
- ``"unknown"``. Note that multiple handler type values can yield
- ``"delegate"`` or ``"unknown"``.
-data.bits (read-only)
- Data width for the handler in bits.
-data.name (read-only)
- Display name for the handler, or ``nil``.
-data.tag (read-only)
- Tag for I/O ports and memory banks, or ``nil``.
-
-.. _luareference-mem-share:
-
-Memory share
-~~~~~~~~~~~~
-
-Wraps MAME’s ``memory_share`` class, representing a named allocated memory zone.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory.shares[tag]
- Gets a memory share by absolute tag, or ``nil`` if no such memory share
- exists.
-manager.machine.devices[tag]:memshare(tag)
- Gets a memory share by tag relative to a device, or ``nil`` if no such
- memory share exists.
-
-Methods
-^^^^^^^
-
-share:read_i{8,16,32,64}(offs)
- Reads a signed integer value of the size in bits from the specified offset
- in the memory share.
-share:read_u{8,16,32,64}(offs)
- Reads an unsigned integer value of the size in bits from the specified
- offset in the memory share.
-share:write_i{8,16,32,64}(offs, val)
- Writes a signed integer value of the size in bits to the specified offset in
- the memory share.
-share:write_u{8,16,32,64}(offs, val)
- Writes an unsigned integer value of the size in bits to the specified offset
- in the memory share.
-
-Properties
-^^^^^^^^^^
-
-share.tag (read-only)
- The absolute tag of the memory share.
-share.size (read-only)
- The size of the memory share in bytes.
-share.length (read-only)
- The length of the memory share in native width elements.
-share.endianness (read-only)
- The Endianness of the memory share (``"big"`` or ``"little"``).
-share.bitwidth (read-only)
- The native element width of the memory share in bits.
-share.bytewidth (read-only)
- The native element width of the memory share in bytes.
-
-.. _luareference-mem-bank:
-
-Memory bank
-~~~~~~~~~~~
-
-Wraps MAME’s ``memory_bank`` class, representing a named memory zone
-indirection.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory.banks[tag]
- Gets a memory region by absolute tag, or ``nil`` if no such memory bank
- exists.
-manager.machine.devices[tag]:membank(tag)
- Gets a memory region by tag relative to a device, or ``nil`` if no such
- memory bank exists.
-
-Properties
-^^^^^^^^^^
-
-bank.tag (read-only)
- The absolute tag of the memory bank.
-bank.entry (read/write)
- The currently selected zero-based entry number.
-
-.. _luareference-mem-region:
-
-Memory region
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``memory_region`` class, representing a memory region used to store
-read-only data like ROMs or the result of fixed decryptions.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.memory.regions[tag]
- Gets a memory region by absolute tag, or ``nil`` if no such memory region
- exists.
-manager.machine.devices[tag]:memregion(tag)
- Gets a memory region by tag relative to a device, or ``nil`` if no such
- memory region exists.
-
-Methods
-^^^^^^^
-
-region:read_i{8,16,32,64}(offs)
- Reads a signed integer value of the size in bits from the specified offset
- in the memory region.
-region:read_u{8,16,32,64}(offs)
- Reads an unsigned integer value of the size in bits from the specified
- offset in the memory region.
-region:write_i{8,16,32,64}(offs, val)
- Writes a signed integer value of the size in bits to the specified offset in
- the memory region.
-region:write_u{8,16,32,64}(offs, val)
- Writes an unsigned integer value of the size in bits to the specified offset
- in the memory region.
-
-Properties
-^^^^^^^^^^
-
-region.tag (read-only)
- The absolute tag of the memory region.
-region.size (read-only)
- The size of the memory region in bytes.
-region.length (read-only)
- The length of the memory region in native width elements.
-region.endianness (read-only)
- The Endianness of the memory region (``"big"`` or ``"little"``).
-region.bitwidth (read-only)
- The native element width of the memory region in bits.
-region.bytewidth (read-only)
- The native element width of the memory region in bytes.
-
-
-.. _luareference-input:
-
-Input system
-------------
-
-Allows scripts to get input from the user, and access I/O ports in the emulated
-system.
-
-.. _luareference-input-ioportman:
-
-I/O port manager
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ioport_manager`` class, which provides access to emulated I/O
-ports and handles input configuration.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport
- Gets the global I/O port manager instance for the emulated machine.
-
-Methods
-^^^^^^^
-
-ioport:count_players()
- Returns the number of player controllers in the system.
-ioport:type_pressed(type, [player])
- Returns a Boolean indicating whether the specified input is currently
- pressed. The input port type is an enumerated value. The player number is
- a zero-based index. If the player number is not supplied, it is assumed to
- be zero.
-ioport:type_name(type, [player])
- Returns the display name for the specified input type and player number.
- The input type is an enumerated value. The player number is a zero-based
- index. If the player number is not supplied, it is assumed to be zero.
-ioport:type_group(type, player)
- Returns the input group for the specified input type and player number. The
- input type is an enumerated value. The player number is a zero-based index.
- Returns an integer giving the grouping for the input. If the player number
- is not supplied, it is assumed to be zero.
-
- This should be called with values obtained from I/O port fields to provide
- canonical grouping in an input configuration UI.
-ioport:type_seq(type, [player], [seqtype])
- Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified input type, player number and sequence type. The input type is an
- enumerated value. The player number is a zero-based index. If the player
- number is not supplied, it is assumed to be zero. If the sequence type is
- supplied, it must be ``"standard"``, ``"increment"`` or ``"decrement"``; if
- it is not supplied, it is assumed to be ``"standard"``.
-
- This provides access to general input configuration.
-ioport:set_type_seq(type, player, seqtype, seq)
- Set the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified input type, player number and sequence type. The input type is an
- enumerated value. The player number is a zero-based index. The sequence
- type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
-
- This allows general input configuration to be set.
-ioport:token_to_input_type(string)
- Returns the input type and player number for the specified input type token.
-ioport:input_type_to_token(type, [player])
- Returns the token string for the specified input type and player number. If
- the player number is not supplied, it assumed to be zero.
-
-Properties
-^^^^^^^^^^
-
-ioport.ports[]
- Gets the emulated :ref:`I/O ports <luareference-input-ioport>` in the
- system. Keys are absolute tags. The ``at`` and ``index_of`` methods have
- O(n) complexity; all other supported operations have O(1) complexity.
-
-.. _luareference-input-natkbd:
-
-Natural keyboard manager
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``natural_keyboard`` class, which manages emulated keyboard and
-keypad inputs.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.natkeyboard
- Gets the global natural keyboard manager instance for the emulated machine.
-
-Methods
-^^^^^^^
-
-natkeyboard:post(text)
- Post literal text to the emulated machine. The machine must have keyboard
- inputs with character bindings, and the correct keyboard input device must
- be enabled.
-natkeyboard:post_coded(text)
- Post text to the emulated machine. Brace-enclosed codes are interpreted in
- the text. The machine must have keyboard inputs with character bindings,
- and the correct keyboard input device must be enabled.
-
- The recognised codes are ``{BACKSPACE}``, ``{BS}``, ``{BKSP}``, ``{DEL}``,
- ``{DELETE}``, ``{END}``, ``{ENTER}``, ``{ESC}``, ``{HOME}``, ``{INS}``,
- ``{INSERT}``, ``{PGDN}``, ``{PGUP}``, ``{SPACE}``, ``{TAB}``, ``{F1}``,
- ``{F2}``, ``{F3}``, ``{F4}``, ``{F5}``, ``{F6}``, ``{F7}``, ``{F8}``,
- ``{F9}``, ``{F10}``, ``{F11}``, ``{F12}``, and ``{QUOTE}``.
-natkeyboard:paste()
- Post the contents of the host clipboard to the emulated machine. The
- machine must have keyboard inputs with character bindings, and the correct
- keyboard input device must be enabled.
-natkeyboard:dump()
- Returns a string with a human-readable description of the keyboard and
- keypad input devices in the system, whether they are enabled, and their
- character bindings.
-
-Properties
-^^^^^^^^^^
-
-natkeyboard.empty (read-only)
- A Boolean indicating whether the natural keyboard manager’s input buffer is
- empty.
-natkeyboard.full (read-only)
- A Boolean indicating whether the natural keyboard manager’s input buffer is
- full.
-natkeyboard.can_post (read-only)
- A Boolean indicating whether the emulated system supports posting character
- data via the natural keyboard manager.
-natkeyboard.is_posting (read-only)
- A Boolean indicating whether posted character data is currently being
- delivered to the emulated system.
-natkeyboard.in_use (read/write)
- A Boolean indicating whether “natural keyboard” mode is enabled. When
- “natural keyboard” mode is enabled, the natural keyboard manager translates
- host character input to emulated system keystrokes.
-natkeyboard.keyboards[]
- Gets the :ref:`keyboard/keypad input devices <luareference-input-kbddev>` in
- the emulated system, indexed by absolute device tag. Index get has O(n)
- complexity; all other supported operations have O(1) complexity.
-
-.. _luareference-input-kbddev:
-
-Keyboard input device
-~~~~~~~~~~~~~~~~~~~~~
-
-Represents a keyboard or keypad input device managed by the
-:ref:`natural keyboard manager <luareference-input-natkbd>`.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.natkeyboard.keyboards[tag]
- Gets the keyboard input device with the specified tag, or ``nil`` if the tag
- does not correspond to a keyboard input device.
-
-Properties
-^^^^^^^^^^
-
-keyboard.device (read-only)
- The underlying device.
-keyboard.tag (read-only)
- The absolute tag of the underlying device.
-keyboard.basetag (read-only)
- The last component of the tag of the underlying device, or ``"root"`` for
- the root machine device.
-keyboard.name (read-only)
- The human-readable description of the underlying device type.
-keyboard.shortname (read-only)
- The identifier for the underlying device type.
-keyboard.is_keypad (read-only)
- A Boolean indicating whether the underlying device has keypad inputs but no
- keyboard inputs. This is used when determining which keyboard input devices
- should be enabled by default.
-keyboard.enabled (read/write)
- A Boolean indicating whether the device’s keyboard and/or keypad inputs are
- enabled.
-
-.. _luareference-input-ioport:
-
-I/O port
-~~~~~~~~
-
-Wraps MAME’s ``ioport_port`` class, representing an emulated I/O port.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport.ports[tag]
- Gets an emulated I/O port by absolute tag, or ``nil`` if the tag does not
- correspond to an I/O port.
-manager.machine.devices[devtag]:ioport(porttag)
- Gets an emulated I/O port by tag relative to a device, or ``nil`` if no such
- I/O port exists.
-
-Methods
-^^^^^^^
-
-port:read()
- Read the current input value. Returns a 32-bit integer.
-port:write(value, mask)
- Write to the I/O port output fields that are set in the specified mask. The
- value and mask must be 32-bit integers. Note that this does not set values
- for input fields.
-port:field(mask)
- Get the first :ref:`I/O port field <luareference-input-field>` corresponding
- to the bits that are set in the specified mask, or ``nil`` if there is no
- corresponding field.
-
-Properties
-^^^^^^^^^^
-
-port.device (read-only)
- The device that owns the I/O port.
-port.tag (read-only)
- The absolute tag of the I/O port
-port.active (read-only)
- A mask indicating which bits of the I/O port correspond to active fields
- (i.e. not unused or unassigned bits).
-port.live (read-only)
- The live state of the I/O port.
-port.fields[] (read-only)
- Gets a table of :ref:`fields <luareference-input-field>` indexed by name.
-
-.. _luareference-input-field:
-
-I/O port field
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport.ports[tag]:field[mask]
- Gets a field for the given port by bit mask.
-manager.machine.ioport.ports[tag].fields[name]
- Gets a field for the given port by display name.
-
-Methods
-^^^^^^^
-
-field:set_value(value)
- Set the value of the I/O port field. For digital fields, the value is
- compared to zero to determine whether the field should be active; for
- analog fields, the value must be right-aligned and in the correct range.
-field:set_input_seq(seqtype, seq)
- Set the :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. This is used to configure per-machine input
- settings. The sequence type must be ``"standard"``, ``"increment"`` or
- ``"decrement"``.
-field:input_seq(seq_type)
- Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. This gets per-machine input assignments. The
- sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
-field:set_default_input_seq(seq_type, seq)
- Set the default :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. This overrides the default input assignment for a
- specific input. The sequence type must be ``"standard"``, ``"increment"``
- or ``"decrement"``.
-field:default_input_seq(seq_type)
- Gets the default :ref:`input sequence <luareference-input-iptseq>` for the
- specified sequence type. If the default assignment is not overridden, this
- gets the general input assignment. The sequence type must be
- ``"standard"``, ``"increment"`` or ``"decrement"``.
-field:keyboard_codes(shift)
- Gets a table of characters corresponding to the field for the specified
- shift state. The shift state is a bit mask of active shift keys.
-
-Properties
-^^^^^^^^^^
-
-field.device (read-only)
- The device that owns the port that the field belongs to.
-field.port (read-only)
- The :ref:`I/O port <luareference-input-ioport>` that the field belongs to.
-field.live (read-only)
- The :ref:`live state <luareference-input-fieldlive>` of the field.
-field.type (read-only)
- The input type of the field. This is an enumerated value.
-field.name (read-only)
- The display name for the field.
-field.default_name (read-only)
- The name for the field from the emulated system’s configuration (cannot be
- overridden by scripts or plugins).
-field.player (read-only)
- Zero-based player number for the field.
-field.mask (read-only)
- Bits in the I/O port corresponding to this field.
-field.defvalue (read-only)
- The field’s default value
-field.sensitivity (read-only)
- The sensitivity or gain for analog fields
-field.way (read-only)
- The number of directions allowed by the restrictor plate/gate for a digital
- joystick, or zero (0) for other inputs.
-field.type_class (read-only)
- The type class for the input field – one of ``"keyboard"``,
- ``"controller"``, ``"config"``, ``"dipswitch"`` or ``"misc"``.
-field.is_analog (read-only)
- A Boolean indicating whether the field is an analog axis or positional
- control.
-field.is_digital_joystick (read-only)
- A Boolean indicating whether the field corresponds to a digital joystick
- switch.
-field.enabled (read-only)
- A Boolean indicating whether the field is enabled.
-field.optional (read-only)
- A Boolean indicating whether the field is optional and not required to use
- the emulated system.
-field.cocktail (read-only)
- A Boolean indicating whether the field is only used when the system is
- configured for a cocktail table cabinet.
-field.toggle (read-only)
- A Boolean indicating whether the field corresponds to a hardware toggle
- switch or push-on, push-off button.
-field.rotated (read-only)
- A Boolean indicating whether the field corresponds to a control that is
- rotated relative its standard orientation.
-field.analog_reverse (read-only)
- A Boolean indicating whether the field corresponds to an analog control that
- increases in the opposite direction to the convention (e.g. larger values
- when a pedal is released or a joystick is moved to the left).
-field.analog_reset (read-only)
- A Boolean indicating whether the field corresponds to an incremental
- position input (e.g. a dial or trackball axis) that should be reset to zero
- for every video frame.
-field.analog_wraps (read-only)
- A Boolean indicating whether the field corresponds to an analog input that
- wraps from one end of its range to the other (e.g. an incremental position
- input like a dial or trackball axis).
-field.analog_invert (read-only)
- A Boolean indicating whether the field corresponds to an analog input that
- has its value ones-complemented.
-field.impulse (read-only)
- A Boolean indicating whether the field corresponds to a digital input that
- activates for a fixed amount of time.
-field.crosshair_scale (read-only)
- The scale factor for translating the field’s range to crosshair position. A
- value of one (1) translates the field’s full range to the full width or
- height the screen.
-field.crosshair_offset (read-only)
- The offset for translating the field’s range to crosshair position.
-field.user_value (read/write)
- The value for DIP switch or configuration settings.
-field.settings[] (read-only)
- Gets a table of the currently enabled settings for a DIP switch or
- configuration field, indexed by value.
-
-.. _luareference-input-fieldlive:
-
-Live I/O port field state
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ioport_field_live`` class, representing the live state of an I/O
-port field.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.ioport.ports[tag]:field(mask).live
- Gets the live state for an I/O port field.
-
-Properties
-^^^^^^^^^^
-
-live.name
- Display name for the field.
-
-.. _luareference-input-inputman:
-
-Input manager
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_manager`` class, which reads host input devices and checks
-whether configured inputs are active.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input
- Gets the global input manager instance for the emulated system.
-
-Methods
-^^^^^^^
-
-input:code_value(code)
- Gets the current value for the host input corresponding to the specified
- code. Returns a signed integer value, where zero is the neutral position.
-input:code_pressed(code)
- Returns a Boolean indicating whether the host input corresponding to the
- specified code has a non-zero value (i.e. it is not in the neutral
- position).
-input:code_pressed_once(code)
- Returns a Boolean indicating whether the host input corresponding to the
- specified code has moved away from the neutral position since the last time
- it was checked using this function. The input manager can track a limited
- number of inputs this way.
-input:code_name(code)
- Get display name for an input code.
-input:code_to_token(code)
- Get token string for an input code. This should be used when saving
- configuration.
-input:code_from_token(token)
- Convert a token string to an input code. Returns the invalid input code if
- the token is not valid or belongs to an input device that is not present.
-input:seq_pressed(seq)
- Returns a Boolean indicating whether the supplied
- :ref:`input sequence <luareference-input-iptseq>` is currently pressed.
-input:seq_clean(seq)
- Remove invalid elements from the supplied
- :ref:`input sequence <luareference-input-iptseq>`. Returns the new, cleaned
- input sequence.
-input:seq_name(seq)
- Get display text for an :ref:`input sequence <luareference-input-iptseq>`.
-input:seq_to_tokens(seq)
- Convert an :ref:`input sequence <luareference-input-iptseq>` to a token
- string. This should be used when saving configuration.
-input:seq_from_tokens(tokens)
- Convert a token string to an
- :ref:`input sequence <luareference-input-iptseq>`. This should be used when
- loading configuration.
-input:axis_code_poller()
- Returns an :ref:`input code poller <luareference-input-codepoll>` for
- obtaining an analog host input code.
-input:switch_code_poller()
- Returns an :ref:`input code poller <luareference-input-codepoll>` for
- obtaining a host switch input code.
-input:keyboard_code_poller()
- Returns an :ref:`input code poller <luareference-input-codepoll>` for
- obtaining a host switch input code that only considers keyboard input
- devices.
-input:axis_sequence_poller()
- Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an :ref:`input sequence <luareference-input-iptseq>` for
- configuring an analog input.
-input:axis_sequence_poller()
- Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an :ref:`input sequence <luareference-input-iptseq>` for
- configuring a digital input.
-
-Properties
-^^^^^^^^^^
-
-input.device_classes[] (read-only)
- Gets a table of host
- :ref:`input device classes <luareference-input-devclass>` indexed by name.
-
-.. _luareference-input-codepoll:
-
-Input code poller
-~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_code_poller`` class, used to poll for host inputs being
-activated.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input:axis_code_poller()
- Returns an input code poller that polls for analog inputs being activated.
-manager.machine.input:switch_code_poller()
- Returns an input code poller that polls for host switch inputs being
- activated.
-manager.machine.input:keyboard_code_poller()
- Returns an input code poller that polls for host switch inputs being
- activated, only considering keyboard input devices.
-
-Methods
-^^^^^^^
-
-poller:reset()
- Resets the polling logic. Active switch inputs are cleared and initial
- analog input positions are set.
-poller:poll()
- Returns an input code corresponding to the first relevant host input that
- has been activated since the last time the method was called. Returns the
- invalid input code if no relevant input has been activated.
-
-.. _luareference-input-seqpoll:
-
-Input sequence poller
-~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_sequence_poller`` poller class, which allows users to
-assign host input combinations to emulated inputs and other actions.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input:axis_sequence_poller()
- Returns an input sequence poller for assigning host inputs to an analog
- input.
-manager.machine.input:switch_sequence_poller()
- Returns an input sequence poller for assigning host inputs to a switch
- input.
-
-Methods
-^^^^^^^
-
-poller:start([seq])
- Start polling. If a sequence is supplied, it is used as a starting
- sequence: for analog inputs, the user can cycle between the full range, and
- the positive and negative portions of an axis; for switch inputs, an “or”
- code is appended and the user can add an alternate host input combination.
-poller:poll()
- Polls for for user input and updates the sequence if appropriate. Returns a
- Boolean indicating whether sequence input is complete. If this method
- returns false, you should continue polling.
-
-Properties
-^^^^^^^^^^
-
-poller.sequence (read-only)
- The current :ref:`input sequence <luareference-input-iptseq>`. This is
- updated while polling. It is possible for the sequence to become invalid.
-poller.valid (read-only)
- A Boolean indicating whether the current input sequence is valid.
-poller.modified (read-only)
- A Boolean indicating whether the sequence was changed by any user input
- since starting polling.
-
-.. _luareference-input-iptseq:
-
-Input sequence
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_seq`` class, representing a combination of host inputs that
-can be read or assigned to an emulated input. Input sequences can be
-manipulated using :ref:`input manager <luareference-input-inputman>` methods.
-Use an :ref:`input sequence poller <luareference-input-seqpoll>` to obtain an
-input sequence from the user.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.input_seq()
- Creates an empty input sequence.
-emu.input_seq(seq)
- Creates a copy of an existing input sequence.
-
-Methods
-^^^^^^^
-
-seq:reset()
- Clears the input sequence, removing all items.
-seq:set_default()
- Sets the input sequence to a single item containing the metavalue specifying
- that the default setting should be used.
-
-Properties
-^^^^^^^^^^
-
-seq.empty (read-only)
- A Boolean indicating whether the input sequence is empty (contains no items,
- indicating an unassigned input).
-seq.length (read-only)
- The number of items in the input sequence.
-seq.is_valid (read-only)
- A Boolean indicating whether the input sequence is a valid. To be valid, it
- must contain at least one item, all items must be valid codes, all product
- groups must contain at least one item that is not negated, and items
- referring to absolute and relative axes must not be mixed within a product
- group.
-seq.is_default (read-only)
- A Boolean indicating whether the input sequence specifies that the default
- setting should be used.
-
-.. _luareference-input-devclass:
-
-Host input device class
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_class`` class, representing a category of host input
-devices (e.g. keyboards or joysticks).
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input.device_classes[name]
- Gets an input device class by name.
-
-Properties
-^^^^^^^^^^
-
-devclass.name (read-only)
- The device class name.
-devclass.enabled (read-only)
- A Boolean indicating whether the device class is enabled.
-devclass.multi (read-only)
- A Boolean indicating whether the device class supports multiple devices, or
- inputs from all devices in the class are combined and treated as a single
- device.
-devclass.devices[] (read-only)
- Gets a table of :ref:`host input devices <luareference-input-inputdev>` in
- the class. Keys are one-based indices.
-
-.. _luareference-input-inputdev:
-
-Host input device
-~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_device`` class, representing a host input device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input.device_classes[name].devices[index]
- Gets a specific host input device.
-
-Properties
-^^^^^^^^^^
-
-inputdev.name (read-only)
- Display name for the device. This is not guaranteed to be unique.
-inputdev.id (read-only)
- Unique identifier string for the device. This may not be human-readable.
-inputdev.devindex (read-only)
- Device index within the device class. This is not necessarily the same as
- the index in the ``devices`` property of the device class – the ``devindex``
- indices may not be contiguous.
-inputdev.items (read-only)
- Gets a table of :ref:`input items <luareference-input-inputitem>`, indexed
- by item ID. The item ID is an enumerated value.
-
-.. _luareference-input-inputitem:
-
-Host input device item
-~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``input_device_item`` class, representing a single host input (e.g.
-a key, button, or axis).
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.input.device_classes[name].devices[index].items[id]
- Gets an individual host input item. The item ID is an enumerated value.
-
-Properties
-^^^^^^^^^^
-
-item.name (read-only)
- The display name of the input item. Note that this is just the name of the
- item itself, and does not include the device name. The full display name
- for the item can be obtained by calling the ``code_name`` method on the
- :ref:`input manager <luareference-input-inputman>` with the item’s code.
-item.code (read-only)
- The input item’s identification code. This is used by several
- :ref:`input manager <luareference-input-inputman>` methods.
-item.token (read-only)
- The input item’s token string. Note that this is a token fragment for the
- item itself, and does not include the device portion. The full token for
- the item can be obtained by calling the ``code_to_token`` method on the
- :ref:`input manager <luareference-input-inputman>` with the item’s code.
-item.current (read-only)
- The item’s current value. This is a signed integer where zero is the
- neutral position.
-
-.. _luareference-input-uiinput:
-
-UI input manager
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``ui_input_manager`` class, which is used for high-level input.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.uiinput
- Gets the global UI input manager instance for the machine.
-
-Methods
-^^^^^^^
-
-uiinput:find_mouse()
- Returns host system mouse pointer X position, Y position, button state, and
- the :ref:`render target <luareference-render-target>` it falls in. The
- position is in host pixels, where zero is at the top/left. The button state
- is a Boolean indicating whether the primary mouse button is pressed.
-
- If the mouse pointer is not over one of MAME’s windows, this may return the
- position and render target from when the mouse pointer was most recently
- over one of MAME’s windows. The render target may be ``nil`` if the mouse
- pointer is not over one of MAME’s windows.
-uiinput:pressed(type)
- Returns a Boolean indicating whether the specified UI input has been
- pressed. The input type is an enumerated value.
-uiinput:pressed_repeat(type, speed)
- Returns a Boolean indicating whether the specified UI input has been
- pressed or auto-repeat has been triggered at the specified speed. The input
- type is an enumerated value; the speed is an interval in sixtieths of a
- second.
-
-Properties
-^^^^^^^^^^
-
-uiinput.presses_enabled (read/write)
- Whether the UI input manager will check for UI inputs frame updates.
-
-
-.. _luareference-render:
-
-Render system
--------------
-
-The render system is responsible for drawing what you see in MAME’s windows,
-including emulated screens, artwork, and UI elements.
-
-.. _luareference-render-bounds:
-
-Render bounds
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_bounds`` class, which represents a rectangle using
-floating-point coordinates.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.render_bounds()
- Creates a render bounds object representing a unit square, with top left
- corner at (0, 0) and bottom right corner at (1, 1). Note that render
- target coordinates don’t necessarily have equal X and Y scales, so this may
- not represent a square in the final output.
-emu.render_bounds(left, top, right, bottom)
- Creates a render bounds object representing a rectangle with top left
- corner at (x0, y0) and bottom right corner at (x1, y1).
-
- The arguments must all be floating-point numbers.
-
-Methods
-^^^^^^^
-
-bounds:includes(x, y)
- Returns a Boolean indicating whether the specified point falls within the
- rectangle. The rectangle must be normalised for this to work (right greater
- than left and bottom greater than top).
-
- The arguments must both be floating-point numbers.
-bounds:set_xy(left, top, right, bottom)
- Set the rectangle’s position and size in terms of the positions of the
- edges.
-
- The arguments must all be floating-point numbers.
-bounds:set_wh(left, top, width, height)
- Set the rectangle’s position and size in terms of the top top left corner
- position, and the width and height.
-
- The arguments must all be floating-point numbers.
-
-Properties
-^^^^^^^^^^
-
-bounds.x0 (read/write)
- The leftmost coordinate in the rectangle (i.e. the X coordinate of the left
- edge or the top left corner).
-bounds.x1 (read/write)
- The rightmost coordinate in the rectangle (i.e. the X coordinate of the
- right edge or the bottom right corner).
-bounds.y0 (read/write)
- The topmost coordinate in the rectangle (i.e. the Y coordinate of the top
- edge or the top left corner).
-bounds.y1 (read/write)
- The bottommost coordinate in the rectangle (i.e. the Y coordinate of the
- bottom edge or the bottom right corner).
-bounds.width (read/write)
- The width of the rectangle. Setting this property changes the position of
- the rightmost edge.
-bounds.height (read/write)
- The height of the rectangle. Setting this property changes the position of
- the bottommost edge.
-bounds.aspect (read-only)
- The width-to-height aspect ratio of the rectangle. Note that this is often
- in render target coordinates which don’t necessarily have equal X and Y
- scales. A rectangle representing a square in the final output doesn’t
- necessarily have an aspect ratio of 1.
-
-.. _luareference-render-color:
-
-Render colour
-~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_color`` class, which represents an ARGB (alpha, red,
-green, blue) format colour. Channels are floating-point values ranging from
-zero (0, transparent alpha or colour off) to one (1, opaque or full colour
-intensity). Colour channel values are not pre-multiplied by the alpha channel
-value.
-
-Instantiation
-^^^^^^^^^^^^^
-
-emu.render_color()
- Creates a render colour object representing opaque white (all channels set
- to 1). This is the identity value – ARGB multiplication by this value will
- not change a colour.
-emu.render_color(a, r, g, b)
- Creates a render colour object with the specified alpha, red, green and
- blue channel values.
-
- The arguments must all be floating-point numbers in the range from zero (0)
- to one (1), inclusive.
-
-Methods
-^^^^^^^
-
-color:set(a, r, g, b)
- Sets the colour object’s alpha, red, green and blue channel values.
-
- The arguments must all be floating-point numbers in the range from zero (0)
- to one (1), inclusive.
-
-Properties
-^^^^^^^^^^
-
-color.a (read/write)
- Alpha value, in the range of zero (0, transparent) to one (1, opaque).
-color.r (read/write)
- Red channel value, in the range of zero (0, off) to one (1, full intensity).
-color.g (read/write)
- Green channel value, in the range of zero (0, off) to one (1, full
- intensity).
-color.b (read/write)
- Blue channel value, in the range of zero (0, off) to one (1, full
- intensity).
-
-.. _luareference-render-manager:
-
-Render manager
-~~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_manager`` class, responsible for managing render targets
-and textures.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.render
- Gets the global render manager instance for the emulation session.
-
-Properties
-^^^^^^^^^^
-
-render.max_update_rate (read-only)
- The maximum update rate in Hertz. This is a floating-point number.
-render.ui_target (read-only)
- The :ref:`render target <luareference-render-target>` used to draw the user
- interface (including menus, sliders and pop-up messages). This is usually
- the first host window or screen.
-render.ui_container (read-only)
- The :ref:`render container <luareference-render-container>` used for drawing
- the user interface.
-render.targets[] (read-only)
- The list of render targets, including output windows and screens, as well as
- hidden render targets used for things like rendering screenshots. Uses
- 1-based integer indices. The index operator and the ``at`` method have O(n)
- complexity.
-
-.. _luareference-render-target:
-
-Render target
-~~~~~~~~~~~~~
-
-Wrap’s MAME’s ``render_target`` class, which represents a video output channel.
-This could be a host window or screen, or a hidden target used for rendering
-screenshots.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.render.targets[index]
- Gets a render target by index.
-manager.machine.render.ui_target
- Gets the render target used to display the user interface (including menus,
- sliders and pop-up messages). This is usually the first host window or
- screen.
-manager.machine.video.snapshot_target
- Gets the render target used to produce snapshots and video recordings.
-
-Properties
-^^^^^^^^^^
-
-target.index (read-only)
- The 1-based index of the render target. This has O(n) complexity.
-target.width (read-only)
- The width of the render target in output pixels. This is an integer.
-target.height (read-only)
- The height of the render target in output pixels. This is an integer.
-target.pixel_aspect (read-only)
- The width-to-height aspect ratio of the render target’s pixels. This is a
- floating-point number.
-target.hidden (read-only)
- A Boolean indicating whether this is an internal render target that is not
- displayed to the user directly (e.g. the render target used to draw
- screenshots).
-target.is_ui_target (read-only)
- A Boolean indicating whether this is the render target used to display the
- user interface.
-target.max_update_rate (read/write)
- The maximum update rate for the render target in Hertz.
-target.orientation (read/write)
- The target orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-target.view_names[]
- The names of the available views for this render target. Uses 1-based
- integer indices. The ``find`` and ``index_of`` methods have O(n)
- complexity; all other supported operations have O(1) complexity.
-target.current_view (read-only)
- The currently selected view for the render target. This is a
- :ref:`layout view <luareference-render-layview>` object.
-target.view_index (read/write)
- The 1-based index of the selected view for this render target.
-target.visibility_mask (read-only)
- An integer bit mask indicating which item collections are currently visible
- for the current view.
-target.screen_overlay (read/write)
- A Boolean indicating whether screen overlays are enabled.
-target.zoom_to_screen (read/write)
- A Boolean indicating whether the render target is configured to scale so
- that the emulated screen(s) fill as much of the output window/screen as
- possible.
-
-.. _luareference-render-container:
-
-Render container
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_container`` class.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.render.ui_container
- Gets the render container used to draw the user interface, including menus,
- sliders and pop-up messages.
-manager.machine.screens[tag].container
- Gets the render container used to draw a given screen.
-
-Methods
-^^^^^^^
-
-container:draw_box(left, top, right, bottom, [line], [fill])
- Draws an outlined rectangle with edges at the specified positions.
-
- Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
- with (0, 0) at the top left and (1, 1) at the bottom right of the window or
- screen that showss the user interface. Note that the aspect ratio is
- usually not square. Coordinates are limited to the window or screen area.
-
- The fill and line colours are in alpha/red/green/blue (ARGB) format.
- Channel values are in the range 0 (transparent or off) to 255 (opaque or
- full intensity), inclusive. Colour channel values are not pre-multiplied by
- the alpha value. The channel values must be packed into the bytes of a
- 32-bit unsigned integer, in the order alpha, red, green, blue from
- most-significant to least-significant byte. If the line colour is not
- provided, the UI text colour is used; if the fill colour is not provided,
- the UI background colour is used.
-container:draw_line(x1, y1, x2, y2, [color])
- Draws a line from (x1, y1) to (x2, y2).
-
- Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
- with (0, 0) at the top left and (1, 1) at the bottom right of the window or
- screen that showss the user interface. Note that the aspect ratio is
- usually not square. Coordinates are limited to the window or screen area.
-
- Coordinates are floating-point numbers in units of screen pixels, with the
- origin at (0, 0). Note that screen pixels often aren’t square. The
- coordinate system is rotated if the screen is rotated, which is usually the
- case for vertical-format screens. Before rotation, the origin is at the top
- left, and coordinates increase to the right and downwards. Coordinates are
- limited to the screen area.
-
- The line colour is in alpha/red/green/blue (ARGB) format. Channel values
- are in the range 0 (transparent or off) to 255 (opaque or full intensity),
- inclusive. Colour channel values are not pre-multiplied by the alpha value.
- The channel values must be packed into the bytes of a 32-bit unsigned
- integer, in the order alpha, red, green, blue from most-significant to
- least-significant byte. If the line colour is not provided, the UI text
- colour is used.
-container:draw_text(x|justify, y, text, [foreground], [background])
- Draws text at the specified position. If the screen is rotated the text
- will be rotated.
-
- If the first argument is a number, the text will be left-aligned at this X
- coordinate. If the first argument is a string, it must be ``"left"``,
- ``"center"`` or ``"right"`` to draw the text left-aligned at the
- left edge of the window or screen, horizontally centred in the window or
- screen, or right-aligned at the right edge of the window or screen,
- respectively. The second argument specifies the Y coordinate of the maximum
- ascent of the text.
-
- Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
- with (0, 0) at the top left and (1, 1) at the bottom right of the window or
- screen that showss the user interface. Note that the aspect ratio is
- usually not square. Coordinates are limited to the window or screen area.
-
- The foreground and background colours are in alpha/red/green/blue (ARGB)
- format. Channel values are in the range 0 (transparent or off) to 255
- (opaque or full intensity), inclusive. Colour channel values are not
- pre-multiplied by the alpha value. The channel values must be packed into
- the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
- from most-significant to least-significant byte. If the foreground colour
- is not provided, the UI text colour is used; if the background colour is not
- provided, it is fully transparent.
-
-Properties
-^^^^^^^^^^
-
-container.user_settings (read/write)
- The container’s :ref:`user settings <luareference-render-contsettings>`.
- This can be used to control a number of image adjustments.
-container.orientation (read/write)
- The container orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-container.xscale (read/write)
- The container’s X scale factor. This is a floating-point number.
-container.yscale (read/write)
- The container’s Y scale factor. This is a floating-point number.
-container.xoffset (read/write)
- The container’s X offset. This is a floating-point number where one (1)
- corresponds to the X size of the container.
-container.yoffset (read/write)
- The container’s Y offset. This is a floating-point number where one (1)
- corresponds to the Y size of the container.
-container.is_empty (read-only)
- A Boolean indicating whether the container has no items.
-
-.. _luareference-render-contsettings:
-
-Container user settings
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``render_container::user_settings`` class, representing image
-adjustments applied to a
-:ref:`render container <luareference-render-container>`.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.screens[tag].container
- Gets the current container user settings for a given screen.
-
-Properties
-^^^^^^^^^^
-
-settings.orientation (read/write)
- The container orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-settings.brightness (read/write)
- The brightness adjustment applied to the container. This is a
- floating-point number.
-settings.contrast (read/write)
- The contrast adjustment applied to the container. This is a floating-point
- number.
-settings.gamma (read/write)
- The gamma adjustment applied to the container. This is a floating-point
- number.
-settings.xscale (read/write)
- The container’s X scale factor. This is a floating-point number.
-settings.yscale (read/write)
- The container’s Y scale factor. This is a floating-point number.
-settings.xoffset (read/write)
- The container’s X offset. This is a floating-point number where one (1)
- represents the X size of the container.
-settings.yoffset (read/write)
- The container’s Y offset. This is a floating-point number where one (1)
- represents the Y size of the container.
-
-.. _luareference-render-layfile:
-
-Layout file
-~~~~~~~~~~~
-
-Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
-file for use by a render target.
-
-Instantiation
-^^^^^^^^^^^^^
-
-A layout file object is supplied to its layout script in the ``file`` variable.
-Layout file objects are not instantiated directly from Lua scripts.
-
-Methods
-^^^^^^^
-
-layout:set_resolve_tags_callback(cb)
- Set a function to perform additional tasks after the emulated machine has
- finished starting, tags in the layout views have been resolved, and the
- default view item handlers have been set up. The function must accept no
- arguments.
-
- Call with ``nil`` to remove the callback.
-
-Properties
-^^^^^^^^^^
-
-layout.device (read-only)
- The device that caused the layout file to be loaded. Usually the root
- machine device for external layouts.
-layout.views[] (read-only)
- The :ref:`views <luareference-render-layview>` created from the layout file.
- Views are indexed by unqualified name (i.e. the value of the ``name``
- attribute). Views are ordered how they appear in the layout file when
- iterating or using the ``at`` method. The index get, ``at`` and
- ``index_of`` methods have O(n) complexity.
-
- Note that not all views in the XML file may be created. For example views
- that reference screens provided by slot card devices will not be created if
- said slot card devices are not present in the system.
-
-.. _luareference-render-layview:
-
-Layout view
-~~~~~~~~~~~
-
-Wraps MAME’s ``layout_view`` class, representing a view that can be displayed in
-a render target. Views are created from XML layout files, which may be loaded
-from external artwork, internal to MAME, or automatically generated based on the
-screens in the emulated system.
-
-Instantiation
-^^^^^^^^^^^^^
-
-Layout scripts generally
-
-manager.machine.render.targets[index].current_view
- Gets the currently selected view for a given render target.
-
-Methods
-^^^^^^^
-
-view:has_screen(screen)
- Returns a Boolean indicating whether the screen is present in the view.
- This is true for screens that are present but not visible because the user
- has hidden the item collection they belong to.
-view:set_prepare_items_callback(cb)
- Set a function to perform additional tasks before the view items are added
- to the render target in preparation for drawing a video frame. The function
- must accept no arguments. Call with ``nil`` to remove the callback.
-view:set_preload_callback(cb)
- Set a function to perform additional tasks after preloading visible view
- items. The function must accept no arguments. Call with ``nil`` to remove
- the callback.
-
- This function may be called when the user selects a view or makes an item
- collection visible. It may be called multiple times for a view, so avoid
- repeating expensive tasks.
-view:set_recomputed_callback(cb)
- Set a function to perform additional tasks after the view’s dimensions are
- recomputed. The function must accept no arguments. Call with ``nil`` to
- remove the callback.
-
- View coordinates are recomputed in various events, including the window
- being resized, entering or leaving full-screen mode, and changing the zoom
- to screen area setting.
-
-Properties
-^^^^^^^^^^
-
-view.items[] (read-only)
- The screen and layout element :ref:`items <luareference-render-layitem>` in
- the view. This container does not support iteration by key using ``pairs``;
- only iteration by index using ``ipairs`` is supported. The key is the value
- of the ``id`` attribute if present. Only items with ``id`` attributes can
- be looked up by key. The index get method has O(1) complexity, and the
- ``at`` and ``index_of`` methods have O(n) complexity.
-view.name (read-only)
- The display name for the view. This may be qualified to indicate the device
- that caused the layout file to be loaded when it isn’t the root machine
- device.
-view.unqualified_name (read-only)
- The unqualified name of the view, exactly as it appears in the ``name``
- attribute in the XML layout file.
-view.visible_screen_count (read-only)
- The number of screens items currently enabled in the view.
-view.effective_aspect (read-only)
- The effective width-to-height aspect ratio of the view in its current
- configuration.
-view.bounds (read-only)
- A :ref:`render bounds <luareference-render-bounds>` object representing the
- effective bounds of the view in its current configuration. The coordinates
- are in view units, which are arbitrary but assumed to have square aspect
- ratio.
-view.has_art
- A Boolean indicating whether the view has any non-screen items, including
- items that are not visible because the user has hidden the item collection
- that they belong to.
-
-.. _luareference-render-layitem:
-
-Layout view item
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``layout_view_item`` class, representing an item in a view. An
-item is drawn as a rectangular textured surface. The texture is supplied by an
-emulated screen or a layout element.
-
-Instantiation
-^^^^^^^^^^^^^
-
-layout.views[name].items[id]
- Get a view item by ID. The item must have an ``id`` attribute in the XML
- layout file to be looked up by ID.
-
-Methods
-^^^^^^^
-
-item:set_state(state)
- Set the value used as the element state and animation state in the absence
- of bindings. The argument must be an integer.
-item:set_element_state_callback(cb)
- Set a function to call to obtain the element state for the item. The
- function must accept no arguments and return an integer. Call with ``nil``
- to restore the default element state callback (based on bindings in the XML
- layout file).
-
- Note that the function must not access the item’s ``element_state``
- property, as this will result in infinite recursion.
-
- This callback will not be used to obtain the animation state for the item,
- even if the item lacks explicit animation state bindings in the XML layout
- file.
-item:set_animation_state_callback(cb)
- Set a function to call to obtain the animation state for the item. The
- function must accept no arguments and return an integer. Call with ``nil``
- to restore the default animation state callback (based on bindings in the
- XML layout file).
-
- Note that the function must not access the item’s ``animation_state``
- property, as this will result in infinite recursion.
-item:set_bounds_callback(cb)
- Set a function to call to obtain the bounds for the item. The function must
- accept no arguments and return a
- :ref:`render bounds <luareference-render-bounds>` object in render target
- coordinates. Call with ``nil`` to restore the default bounds callback
- (based on the item’s animation state and ``bounds`` child elements in the
- XML layout file).
-
- Note that the function must not access the item’s ``bounds`` property, as
- this will result in infinite recursion.
-item:set_color_callback(cb)
- Set a function to call to obtain the multiplier colour for the item. The
- function must accept no arguments and return a
- :ref:`render colour <luareference-render-color>` object. Call with ``nil``
- to restore the default colour callback (based on the item’s animation state
- and ``color`` child elements in the XML layout file).
-
- Note that the function must not access the item’s ``color`` property, as
- this will result in infinite recursion.
-item:set_scroll_size_x_callback(cb)
- Set a function to call to obtain the size of the horizontal scroll window as
- a proportion of the associated element’s width. The function must accept no
- arguments and return a floating-point value. Call with ``nil`` to restore
- the default horizontal scroll window size callback (based on the ``xscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_size_x``
- property, as this will result in infinite recursion.
-item:set_scroll_size_y_callback(cb)
- Set a function to call to obtain the size of the vertical scroll window as a
- proportion of the associated element’s height. The function must accept no
- arguments and return a floating-point value. Call with ``nil`` to restore
- the default vertical scroll window size callback (based on the ``yscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_size_y``
- property, as this will result in infinite recursion.
-item:set_scroll_pos_x_callback(cb)
- Set a function to call to obtain the horizontal scroll position. A value of
- zero places the horizontal scroll window at the left edge of the associated
- element. If the item does not wrap horizontally, a value of 1.0 places the
- horizontal scroll window at the right edge of the associated element; if the
- item wraps horizontally, a value of 1.0 corresponds to wrapping back to the
- left edge of the associated element. The function must accept no arguments
- and return a floating-point value. Call with ``nil`` to restore the default
- horizontal scroll position callback (based on bindings in the ``xscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_pos_x`` property,
- as this will result in infinite recursion.
-item:set_scroll_pos_y_callback(cb)
- Set a function to call to obtain the vertical scroll position. A value of
- zero places the vertical scroll window at the top edge of the associated
- element. If the item does not wrap vertically, a value of 1.0 places the
- vertical scroll window at the bottom edge of the associated element; if the
- item wraps vertically, a value of 1.0 corresponds to wrapping back to the
- left edge of the associated element. The function must accept no arguments
- and return a floating-point value. Call with ``nil`` to restore the default
- vertical scroll position callback (based on bindings in the ``yscroll``
- child element in the XML layout file).
-
- Note that the function must not access the item’s ``scroll_pos_y`` property,
- as this will result in infinite recursion.
-
-Properties
-^^^^^^^^^^
-
-item.id (read-only)
- Get the optional item identifier. This is the value of the ``id`` attribute
- in the XML layout file if present, or ``nil``.
-item.bounds_animated (read-only)
- A Boolean indicating whether the item’s bounds depend on its animation
- state.
-item.color_animated (read-only)
- A Boolean indicating whether the item’s colour depends on its animation
- state.
-item.bounds (read-only)
- The item’s bounds for the current state. This is a
- :ref:`render bounds <luareference-render-bounds>` object in render target
- coordinates.
-item.color (read-only)
- The item’s colour for the current state. The colour of the screen or
- element texture is multiplied by this colour. This is a
- :ref:`render colour <luareference-render-color>` object.
-item.scroll_wrap_x (read-only)
- A Boolean indicating whether the item wraps horizontally.
-item.scroll_wrap_y (read-only)
- A Boolean indicating whether the item wraps vertically.
-item.scroll_size_x (read/write)
- Get the item’s horizontal scroll window size for the current state, or set
- the horizontal scroll window size to use in the absence of bindings. This
- is a floating-point value representing a proportion of the associated
- element’s width.
-item.scroll_size_y (read/write)
- Get the item’s vertical scroll window size for the current state, or set the
- vertical scroll window size to use in the absence of bindings. This is a
- floating-point value representing a proportion of the associated element’s
- height.
-item.scroll_pos_x (read/write)
- Get the item’s horizontal scroll position for the current state, or set the
- horizontal scroll position size to use in the absence of bindings. This is
- a floating-point value.
-item.scroll_pos_y (read/write)
- Get the item’s vertical scroll position for the current state, or set the
- vertical position size to use in the absence of bindings. This is a
- floating-point value.
-item.blend_mode (read-only)
- Get the item’s blend mode. This is an integer value, where 0 means no
- blending, 1 means alpha blending, 2 means RGB multiplication, 3 means
- additive blending, and -1 allows the items within a container to specify
- their own blending modes.
-item.orientation (read-only)
- Get the item orientation flags. This is an integer bit mask, where bit 0
- (0x01) is set to mirror horizontally, bit 1 (0x02) is set to mirror
- vertically, and bit 2 (0x04) is set to mirror along the top left-bottom
- right diagonal.
-item.element_state (read-only)
- Get the current element state. This will call the element state callback
- function to handle bindings.
-item.animation_state (read-only)
- Get the current animation state. This will call the animation state
- callback function to handle bindings.
-
-
-.. _luareference-debug:
-
-Debugger
---------
-
-Some of MAME’s core debugging features can be controlled from Lua script. The
-debugger must be enabled to use the debugging features (usually by passing
-``-debug`` on the command line).
-
-.. _luareference-debug-manager:
-
-Debugger manager
-~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``debugger_manager`` class, providing the main interface to control
-the debugger.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.debugger
- Returns the global debugger manager instance, or ``nil`` if the debugger is
- not enabled.
-
-Methods
-^^^^^^^
-
-debugger:command(str)
- Execute a debugger console command. The argument is the command string.
- The output is sent to both the debugger console and the Lua console.
-
-Properties
-^^^^^^^^^^
-
-debugger.consolelog[] (read-only)
- The lines in the console log (output from debugger commands). This
- container only supports index and length operations.
-debugger.errorlog[] (read-only)
- The lines in the error log (``logerror`` output). This container only
- supports index and length operations.
-debugger.visible_cpu (read/write)
- The CPU device with debugger focus. Changes become visible in the debugger
- console after the next step. Setting to a device that is not a CPU has no
- effect.
-debugger.execution_state (read/write)
- Either ``"run"`` if the emulated system is running, or ``"stop"`` if it is
- stopped in the debugger.
-
-.. _luareference-debug-devdebug:
-
-Device debugger interface
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Wraps MAME’s ``device_debug`` class, providing the debugger interface to an
-emulated CPU device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]:debug()
- Returns the debugger interface for an emulated CPU device, or ``nil`` if the
- device is not a CPU.
-
-Methods
-^^^^^^^
-
-debug:step([cnt])
- Step by the specified number of instructions. If the instruction count is
- not provided, it defaults to a single instruction.
-debug:go()
- Run the emulated CPU.
-debug:bpset(addr, [cond], [act])
- Set a breakpoint at the specified address, with an optional condition and
- action. If the action is not specified, it defaults to just breaking into
- the debugger. Returns the breakpoint number for the new breakpoint.
-
- If specified, the condition must be a debugger expression that will be
- evaluated each time the breakpoint is hit. Execution will only be stopped
- if the expression evaluates to a non-zero value. If the condition is not
- specified, it defaults to always active.
-debug:bpenable([bp])
- Enable the specified breakpoint, or all breakpoints for the device if no
- breakpoint number is specified. Returns whether the specified number
- matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
- breakpoint number is specified.
-debug:bpdisable([bp])
- Disable the specified breakpoint, or all breakpoints for the device if no
- breakpoint number is specified. Returns whether the specified number
- matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
- breakpoint number is specified.
-debug:bpclear([bp])
- Clear the specified breakpoint, or all breakpoints for the device if no
- breakpoint number is specified. Returns whether the specified number
- matched a breakpoint if a breakpoint number is specified, or ``nil`` if no
- breakpoint number is specified.
-debug:bplist()
- Returns a table of breakpoints for the device. The keys are the breakpoint
- numbers, and the values are
- :ref:`breakpoint objects <luareference-debug-breakpoint>`.
-debug:wpset(space, type, addr, len, [cond], [act])
- Set a watchpoint over the specified address range, with an optional
- condition and action. The type must be ``"r"``, ``"w"`` or ``"rw"`` for a
- read, write or read/write breakpoint. If the action is not specified, it
- defaults to just breaking into the debugger. Returns the watchpoint number
- for the new watchpoint.
-
- If specified, the condition must be a debugger expression that will be
- evaluated each time the breakpoint is hit. Execution will only be stopped
- if the expression evaluates to a non-zero value. The variable 'wpaddr' is
- set to the address that actually triggered the watchpoint, the variable
- 'wpdata' is set to the data that is being read or written, and the variable
- 'wpsize' is set to the size of the data in bytes. If the condition is not
- specified, it defaults to always active.
-debug:wpenable([wp])
- Enable the specified watchpoint, or all watchpoints for the device if no
- watchpoint number is specified. Returns whether the specified number
- matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
- watchpoint number is specified.
-debug:wpdisable([wp])
- Disable the specified watchpoint, or all watchpoints for the device if no
- watchpoint number is specified. Returns whether the specified number
- matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
- watchpoint number is specified.
-debug:wpclear([wp])
- Clear the specified watchpoint, or all watchpoints for the device if no
- watchpoint number is specified. Returns whether the specified number
- matched a watchpoint if a watchpoint number is specified, or ``nil`` if no
- watchpoint number is specified.
-debug:wplist(space)
- Returns a table of watchpoints for the specified address space of the
- device. The keys are the watchpoint numbers, and the values are
- :ref:`watchpoint objects <luareference-debug-watchpoint>`.
-
-.. _luareference-debug-breakpoint:
-
-Breakpoint
-~~~~~~~~~~
-
-Wraps MAME’s ``debug_breakpoint`` class, representing a breakpoint for an
-emulated CPU device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]:debug():bplist()[bp]
- Gets the specified breakpoint for an emulated CPU device, or ``nil`` if no
- breakpoint corresponds to the specified index.
-
-Properties
-^^^^^^^^^^
-
-breakpoint.index (read-only)
- The breakpoint’s index. The can be used to enable, disable or clear the
- breakpoint via the
- :ref:`CPU debugger interface <luareference-debug-devdebug>`.
-breakpoint.enabled (read-only)
- A Boolean indicating whether the breakpoint is currently enabled.
-breakpoint.address (read-only)
- The breakpoint’s address.
-breakpoint.condition (read-only)
- A debugger expression evaluated each time the breakpoint is hit. The action
- will only be triggered if this expression evaluates to a non-zero value. An
- empty string if no condition was specified.
-breakpoint.action (read-only)
- An action the debugger will run when the breakpoint is hit and the condition
- evaluates to a non-zero value. An empty string if no action was specified.
-
-.. _luareference-debug-watchpoint:
-
-Watchpoint
-~~~~~~~~~~
-
-Wraps MAME’s ``debug_watchpoint`` class, representing a watchpoint for an
-emulated CPU device.
-
-Instantiation
-^^^^^^^^^^^^^
-
-manager.machine.devices[tag]:debug():wplist(space)[wp]
- Gets the specified watchpoint for an address space of an emulated CPU
- device, or ``nil`` if no watchpoint in the address space corresponds to the
- specified index.
-
-Properties
-^^^^^^^^^^
-
-watchpoint.index (read-only)
- The watchpoint’s index. The can be used to enable, disable or clear the
- watchpoint via the
- :ref:`CPU debugger interface <luareference-debug-devdebug>`.
-watchpoint.enabled (read-only)
- A Boolean indicating whether the watchpoint is currently enabled.
-watchpoint.type (read-only)
- Either ``"r"``, ``"w"`` or ``"rw"`` for a read, write or read/write
- watchpoint.
-watchpoint.address (read-only)
- The starting address of the watchpoint’s address range.
-watchpoint.length (read-only)
- The length of the watchpoint’s address range.
-watchpoint.condition (read-only)
- A debugger expression evaluated each time the watchpoint is hit. The action
- will only be triggered if this expression evaluates to a non-zero value. An
- empty string if no condition was specified.
-watchpoint.action (read-only)
- An action the debugger will run when the watchpoint is hit and the condition
- evaluates to a non-zero value. An empty string if no action was specified.
diff --git a/docs/source/techspecs/m6502.rst b/docs/source/techspecs/m6502.rst
index c4cb45f5cea..7d67423abb8 100644
--- a/docs/source/techspecs/m6502.rst
+++ b/docs/source/techspecs/m6502.rst
@@ -18,7 +18,7 @@ Point 1 has been ensured through bisimulation with the gate-level simulation per
The 6502 family
---------------
-The MOS 6502 family has been large and productive. A large number of variants exist, varying on bus sizes, I/O, and even opcodes. Some offshots (g65c816, hu6280) even exist that live elsewhere in the mame tree. The final class hierarchy is this:
+The MOS 6502 family has been large and productive. A large number of variants exist, varying on bus sizes, I/O, and even opcodes. Some offshoots (g65c816, hu6280) even exist that live elsewhere in the mame tree. The final class hierarchy is this:
::
@@ -26,7 +26,7 @@ The MOS 6502 family has been large and productive. A large number of variants ex
|
+------+--------+--+--+-------+-------+
| | | | | |
- 6510 deco16 6504 6509 n2a03 65c02
+ 6510 deco16 6504 6509 rp2a03 65c02
| |
+-----+-----+ r65c02
| | | |
@@ -38,7 +38,7 @@ The MOS 6502 family has been large and productive. A large number of variants ex
-The 6510 adds an up to 8 bits I/O port, with the 6510t, 7501 and 8502 being software-identical variants with different pin count (hence I/O count), die process (NMOS, HNMOS, etc) and clock support.
+The 6510 adds an up to 8 bits I/O port, with the 6510t, 7501 and 8502 being software-identical variants with different pin count (hence I/O count), die process (NMOS, HNMOS, etc.) and clock support.
The deco16 is a Deco variant with a small number of not really understood additional instructions and some I/O.
@@ -46,7 +46,7 @@ The 6504 is a pin and address-bus reduced version.
The 6509 adds internal support for paging.
-The n2a03 is the NES variant with the D flag disabled and sound functionality integrated.
+The rp2a03 is the NES variant with the D flag disabled and sound functionality integrated.
The 65c02 is the very first cmos variant with some additional instructions, some fixes, and most of the undocumented instructions turned into nops. The R (Rockwell, but eventually produced by WDC too among others) variant adds a number of bitwise instructions and also stp and wai. The SC variant, used by the Lynx portable console, looks identical to the R variant. The 'S' probably indicates a static-ram-cell process allowing full DC-to-max clock control.
@@ -374,6 +374,6 @@ Current TO-DO:
- Integrate the I/O subsystems in the 4510
-- Possibly integrate the sound subsytem in the n2a03
+- Possibly integrate the sound subsytem in the rp2a03
- Add decent hookups for the Apple 3 madness
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index 5d18c4e1202..ebdca9646d1 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -126,7 +126,8 @@ A memory share can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved. That class behaves like a pointer but also has the
``target()``, ``length()``, ``bytes()``, ``endianness()``,
-``bitwidth()`` and ``bytewidth()`` methods for share information.
+``bitwidth()`` and ``bytewidth()`` methods for share information. The
+desired size is specified in bytes.
.. code-block:: C++
@@ -154,12 +155,17 @@ A memory bank is a named memory zone indirection that can be mapped in
address spaces. It points to ``nullptr`` when created.
``configure_entry`` associates an entry number and a base pointer.
``configure_entries`` does the same for multiple consecutive entries
-spanning a memory zone. Alternatively ``set_base`` sets the base for
-entry 0 and selects it.
+spanning a memory zone.
-``set_entry`` allows to dynamically and efficiently select the current
-active entry, ``entry()`` gets that selection back, and ``base()`` gets
-the associated base pointer.
+``set_base`` sets the base address for the active entry. If there are
+no entries, entry 0 (zero) is automatically created and selected. Use
+of ``set_base`` should be avoided in favour of pre-configured entries
+unless there are an impractically large number of possible base
+addresses.
+
+``set_entry`` dynamically and efficiently selects the active entry,
+``entry()`` returns the active entry number, and ``base()`` gets the
+associated base pointer.
.. code-block:: C++
@@ -180,7 +186,7 @@ retrieved by building one of these four finders.
[device constructor] m_bank(*this, "name"),
-A memory share can be created if it doesn’t exist in a memory map
+A memory bank can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved.
@@ -197,7 +203,7 @@ that the lookup can be expensive, prefer finders instead.
.. code-block:: C++
- class memory_bank {
+ class memory_region {
u8 *base();
u8 *end();
u32 bytes() const;
@@ -355,7 +361,7 @@ Sets a method of the current device or driver to read, write or both
for the current entry. The prototype of the method can take multiple
forms making some elements optional. ``uNN`` represents ``u8``,
``u16``, ``u32`` or ``u64`` depending on the data width of the handler.
-The handler can be narrower than the bus itself (for instance a 8-bit
+The handler can be narrower than the bus itself (for instance an 8-bit
device on a 32-bit bus).
The offset passed in is built from the access address. It starts at
@@ -597,7 +603,7 @@ parameter is that trigger width (would be 16 in the 68000 case).
This parameter allows to set user-defined flags on the handler which
can then be retrieved by an accessing device to change their
-behaviour. An example of use the the i960 which marks burstable zones
+behaviour. An example of use the i960 which marks burstable zones
that way (they have a specific hardware-level support).
@@ -647,7 +653,7 @@ changed on-the-fly. They’re powerful but have some issues:
* changing the mappings repeatedly can be slow
* the address space state is not saved in the saved states, so it has to
be rebuilt after state load
-* they can be hidden anywhere rather that be grouped in an address map,
+* they can be hidden anywhere rather than be grouped in an address map,
which can be less readable
The methods, rather than decomposing the information in handler, handler
diff --git a/docs/source/techspecs/naming.rst b/docs/source/techspecs/naming.rst
index 94d3a889649..4846876c0cd 100644
--- a/docs/source/techspecs/naming.rst
+++ b/docs/source/techspecs/naming.rst
@@ -1,3 +1,5 @@
+.. _naming:
+
MAME Naming Conventions
=======================
@@ -13,25 +15,6 @@ To promote consistency and readability in MAME source code, we have some
naming conventions for various elements.
-.. _naming-definitions:
-
-Definitions
------------
-
-Snake case
- All lowercase letters with words separated by underscores:
- ``this_is_snake_case``
-Screaming snake case
- All uppercase letters with words separated by underscores:
- ``SCREAMING_SNAKE_CASE``
-Camel case:
- Lowercase initial letter, first letter of each subsequent word
- capitalised, with no separators between words: ``exampleCamelCase``
-Llama case:
- Uppercase initial letter, first letter of each subsequent word
- capitalised, with no separators between words: ``LlamaCaseSample``
-
-
.. _naming-transliteration:
Transliteration
@@ -90,7 +73,7 @@ For software list entries where a transliteration is used for the
``name="alt_title"`` attribute.
For software items that have multiple titles (for example different
-regional titles with the same installation media), use the most most
+regional titles with the same installation media), use the most
widespread English Latin title for the ``description`` element, and put
the other titles in ``info`` elements with ``name="alt_title"``
attributes.
@@ -108,39 +91,5 @@ use lowercase for anything else besides proper nouns and initialisms.
C++ naming conventions
----------------------
-Preprocessor macros
- Macro names should use screaming snake case. Macros are always
- global and name conflicts can cause confusing errors – think
- carefully about what macros really need to be in headers and name
- them carefully.
-Include guards
- Include guard macros should begin with ``MAME_``, and end with a
- capitalised version of the file name, withe separators replaced by
- underscores.
-Constants
- Constants should use screaming snake case, whether they are constant
- globals, constant data members, enumerators or preprocessor
- constants.
-Functions
- Free functions names should use snake case. (There are some utility
- function that were previously implemented as preprocessor macros
- that still use screaming snake case.)
-Classes
- Class names should use snake case. Abstract class names should end
- in ``_base``. Public member functions (including static member
- functions) should use snake case.
-Device classes
- Concrete driver ``driver_device`` implementation names
- conventionally end in ``_state``, while other concrete device class
- names end in ``_device``. Concrete ``device_interface`` names
- conventionally begin with ``device_`` and end with ``_interface``.
-Device types
- Device types should use screaming snake case. Remember that device
- types are names in the global namespace, so choose explicit,
- unambiguous names.
-Enumerations
- The enumeration name should use snake case. The enumerators should
- use screaming snake case.
-Template parameters
- Template parameters should use llama case (both type and value
- parameters).
+For C++ naming conventions, see the relevant section in the C++
+Coding Guidelines: :ref:`contributing-cxx-naming`
diff --git a/docs/source/techspecs/object_finders.rst b/docs/source/techspecs/object_finders.rst
index 2256d74b677..27fe42fdd50 100644
--- a/docs/source/techspecs/object_finders.rst
+++ b/docs/source/techspecs/object_finders.rst
@@ -239,7 +239,7 @@ the object finders in the device class (with all distractions removed):
}
sbus_device(machine_config const &mconfig, char const *tag, device_t *owner, u32 clock) :
- device_t(mconfig, type, tag, owner, clock),
+ device_t(mconfig, SBUS, tag, owner, clock),
device_memory_interface(mconfig, *this),
m_maincpu(*this, finder_base::DUMMY_TAG),
m_type1space(*this, finder_base::DUMMY_TAG, -1)
@@ -478,7 +478,7 @@ for all elements of the array):
};
This finds or creates memory shares with tags ``vram_0`` and ``vram_1``, each of
-of which is 8 KiB organised as 4,096 big-Endian 16-bit words.
+which is 8 KiB organised as 4,096 big-Endian 16-bit words.
Optional object finders
diff --git a/docs/source/techspecs/poly_manager.rst b/docs/source/techspecs/poly_manager.rst
index e86cf481428..d30a57c39c3 100644
--- a/docs/source/techspecs/poly_manager.rst
+++ b/docs/source/techspecs/poly_manager.rst
@@ -951,7 +951,7 @@ poly_array
poly_array();
-The **poly_array** contructor requires no parameters and simply pre-allocates one
+The **poly_array** constructor requires no parameters and simply pre-allocates one
chunk of objects in preparation for future allocations.
count
diff --git a/docs/source/tools/castool.rst b/docs/source/tools/castool.rst
index b4d8f81467f..73fb095d9b1 100644
--- a/docs/source/tools/castool.rst
+++ b/docs/source/tools/castool.rst
@@ -9,7 +9,7 @@ Castool is part of the MAME project. It shares large portions of code with MAME,
Using Castool
-=============
+-------------
Castool is a command line program that contains a simple set of instructions. Commands are invoked in a manner along the lines of this:
@@ -30,7 +30,7 @@ Example usage:
Castool Formats
-===============
+---------------
These are the formats supported by Castool for conversion to .WAV files.
diff --git a/docs/source/tools/chdman.rst b/docs/source/tools/chdman.rst
new file mode 100644
index 00000000000..04612642764
--- /dev/null
+++ b/docs/source/tools/chdman.rst
@@ -0,0 +1,456 @@
+.. _chdman:
+
+chdman – CHD (Compressed Hunks of Data) File Manager
+====================================================
+
+chdman can be used to create, convert, check the integrity of and extract data
+from media images in CHD (Compressed Hunks of Data) format.
+
+The basic usage is ``chdman <command> <option>...``
+
+.. contents:: :local:
+
+
+.. _chdman-commonopts:
+
+Common options
+--------------
+
+The options available depend on the command, but the following options are
+used by multiple commands:
+
+--input <file> / -i <file>
+ Specify the input file. This option is required for most commands. The
+ input file formats supported depend on the command
+--inputparent <chdfile> / -ip <chdfile>
+ Specify the parent CHD file for the input file. This option is supported for
+ most commands that operate on CHD format input files. This option must be
+ used if the input file is a *delta CHD*, storing only the hunks that differ
+ from its parent CHD,
+--inputstartbyte <offset> / -isb <offset>
+ Specify the offset to the data in the input file in bytes. This is useful
+ for creating CHD format files from input files that contain a header before
+ the start of the data, or for extracting partial content from a CHD format
+ file. May not be specified in combination with the
+ ``--inputstarthunk``/``-ish`` option.
+--inputstarthunk <offset> / -ish <offset>
+ Specify the offset to the data in the input file in hunks. May not be
+ specified in combination with the ``--inputstartbyte``/``-isb`` option.
+--inputbytes <length> / -ib <length>
+ Specify the amount of input data to use in bytes, starting from the offset
+ to the data in the input file. This is useful for creating CHD format files
+ from input files that contain additional content after the data, or for
+ extracting partial content from a CHD format file. May not be specified in
+ combination with the ``--inputhunks``/``-ih`` option.
+--inputhunks <length> / -ih <length>
+ Specify the amount of input data to use in hunks, starting from the offset
+ to the data in the input file. May not be specified in combination with the
+ ``--inputbytes``/``-ib`` option.
+--output <file> / -o <file>
+ Specify the output file name. This option is required for commands that
+ produce output files. The output file formats supported depend on the
+ command.
+--outputparent <chdfile> / -op <chdfile>
+ Specify the parent CHD file for the output file. This option is supported
+ for commands that produce CHD format output files. Using this option
+ produces a *delta CHD*, storing only the hunks that differ from its parent
+ CHD. The parent CHD should be the same media type and size, with the same
+ hunk size.
+--compression none|<type>[,<type>]... / -c none|<type>[,<type>]...
+ Specify compression algorithms to use. This option is supported for commands
+ that produce CHD format output files. Specify ``none`` to disable
+ compression, or specify up to four comma-separated compression algorithms.
+ See :ref:`compression algorithms <chdman-compression>` for supported
+ compression algorithms. Compression must be disable to create writable media
+ image files.
+--hunksize <bytes> / -hs <bytes>
+ Specifies the hunk size in bytes. This option is supported for commands that
+ produce CHD format output files. The hunk size must be no smaller than
+ 16 bytes and no larger than 1048576 bytes (1 MiB). The hunk size must be a
+ multiple of the sector size or unit size of the media. Larger hunk sizes may
+ give better compression ratios, but reduce performance for small random
+ reads as an entire hunk needs to be read and decompressed at a time.
+--force / -f
+ Overwrite output files if they already exist. This option is supported for
+ commands that produce output files.
+--verbose / -v
+ Enable verbose output. This prints more detailed information for some
+ commands.
+--numprocessors <count> / -np <count>
+ Limit the maximum number of concurrent threads used for data compression.
+ This option is supported for commands that produce CHD format output files.
+
+
+.. _chdman-commands:
+
+Commands
+--------
+
+info
+~~~~
+
+Display information about a CHD format file. Information includes:
+
+* CHD format version and compression algorithms used.
+* Compressed and uncompressed sizes and overall compression ratio.
+* Hunk size, unit size and number of hunks in the file.
+* SHA1 digests of the data and metadata.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--verbose`` / ``-v``
+
+verify
+~~~~~~
+
+Verify the integrity of a CHD format file. The input file must be a read-only
+CHD format file (the integrity of writable CHD files cannot be verified). Note
+that this command modifies its input file if the ``--fix``/``-f`` option is
+specified.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+
+Additional options:
+
+* ``--fix`` / ``-f``
+
+createraw
+~~~~~~~~~
+
+Create a CHD format file from a raw media image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>``
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+Additional options:
+
+--unitsize <bytes> / -us <bytes> (required)
+ The unit size for the output CHD file in bytes. This is the smallest unit
+ of data that can be addressed within the CHD file. It should match the
+ sector size or page size of the source media. The hunk size must be a whole
+ multiple of the unit size. The unit size must be specified if no parent CHD
+ file for the output is supplied. If a parent CHD file for the output is
+ supplied, the unit size must match the unit size of the parent CHD file.
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be:
+
+* The hunk size of the parent CHD file if a parent CHD file for the output is
+ supplied.
+* The smallest whole multiple of the unit size not larger than 4 KiB if the unit
+ size is not larger than 4 KiB (4096 bytes).
+* The unit size if it is larger than 4 KiB (4096 bytes).
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``lzma,zlib,huff,flac``.
+
+createhd
+~~~~~~~~
+
+Create a CHD format hard disk image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+Additional options:
+
+* ``--sectorsize <bytes>`` / ``-ss <bytes>``
+* ``--size <bytes>`` / ``-s <bytes>``
+* ``--chs <cylinders>,<heads>,<sectors>`` / ``-chs <cylinders>,<heads>,<sectors>``
+* ``--template <template>`` / ``-tp <template>``
+
+Creates a blank (zero-filled) hard disk image if no input file is supplied. The
+input start/length (``--inputstartbyte``/``-isb``,
+``--inputstarthunk``/``-ish``, ``--inputbytes``/``-ib`` and
+``--inputhunks``/``-ih`` options) cannot be used if no input file is supplied.
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be:
+
+* The hunk size of the parent CHD file if a parent CHD file for the output is
+ supplied.
+* The smallest whole multiple of the sector size not larger than 4 KiB if the
+ sector size is not larger than 4 KiB (4096 bytes).
+* The sector size if it is larger than 4 KiB (4096 bytes).
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``lzma,zlib,huff,flac`` if an input file is supplied, or ``none`` if no input
+file is supplied.
+
+createcd
+~~~~~~~~
+
+Create a CHD format CD-ROM image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be
+the hunk size of the parent CHD if a parent CHD file for the output is supplied,
+or eight sectors per hunk (18,816 bytes) otherwise.
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``cdlz,cdzl,cdfl``.
+
+createdvd
+~~~~~~~~~
+
+Create a CHD format DVD-ROM image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+If the ``--hunksize`` or ``-hs`` option is not supplied, the default will be
+the hunk size of the parent CHD if a parent CHD file for the output is supplied,
+or two sectors per hunk (4096 bytes) otherwise.
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``lzma,zlib,huff,flac``.
+
+createld
+~~~~~~~~
+
+Create a CHD format LaserDisc image file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--outputparent <chdfile>`` / ``-op <chdfile>``
+* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...``
+* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required)
+* ``--force`` / ``-f``
+* ``--numprocessors <count>`` / ``-np <count>``
+
+Additional options:
+
+* ``--inputstartframe <offset>`` / ``-isf <offset>``
+* ``--inputframes <length>`` / ``-if <length>``
+
+If the ``--compression`` or ``-c`` option is not supplied, it defaults to
+``avhu``.
+
+extractraw
+~~~~~~~~~~
+
+Extract data from a CHD format raw media image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+extracthd
+~~~~~~~~~
+
+Extract data from a CHD format hard disk image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+extractcd
+~~~~~~~~~
+
+Extract data from a CHD format CD-ROM image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+Additional options:
+
+* ``--outputbin <file>`` / ``-ob <file>``
+
+extractdvd
+~~~~~~~~~~
+
+Extract data from a CHD format DVD-ROM image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--inputstartbyte <offset>`` / ``-isb <offset>``
+* ``--inputstarthunk <offset>`` / ``-ish <offset>``
+* ``--inputbytes <length>`` / ``-ib <length>``
+* ``--inputhunks <length>`` / ``-ih <length>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+extractld
+~~~~~~~~~
+
+Extract data from a CHD format DVD-ROM image.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--inputparent <chdfile>`` / ``-ip <chdfile>``
+* ``--output <file>`` / ``-o <file>`` (required)
+* ``--force`` / ``-f``
+
+Additional options:
+
+* ``--inputstartframe <offset>`` / ``-isf <offset>``
+* ``--inputframes <length>`` / ``-if <length>``
+
+addmeta
+~~~~~~~
+
+Add a metadata item to a CHD format file. Note that this command modifies its
+input file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+
+Additional options:
+
+* ``--tag <tag>`` / ``-t <tag>`` (required)
+* ``--index <index>`` / ``-ix <index>``
+* ``--valuetext <text>`` / ``-vt <text>``
+* ``--valuefile <file>`` / ``-vf <file>``
+* ``--nochecksum`` / ``-nocs``
+
+delmeta
+~~~~~~~
+
+Delete a metadata item from a CHD format file. Note that this command modifies
+its input file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+
+Additional options:
+
+* ``--tag <tag>`` / ``-t <tag>`` (required)
+* ``--index <index>`` / ``-ix <index>``
+
+dumpmeta
+~~~~~~~~
+
+Extract metadata items from a CHD format file to the standard output or to a
+file.
+
+Common options supported:
+
+* ``--input <file>`` / ``-i <file>`` (required)
+* ``--output <file>`` / ``-o <file>``
+* ``--force`` / ``-f``
+
+Additional options:
+
+* ``--tag <tag>`` / ``-t <tag>`` (required)
+* ``--index <index>`` / ``-ix <index>``
+
+listtemplates
+~~~~~~~~~~~~~
+
+List available hard disk templates. This command does not accept any options.
+
+
+.. _chdman-compression:
+
+Compression algorithms
+----------------------
+
+The following compression algorithms are supported:
+
+zlib – zlib deflate
+ Compresses data using the zlib deflate algorithm.
+zstd – Zstandard
+ Compresses data using the Zstandard algorithm. This gives very good
+ compression and decompression performance with better compression ratios than
+ zlib deflate, but older software may not support CHD files that use Zstandard
+ compression.
+lzma – Lempel-Ziv-Markov chain algorithm
+ Compresses data using the Lempel-Ziv-Markov-chain algorithm (LZMA). This
+ gives high compression ratios at the cost of poor compression and
+ decompression performance.
+huff – Huffman coding
+ Compresses data using 8-bit Huffman entropy coding.
+flac – Free Lossless Audio Codec
+ Compresses data as two-channel (stereo) 16-bit 44.1 kHz PCM audio using the
+ Free Lossless Audio Codec (FLAC). This gives good compression ratios if the
+ media contains 16-bit PCM audio data.
+cdzl – zlib deflate for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the zlib deflate algorithm.
+cdzs – Zstandard for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the Zstandard algorithm. This gives very good compression and
+ decompression performance with better compression ratios than zlib deflate,
+ but older software may not support CHD files that use Zstandard compression.
+cdlz - Lempel-Ziv-Markov chain algorithm/zlib deflate for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the Lempel-Ziv-Markov chain algorithm (LZMA) for audio data and the
+ zlib deflate algorithm for subchannel data. This gives high compression
+ ratios at the cost of poor compression and decompression performance.
+cdfl – Free Lossless Audio Codec/zlib deflate for CD-ROM data
+ Compresses audio data and subchannel data from CD-ROM sectors separately
+ using the Free Lossless Audio Codec (FLAC) for audio data and the zlib
+ deflate algorithm for subchannel data. This gives good compression ratios
+ for audio CD tracks.
+avhu – Huffman coding for audio-visual data
+ This is a specialised compression algorithm for audio-visual (A/V) data. It
+ should only be used for LaserDisc CHD files.
diff --git a/docs/source/tools/floptool.rst b/docs/source/tools/floptool.rst
index f2e24eac56f..bf71c296aee 100644
--- a/docs/source/tools/floptool.rst
+++ b/docs/source/tools/floptool.rst
@@ -9,7 +9,7 @@ Floptool is part of the MAME project. It shares large portions of code with MAME
Using Floptool
-==============
+--------------
Floptool is a command line program that contains a simple set of instructions. Commands are invoked in a manner along the lines of this:
@@ -33,7 +33,7 @@ Example usage:
Floptool Formats
-================
+----------------
These are the formats supported by Floptool for conversion to other formats.
diff --git a/docs/source/tools/imgtool.rst b/docs/source/tools/imgtool.rst
index b874fdfe215..e54638ea59b 100644
--- a/docs/source/tools/imgtool.rst
+++ b/docs/source/tools/imgtool.rst
@@ -10,7 +10,7 @@ Imgtool is part of the MAME project. It shares large portions of code with MAME,
**Some portions of Imgtool are Copyright (c) 1989, 1993 The Regents of the University of California. All rights reserved.**
Using Imgtool
-=============
+-------------
Imgtool is a command line program that contains several "subcommands" that actually do all of the work. Most commands are invoked in a manner along the lines of this:
@@ -32,7 +32,7 @@ Further details vary with each subcommand. Also note that not all subcommands a
Imgtool Subcommands
-===================
+-------------------
**create**
@@ -64,7 +64,7 @@ Imgtool Subcommands
**put**
- **imgtool put <format> <imagename> <filename>... <destname> [--(fileoption)==value] [--filter=filter] [--fork=fork]**
+ **imgtool put <format> <imagename> <filename>... <destname> [--(fileoption)=value] [--filter=filter] [--fork=fork]**
* <format> is the image format, e.g. coco_jvc_rsdos
* <imagename> is the image filename; can specify a ZIP file for image name
@@ -151,7 +151,7 @@ Imgtool Subcommands
Imgtool Filters
-===============
+---------------
Filters are a means to process data being written into or read out of an image in a certain way. Filters can be specified on the get, put, and getall commands by specifying --filter=xxxx on the command line. Currently, the following filters are supported:
@@ -173,7 +173,7 @@ Filters are a means to process data being written into or read out of an image i
**vzsnapshot**
- [todo: VZ Snapshot? Find out what this is....]
+ [todo: VZ Snapshot? Find out what this is...]
**vzbas**
diff --git a/docs/source/tools/index.rst b/docs/source/tools/index.rst
index 6d0551bf1d1..4086f924b99 100644
--- a/docs/source/tools/index.rst
+++ b/docs/source/tools/index.rst
@@ -1,12 +1,14 @@
MAME External Tools
--------------------
+===================
-This section covers various extra tools that come with your MAME distribution (e.g. *imgtool*)
+This section describes additional tools that are built alongside and typically
+distributed with MAME.
.. toctree::
- :titlesonly:
+ :titlesonly:
- imgtool
- castool
- floptool
- othertools
+ chdman
+ imgtool
+ castool
+ floptool
+ othertools
diff --git a/docs/source/tools/othertools.rst b/docs/source/tools/othertools.rst
index eb4c479b846..ebf31719d16 100644
--- a/docs/source/tools/othertools.rst
+++ b/docs/source/tools/othertools.rst
@@ -44,12 +44,18 @@ ldresample
This tool recompresses video data for laserdisc and VHS dumps. Most users will not need to work with this.
-
ldverify
--------
This tool is used for comparing laserdisc or VHS CHD images with the source AVI. Most users will not need to work with this.
+
+romcmp
+------
+
+This tool is used to perform basic data comparisons and integrity checks on binary dumps. With the -h switch, it can also be used to calculate hash functions. Most users will not need to work with this.
+
+
unidasm
-------
diff --git a/docs/source/usingmame/aboutromsets.rst b/docs/source/usingmame/aboutromsets.rst
index 51c72d0ce41..3a5197a3159 100644
--- a/docs/source/usingmame/aboutromsets.rst
+++ b/docs/source/usingmame/aboutromsets.rst
@@ -68,6 +68,24 @@ If you hit problems with a set not working, there are several things to check--
ROMs and CHDs
-------------
-ROM chip data tends to be relatively small and gets loaded to system memory outright. Some games also used additional storage mediums such as hard drives, CD-ROMs, DVDs, and Laserdiscs. Those storage mediums are, for multiple technical reasons, not well-suited to being stored the same way as ROM data and won't fit completely in memory in some cases.
-
-Thus, a new format was created for these in the CHD file. **Compressed Hunks of Data**, or CHD for short, are designed very specifically around the needs of mass storage media. Some arcade games, consoles, and PCs will require a CHD to run. As CHDs are already compressed, they should **NOT** be stored in a ZIP or 7Z file as you would for ROM images.
+ROM chip data tends to be relatively small and are loaded into system memory in
+their entirety. Some games also used additional storage media such as hard
+disks, CD-ROMs, DVDs, and LaserDiscs. Those storage media are, for multiple
+technical reasons, not well-suited to being stored the same way as ROM data and
+won’t fully fit in memory in some cases.
+
+Thus, a new format was created for these in the CHD file. **Compressed Hunks of
+Data** files, or CHD files for short, are designed very specifically around the
+needs of mass storage media. Some arcade games, consoles, and PCs will require
+one or more CHD files to run. As CHD files are already compressed, they
+**should not** be stored PKZIP or 7-Zip archives as ROM images would be.
+
+To save space when multiple variants of a system or software item are present,
+MAME supports *delta CHD* files. A delta CHD file only stores the parts of the
+data that differ from its *parent CHD* file. This allows large space savings
+when different variants share a lot of data. Delta CHD files can only be used
+for clone systems, devices with a parent ROM device, and clone software items.
+A delta CHD file must use a (non-delta) CHD file from the parent system, parent
+ROM device or parent software item as its parent CHD file. The parent CHD file
+must be present to use a delta CHD file, or MAME will not be able to read the
+shared data from it.
diff --git a/docs/source/usingmame/assetsearch.rst b/docs/source/usingmame/assetsearch.rst
new file mode 100644
index 00000000000..325d4bcfd7e
--- /dev/null
+++ b/docs/source/usingmame/assetsearch.rst
@@ -0,0 +1,398 @@
+.. _assetsearch:
+
+How does MAME look for files?
+=============================
+
+.. contents:: :local:
+
+Introduction
+------------
+
+Unlike typical desktop applications where you browse your disk and select a file
+to open or a location to save to, MAME has settings to tell it where to look for
+the files it needs. You can change these settings by starting MAME without
+specifying a system, selecting **Configure Options** from the system selection
+menu, and then selecting **Configure Directories** (remember to select **Save
+Configuration** if you want to keep your changes). You can also change settings
+by editing your mame.ini and ui.ini files directly, or specify settings on the
+command line. For information on available options for controlling where MAME
+searches for files, see :ref:`mame-commandline-pathoptions`.
+
+Terminology
+~~~~~~~~~~~
+
+It’s necessary to understand some MAME-specific terminology used in the
+explanations here:
+
+System
+ A system is a complete machine that can be emulated by MAME. Some systems
+ run fixed software, while others can load software from software list items
+ and/or media files.
+Device
+ An emulated component that can be used by multiple systems, or by other
+ devices. Some devices require ROM dumps, and some devices allow software
+ from additional software lists to be used with a system.
+Parent system
+ MAME uses so-called parent/clone relationships to group related systems.
+ One system in the group is chosen to be the *parent* and the others are
+ called *clones*. (The choice of the parent system is somewhat arbitrary.
+ It is not necessarily the original or definitive variant.)
+BIOS system
+ A system configured with no software. This is mostly applicable for arcade
+ systems that used interchangeable game cartridges or ROM boards. Note that
+ this is *not* the same as the BIOS selection settings that allow you to
+ select system boot ROMs or device firmware.
+Software item
+ A software package described in a software list. Software items may consist
+ of multiple *parts* that can be mounted independently. Due to the large
+ variety of media supported by MAME, software parts may use different
+ *loaders*. These include the *ROM loader*, typically used for cartridge
+ media, and the *image file loader*, used for software parts consisting of a
+ single media image (including floppy disk and cassette media).
+Parent software item
+ Related software items are grouped using parent/clone relationships, in a
+ similar way to related systems. This is usually used to group different
+ versions or releases of the same piece of software. If a software item has
+ a parent item, it will always be in the same software list.
+Short name
+ MAME uses *short names* to uniquely identify systems and devices, to
+ uniquely identify software lists, to uniquely identify software items within
+ a software list, and to uniquely identify software parts within a software
+ item.
+
+ You can see the short name for a system by highlighting it in the system
+ selection menu, ensuring the info panel is visible on the right, and
+ showing the **General Info** in the **Infos** tab. For example the short
+ name for the Nintendo Virtual Boy is ``vboy``. System and device short
+ names can also be seen in the output of various command line verbs,
+ including ``-listxml``, ``-listfull``, ``-listroms`` and ``-listcrc``.
+
+ You can see the short names for a software item and the software list it
+ belongs to by highlighting it in the software selection menu, ensuring the
+ info panel is visible on the right, and showing the **Software List Info**
+ in the **Infos** tab. For example the short name for Macintosh System
+ Software 6.0.3 is ``sys603`` and the short name of the software list it
+ belongs to is ``mac_flop``. Software list short names match their file
+ names (for example the Sega Mega Drive/Genesis cartridge software list is
+ called **megadriv.xml** and its short name is ``megadriv``). You can also
+ see the short names software lists, software items and parts by finding the
+ ``name`` attributes in the XML software list files.
+
+
+Search path options
+-------------------
+
+Most options for specifying locations to search allow multiple directories to be
+specified, separated by semicolon (``;``) characters. Environment variables are
+expanded, using CMD shell syntax on Windows, or Bourne shell syntax on UNIX-like
+systems.
+
+Relative paths are interpreted relative to the current working directory at the
+time of use. 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 or from most Linux desktop
+environments, the working directory will be set to your home directory.
+
+
+Archive files
+-------------
+
+MAME can load files from PKZIP and 7-Zip archives (these must have ``.zip`` and
+``.7z`` file name extensions, respectively). A number of extensions to the
+PKZIP format are supported, including Zip64 for large archives, NTFS timestamps,
+and LZMA compression. Only ASCII or UTF-8 filenames are supported in PKZIP
+archives (7-Zip archives always use UTF-16 filenames).
+
+MAME *does not* load files from nested archives. MAME will not load files
+stored in a PKZIP or 7-Zip archive which is itself contained within a PKZIP or
+7-Zip archive. Multi-segment archives and encrypted archives are not supported.
+The legacy “implode” compression method in PKZIP archives is not supported.
+
+MAME may perform poorly with archives containing large numbers of files. Files
+compressed using the LZMA compression algorithm are inherently more
+CPU-intensive to decompress than files compressed using simpler algorithms.
+MAME does not take the archive layout into consideration when loading files from
+archives, so using “solid compression” often results in MAME decompressing the
+same data repeatedly when loading media.
+
+
+How does MAME search for media?
+-------------------------------
+
+Use the :ref:`rompath <mame-commandline-rompath>` option sets the folders where
+searches for ROM dumps, disk images, and other media. By default MAME looks for
+media in a folder called **roms** in the working directory. For the purpose of
+this discussion, floppy disk, cassette, paper tape and other media images that
+are not stored in CHD format are treated as ROM dumps.
+
+When searching for system, device and software ROM dumps, MAME treats folders
+and archives inside the folders configured in you ``rompath`` setting as
+equivalent, but remember the limitation that MAME cannot load files from an
+archive contained within another archive. MAME looks for a folder first, then a
+PKZIP archive, and finally a 7-Zip archive. When searching for a ROM dump in an
+archive, MAME first looks for a file with the expected name and CRC. If no
+matching file is found, MAME looks for a file with the expected CRC ignoring the
+name. If no matching file is found, MAME finally looks for a file with the
+expected name, ignoring the CRC.
+
+While MAME can load disk images in CHD format from inside archives, this is not
+recommended. CHD files contain compressed data stored in a format allowing
+random access. If a CHD format disk image is stored in a PKZIP or 7-Zip
+archive, MAME needs to load the entire file into memory in order to use it. For
+hard disk or LaserDisc images in particular, this will likely use an excessive
+amount of swap file space, hurting performance and possibly reducing the life
+expectancy of your disks or SSDs. It’s best to keep CHD format disk images in
+folders.
+
+System ROMs
+~~~~~~~~~~~
+
+For each folder configured in your ``rompath`` setting, MAME looks for system
+ROMs in the following locations:
+
+* A folder or archive matching the short name of the system itself.
+* A folder or archive matching the short name of the system’s parent system, if
+ applicable.
+* A folder or archive matching the short name of the corresponding BIOS system,
+ if applicable.
+
+Using Shiritsu Justice Gakuen as an example, MAME will search for system ROMs as
+follows:
+
+* The short name of the system is ``jgakuen``, so MAME will look for a folder
+ called **jgakuen**, a PKZIP archive called **jgakuen.zip**, or a 7-Zip archive
+ called **jgakuen.7z**.
+* The parent system is the European version of Rival Schools, which has the
+ short name ``rvschool``, so MAME will look for a folder called **rvschool**, a
+ PKZIP archive called **rvschool.zip**, or a 7-Zip archive called
+ **rvschool.7z**.
+* The corresponding BIOS system is the Capcom ZN2 board, which has the short
+ name ``coh3002c``, so MAME will look for a folder called **coh3002c**, a PKZIP
+ archive called **coh3002c.zip**, or a 7-Zip archive called **coh3002c.7z**.
+
+Device ROMs
+~~~~~~~~~~~
+
+For each folder configured in your ``rompath`` setting, MAME looks for device
+ROMs in the following locations:
+
+* A folder or archive matching the short name of the device.
+* A folder or archive matching the short name of the device’s parent ROM device,
+ if applicable.
+* A folder or archive matching the short name of the system.
+* A folder or archive matching the short name of the system’s parent system, if
+ applicable.
+* A folder or archive matching the short name of the corresponding BIOS system,
+ if applicable.
+
+Using a Unitron 1024 Macintosh clone with a French Macintosh Plus keyboard with
+integrated numeric keypad attached as an example, MAME will look for the
+keyboard microcontroller ROM as follows:
+
+* The short name of the French Macintosh Plus keyboard is ``mackbd_m0110a_f``,
+ so MAME will look for a folder called **mackbd_m0110a_f**, a PKZIP archive
+ called **mackbd_m0110a_f.zip**, or a 7-Zip archive called
+ **mackbd_m0110a_f.7z**.
+* The parent ROM device is the U.S. Macintosh Plus keyboard with integrated
+ numeric keypad, which has the short name ``mackbd_m0110a``, so MAME will look
+ for a folder called **mackbd_m0110a**, a PKZIP archive called
+ **mackbd_m0110a.zip**, or a 7-Zip archive called **mackbd_m0110a.7z**.
+* The short name of the Unitron 1024 system is ``utrn1024``, so MAME will look
+ for a folder called **utrn1024**, a PKZIP archive called **utrn1024.zip**, or
+ a 7-Zip archive called **utrn1024.7z**.
+* The parent system of the Unitron 1024 is the Macintosh Plus, which has the
+ short name ``macplus``, so MAME will look for a folder called **macplus**, a
+ PKZIP archive called **macplus.zip**, or a 7-Zip archive called
+ **macplus.7z**.
+* There is no corresponding BIOS system, so MAME will not search in any further
+ locations.
+
+Software Item ROMs
+~~~~~~~~~~~~~~~~~~
+
+For each folder configured in your ``rompath`` setting, MAME looks for software
+item ROMs in the following locations:
+
+* A folder or archive matching the short name of the software item inside a
+ folder matching the short name of the software list (or a folder matching the
+ short name of the software item inside an archive matching the name of the
+ software list).
+* A folder or archive matching the short name of the parent software item inside
+ a folder matching the short name of the software list, if applicable (or a
+ folder matching the short name of the parent software item in an archive
+ matching the name of the software list).
+* A folder or archive matching the short name of the software item. (This is
+ for convenience for software items that also run as stand-alone systems with
+ the same short name, such as Neo Geo games.)
+* A folder or archive matching the short name of the parent software item, if
+ applicable. (This is for convenience for software items that also run as
+ stand-alone systems with the same short name, such as Neo Geo games.)
+
+If you load the German version of Dune II from the Mega Drive/Genesis cartridge
+software list in the PAL Mega Drive console, MAME will look for the cartridge
+ROM as follows:
+
+* The short name of the software item for the German version of Dune II is
+ ``dune2g`` and the short name of the Mega Drive/Genesis cartridge software
+ list is ``megadriv``, so MAME will look for a folder called **dune2g**, a
+ PKZIP archive called **dune2g.zip** or a 7-Zip archive called **dune2g.7z**
+ inside a folder called **megadriv** (or a folder called **dune2g** inside a
+ PKZIP archive called **megadriv.zip** or a 7-Zip archive called
+ **megadriv.7z**).
+* The parent software item is the general European PAL version of Dune II in the
+ same software list, which has the short name ``dune2``, so MAME will look for
+ a folder called **dune2**, a PKZIP archive called **dune2.zip** or a 7-Zip
+ archive called **dune2.7z** inside a folder called **megadriv** (or a folder
+ called **dune2** inside a PKZIP archive called **megadriv.zip** or a 7-Zip
+ archive called **megadriv.7z**).
+* Next MAME will ignore the short name of the software list and use the short
+ name of the software item only, looking for a folder called **dune2g**, a
+ PKZIP archive called **dune2g.zip** or a 7-Zip archive called **dune2g.7z**.
+* Still ignoring the short name of the software list, MAME will use the short
+ name of the parent software item only, looking for a folder called **dune2**,
+ a PKZIP archive called **dune2.zip** or a 7-Zip archive called **dune2.7z**.
+
+CHD format disk images
+~~~~~~~~~~~~~~~~~~~~~~
+
+MAME searches for system, device and software item CHD format disk images in
+almost the same way it searches for ROMs, with just a few differences:
+
+* For systems and software items, MAME will check the parent system or software
+ item if applicable for alternate names for a disk image with the same content
+ digest. This allows you to keep a single copy of a CHD format disk image for
+ a parent system or software item and any clones that expect a disk image with
+ the same content, irrespective of the name the clones expect.
+* For software items, MAME will look for CHD format disk images in a folder
+ matching the short name of the software list. This is for convenience when
+ all items in a software list only contain a single CHD format disk image each.
+* We recommend that you *do not* store CHD format disk images inside PKZIP or
+ 7-Zip archives. However, if you do decide to do this, MAME will only find CHD
+ format disk images inside archives with an expected name. This is because
+ MAME uses the content digest from the CHD header, not the checksum of the CHD
+ file itself. The checksum of the CHD file itself can vary depending on
+ compression options.
+
+To save space, MAME allows delta CHD files to be used for clone systems, devices
+with parent ROM devices and clone software items. The delta CHD file must use a
+CHD format disk image from the parent system, parent ROM device or parent
+software item as its parent CHD file. The space saved depends on how much
+content can be reused from the parent CHD file. MAME searches the same
+locations for parent CHD files that it would search for the disk image itself.
+
+Loose software
+~~~~~~~~~~~~~~
+
+Many systems support loading media from a file by supplying the path on the
+command line for one of the media options. Relative paths are interpreted
+relative to the current working directory.
+
+You can specify a path to a file inside a PKZIP or 7-Zip archive similarly to
+specifying a path to a file in a folder (keep in mind that you can have at most
+a single archive file in a path, as MAME does not support loading files from
+archives contained within other archives). If you specify a path to a PKZIP or
+7-Zip archive, MAME will use the first file found in the archive (this depends
+on the order that files are stored in the archive – it’s most useful for
+archives containing a single file).
+
+Start the Nintendo Entertainment System/Famicom system with the file
+**amazon_diet_EN.nes** mounted in the cartridge slot:
+
+.. code-block:: bash
+
+ mame nes -cart amazon_diet_EN.nes
+
+Start the Osborne-1 system with the first file in the archive **os1xutls.zip**
+mounted in the first floppy disk drive:
+
+.. code-block:: bash
+
+ mame osborne1 -flop1 os1xutils.zip
+
+Start the Macintosh Plus system with the file **system tools.img** in the
+archive **sys603.zip** mounted in the first floppy disk drive:
+
+.. code-block:: bash
+
+ mame macplus -flop1 "sys603.zip/system tools.img"
+
+Diagnosing missing media
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When starting a system from MAME’s system selection menu or software selection
+menu, MAME will list any missing system or device ROM dumps or disk images, as
+long as at least one ROM dump or disk image for the system is present. For
+clone systems, at least one ROM dump or disk image *unique to the clone* must be
+present for MAME to list missing ROM dumps and disk images.
+
+If all system and device ROM dump and disk images are present and the system is
+being started with a software item, MAME will check that ROM dumps and disk
+images for the software item are present. If at least one ROM dump or disk
+image for the software item is present, MAME will list any missing ROM dumps or
+disk images.
+
+For example if you try to start the Macintosh Plus system and the keyboard
+microcontroller ROM dump is missing, MAME displays the following error message:
+
+ Required ROM/disk images for the selected system are missing or incorrect.
+ Please acquire the correct files or select a different system.
+
+ 341-0332-a.bin (mackbd_m0110a) - not found
+
+ Press any key to continue.
+
+The name of the missing ROM dump is shown (**341-0332-a.bin**), as well as the
+short name of the device it belongs to (``mackbd_m0110a``). When a missing ROM
+dump or disk image is not specific to the selected system, the short name of the
+system or device it belongs to is shown.
+
+If you start a system in MAME from a command prompt, MAME will show where it
+searched for any ROM dumps or disk images that were not found.
+
+Using the example of a Unitron 1024 Macintosh clone with a French keyboard
+connected, MAME will show the following error messages if no ROMs are present::
+
+ mame utrn1024 -kbd frp
+ 342-0341-a.u6d NOT FOUND (tried in utrn1024 macplus)
+ 342-0342-a.u8d NOT FOUND (tried in utrn1024 macplus)
+ 341-0332-a.bin NOT FOUND (tried in mackbd_m0110a_f mackbd_m0110a utrn1024 macplus)
+
+MAME used the system short name ``utrn1024`` and the parent system short name
+``macplus`` when searching for system ROMs. When searching for the keyboard
+microcontroller ROM, MAME used the device short name ``mackbd_m0110a_f``, the
+parent ROM device short name ``mackbd_m0110a``, the system short name
+``utrn1024``, and the parent system short name ``macplus``.
+
+Software parts that use the ROM loader (typically cartridge media) show similar
+messages when ROM dumps are not found. Using the example of the German version
+of Dune II on a PAL Mega Drive, MAME will show the following error messages if
+no ROMs are present::
+
+ mame megadriv dune2g
+ mpr-16838-f.u1 NOT FOUND (tried in megadriv\dune2g megadriv\dune2 dune2g dune2 megadriv genesis)
+ Fatal error: Required files are missing, the machine cannot be run.
+
+MAME searched for the cartridge ROM using:
+
+* The software list short name ``megadriv`` and the software item short name
+ ``dune2g``.
+* The software list short name ``megadriv`` and the parent software item short
+ name ``dune2``.
+* The software item short name ``dune2g`` only.
+* The parent software item short name ``dune2`` only.
+* The locations that would be searched for the PAL Mega Drive system (the system
+ short name ``megadriv`` and the parent system short name ``genesis``).
+
+Software parts that use the image file loader (including floppy disk and
+cassette media) only check for media after ROM images are loaded, and missing
+media files are shown differently. Using the example of Macintosh System 6.0.3,
+MAME will show these error messages if the software is missing::
+
+ mame macplus -flop1 sys603:flop1
+ :fdc:0:35dd: error opening image file system tools.img: No such file or directory (generic:2) (tried in mac_flop\sys603 sys603 macplus)
+ Fatal error: Device Apple/Sony 3.5 DD (400/800K GCR) load (-floppydisk1 sys603:flop1) failed: No such file or directory
+
+The error messages show where MAME searched for the image file in the same
+format. In this case, it used the software list short name ``mac_flop`` and the
+software short name ``sys603``, the software short name ``sys603`` only, and
+the locations that would be searched for system ROMs.
diff --git a/docs/source/usingmame/commonissues.rst b/docs/source/usingmame/commonissues.rst
index bd7a29f31af..50f81671934 100644
--- a/docs/source/usingmame/commonissues.rst
+++ b/docs/source/usingmame/commonissues.rst
@@ -309,7 +309,7 @@ You can try changing the
:ref:`lightgunprovider <mame-commandline-lightgunprovider>` setting (depending
on which kind of device you’re having issues with) from ``rawinput`` to one of
the other options such as ``dinput`` or ``win32``. See
-:ref:`osd-commandline-options` for details on input provider options
+:ref:`mame-commandline-osdoptions` for details on input provider options
.. _ExternalOPL:
diff --git a/docs/source/usingmame/defaultkeys.rst b/docs/source/usingmame/defaultkeys.rst
index d66c6556a4a..9892c86cb1f 100644
--- a/docs/source/usingmame/defaultkeys.rst
+++ b/docs/source/usingmame/defaultkeys.rst
@@ -35,8 +35,8 @@ and saving/loading save states.
If you are running with -debug, this key sends a ‘break’ in emulation.
- When the on-screen display is visible, you can use the following
- keys to control it:
+ When a slider control is visible, you can use the following keys to control
+ it:
* **Up** - select previous parameter to modify.
* **Down** - select next parameter to modify.
@@ -63,7 +63,8 @@ and saving/loading save states.
Highlight first or last UI menu option.
**[** **]**
Move to previous or next group in UI menus that support it (e.g. move to the
- inputs for the previous or next device in the Input (this Machine) menu).
+ inputs for the previous or next device in the **Input Assignments (this
+ System)** menu).
**Enter**/**Joystick 1 Button 1**
Select currently highlighted UI menu option.
**Space**
@@ -71,13 +72,6 @@ and saving/loading save states.
**Delete**
Clear/reset to default when highlighting an entry on the input
configuration, cheat options, and plugin options pages.
-**P**
- Pauses the emulated machine.
-**Left Shift+P**
- While paused, advances to next frame. If rewind is enabled, a new rewind
- save state is also captured.
-**Left Shift+~**
- While paused, loads the most recent rewind save state.
**F1**
Power the machine on for machines that have specific power button behavior.
**F2**
@@ -115,8 +109,10 @@ and saving/loading save states.
* **Home**/**End** - move to top/bottom of list.
* **Left**/**Right** - change color displayed.
* **R** - rotate tiles 90 degrees clockwise.
- * **-**/**+** - increase/decrease the number of tiles per row.
- * **0** - restore the default number of tiles per row.
+ * **-**/**+** - increase/decrease the number of tiles per row (hold Shift to
+ restrict to integer scale factors).
+ * **0** - restore the default number of tiles per row (hold Shift to
+ restrict to integer scale factors).
* **Enter** - switch to tilemap viewer.
Tilemap mode:
@@ -131,18 +127,20 @@ and saving/loading save states.
* **Enter** - switch to palette/colortable mode.
Note: Not all systems have decoded graphics and/or tilemaps.
-**Left Ctrl+F5**
- Toggle Filter.
- (*SDL MAME only*)
-**Left Alt+Left Ctrl+F5**
- Toggle HLSL Post-Processing.
- (*Windows non-SDL MAME only*)
+**Left Shift+F4**
+ While paused, loads the most recent rewind save state.
+**F5**
+ Pauses the emulated machine.
+**Left Shift+F5**
+ While paused, advances to next frame. If rewind is enabled, a new rewind
+ save state is also captured.
**F6**
- Toggle cheat mode. (if started with “-cheat”)
-**Left Ctrl+F6**
- Decrease Prescaling.
-**Left Ctrl+F7**
- Increase Prescaling.
+ Create a save state. Requires an additional keypress to identify the state,
+ similar to the load option above. If an existing save state is present, it
+ will also appear in the selection menu to allow overwriting of that save
+ state.
+**Left Shift+F6**
+ Create a quick save state.
**F7**
Load a save state. You will be prompted to press a key or select from the
menu to determine which save state you wish to load.
@@ -152,16 +150,27 @@ and saving/loading save states.
receive a warning that the save state may not be valid when attempting to
save or load.*
**Left Shift+F7**
- Create a save state. Requires an additional keypress to identify the state,
- similar to the load option above. If an existing save state is present, it
- will also appear in the selection menu to allow overwriting of that save
- state.
+ Load a quick save state.
**F8**
Decrease frame skipping on the fly.
+**Left Shift+F8**
+ Toggle cheat mode. (if started with “-cheat”)
+**Left Alt+F8**
+ Decrease Prescaling.
+ (*SDL MAME only*)
**F9**
Increase frame skipping on the fly.
+**Left Alt+F9**
+ Increase Prescaling.
+ (*SDL MAME only*)
**F10**
Toggle speed throttling.
+**Left Alt+F10**
+ Toggle HLSL Post-Processing.
+ (*Windows non-SDL MAME only*)
+**Left Alt+F10**
+ Toggle Filter.
+ (*SDL MAME only*)
**F11**
Toggles speed display.
**Left Shift+F11**
@@ -176,14 +185,9 @@ and saving/loading save states.
Begin recording AVI video.
**Left Alt+F12**
Take HLSL Rendered Snapshot.
-**Insert**
+**Insert** (Windows non-SDL MAME)/**Page Down** (SDL MAME)
Fast forward. While held, runs game with throttling disabled and with the
maximum frameskip.
- (*Windows non-SDL MAME only*)
-**Page Down**
- Fast forward. While held, runs game with throttling disabled and with the
- maximum frameskip.
- (*SDL MAME only*)
**Left Alt+Enter**
Toggles between full-screen and windowed mode.
**Scroll Lock**/**Forward Delete** (Mac Desktop)/**fn-Delete** (Mac Laptop)
@@ -704,8 +708,8 @@ All the keys below are fully configurable in the user interface. This list shows
the standard keyboard configuration.
Note that controls can vary widely by computer type, so not all keys are shown
-here. See the “Input (this Machine)” section of MAME’s configuration menu for
-details for the machine you are currently using.
+here. See the **Input Assignments (this system)** section of MAME’s Input
+Settings menu for details for the machine you are currently using.
**Tab**
@@ -740,5 +744,5 @@ All the keys are fully configurable in the user interface.
Note that controls can vary widely by machine type, so default keys are not
shown here and defaults will vary considerably based on the manufacturer and
-style. See the “Input (this Machine)” section of MAME’s configuration menu for
-details for the machine you are currently using.
+style. See the **Input Assignments (this system)** section of MAME’s Input
+Settings menu for details for the machine you are currently using.
diff --git a/docs/source/usingmame/index.rst b/docs/source/usingmame/index.rst
index e1a2ae8f5b1..615d3f34c4b 100644
--- a/docs/source/usingmame/index.rst
+++ b/docs/source/usingmame/index.rst
@@ -13,6 +13,7 @@ documentation for your platform of choice.
ui
defaultkeys
mamemenus
+ assetsearch
frontends
aboutromsets
commonissues
diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst
index ca40b5668ed..ebade1e5188 100644
--- a/docs/source/usingmame/mamemenus.rst
+++ b/docs/source/usingmame/mamemenus.rst
@@ -1,9 +1,287 @@
+.. _menus:
+
MAME Menus
==========
-If you started MAME without any command line parameters, you'll be shown the
-system selection menu immediately. While the keys listed above will let you
-navigate the menus, you can also use a mouse.
+.. contents:: :local:
+
+
+.. _menus-intro:
+
+Introduction
+------------
+
+To show the :ref:`main menu <menus-main>` while running an emulated system in
+MAME, press the **Show/Hide Menu** key or button (**Tab** by default). If the
+emulated system has keyboard inputs, you may need to press the
+**Toggle UI Controls** key or button (**Scroll Lock**, or **Forward Delete** on
+macOS, by default) to enable user interface controls first. You can dismiss a
+menu by pressing the **UI Back** key or button (**Escape** by default).
+Dismissing a menu will return to its parent menu, or to the running system in
+the case of the main menu.
+
+You can hide a menu and return to the running system by pressing the
+**Show/Hide Menu** key or button. Pressing the **Show/Hide Menu** key or button
+again will jump back to the same menu. This is useful when testing changes to
+settings.
+
+Emulated system inputs are ignored while menus are displayed. You can still
+pause or resume the running system while most menus are displayed by pressing
+the **Pause** key or button (**F5** on the keyboard by default).
+
+If you start MAME without specifying a system on the command line, the system
+selection menu will be shown (assuming the
+:ref:`ui option <mame-commandline-ui>` is set to **cabinet**). The system
+selection menu is also shown if you select **Select New System** from the main
+menu during emulation.
+
+For more information on navigating menus, :ref:`see the relevant section
+<ui-menus>`.
+
+
+.. _menus-main:
+
+Main menu
+---------
+
+The main menu is shown when you press the **Show/Hide Menu** key or button while
+running an emulated system or while the system information screen is displayed.
+It provides access to menus used to change settings, control various features,
+and show information about the running system and MAME itself.
+
+If you press the **Show/Hide Menu** key or button to show the main menu while
+the system information screen is displayed, the emulated system will not start
+until the main menu is dismissed (either by selecting **Start System**, pressing
+the **UI Back** key or button, or pressing the **Show/Hide Menu** key or
+button). This can be useful for mounting media images or changing DIP switches
+and machine configuration settings before the emulated system starts.
+
+Input Settings
+ Shows the :ref:`Input Settings <menus-inputopts>` menu, where you can assign
+ controls to emulated inputs, adjust analog control settings, control toggle
+ inputs, and test input devices.
+DIP Switches
+ Shows the DIP Switches menu, where configuration switches for the running
+ system can be changed. This item is not shown if the running system has no
+ DIP switches.
+Machine Configuration
+ Shows the Machine Configuration menu, where various settings specific to the
+ emulated system can be changed. This item is not shown if the running
+ system has no configuration settings.
+Bookkeeping
+ Shows uptime, coin counter and ticket dispenser statistics (if relevant) for
+ the running system.
+System Information
+ Shows information about the running system as emulated in MAME, including
+ CPU, sound and video devices.
+Warning Information
+ Shows information about imperfectly emulated features of the running system.
+ This item is not shown if there are no relevant warnings.
+Media Image Information
+ Shows information about mounted media images (if any). This item is only
+ shown if the running system has one or more media devices (e.g. floppy disk
+ drives or memory card slots).
+File Manager
+ Shows the File Manager menu, where you can mount new or existing media image
+ files, or unmount currently mounted media images. This item is only shown
+ if the running system has one or more media devices (e.g. floppy disk
+ drives or memory card slots).
+Tape Control
+ Shows the Tape Control menu, where you can control emulated cassette tape
+ mechanisms. This item is only shown for systems that use cassette tape
+ media.
+Pseudo Terminals
+ Shows the status of any pseudo terminal devices in the running system (used
+ to connect the emulated system to host pseudo terminals, for example via
+ emulated serial ports). This item is not shown if there are no pseudo
+ terminal devices in the running system.
+BIOS Selection
+ Shows the BIOS Selection menu, where you can select the BIOS/boot
+ ROM/firmware for the system and slot cards it contains. This item is not
+ shown if no BIOS options are available.
+Slot Devices
+ Shows the Slot Devices menu, where you can choose between emulated
+ peripherals. This item is not shown for systems that have no slot devices.
+Barcode Reader
+ Shows the Barcode Reader menu, where you can simulate scanning barcodes with
+ emulated barcode readers. This item is not shown if there are no barcode
+ readers in the running system.
+Network Devices
+ Shows the Network Devices menu, where you can set up emulated network
+ adapters that support bridging to a host network. This item is not shown if
+ there are no network adaptors that support bridging in the running system.
+Slider Controls
+ Shows the Slider Controls menu, where you can adjust various settings,
+ including video adjustments and individual sound channel levels.
+Video Options
+ Shows the Video Options menu, where you can change the view for each
+ screen/window, as well as for screenshots.
+Crosshair Options
+ Shows the Crosshair Options menu, where you can adjust the appearance of
+ crosshairs used to show the location of emulated light guns and other
+ absolute pointer inputs. This item is not shown if the emulated system has
+ no absolute pointer inputs.
+Cheat
+ Shows the Cheat menu, for controlling the built-in cheat engine. This item
+ is only shown if the built-in chat engine is enabled. Note that the cheat
+ plugin’s menu is accessed via the Plugin Options menu.
+Plugin Options
+ Shows the Plugin Options menu, where you can access settings for enabled
+ plugins. This item is not shown if no plugins are enabled, or if the main
+ menu is shown before the emulated system starts (by pressing the Show/Hide
+ Menu key/button while the system information screen is displayed).
+External DAT View
+ Shows the info viewer, which displays information loaded from various
+ external support files. This item is not shown if the :ref:`data plugin
+ <plugins-data>` is not enabled, or if the main menu is shown before the
+ emulated system starts (by pressing the Show/Hide Menu key/button while the
+ system information screen is displayed).
+Add To Favorites/Remove From Favorites
+ Adds the running system to the favourites list, or removes it if it’s
+ already in the favourites list. The favourites list can be used as a
+ filter for the system selection menu.
+About MAME
+ Shows the emulator version, data model, and copyright license information.
+Select New System
+ Shows the system selection menu, where you can select a system to start a
+ new emulation session. This item is not shown if the main menu is shown
+ before the emulated system starts (by pressing the Show/Hide Menu key/button
+ while the system information screen is displayed).
+Close Menu/Start System
+ Closes the main menu, returning control of the running system. Shows
+ **Start System** if the main menu is shown before the emulated system
+ starts (by pressing the Show/Hide Menu key/button while the system
+ information screen is displayed).
+
+
+.. _menus-inputopts:
+
+Input Settings menu
+-------------------
+
+The Input Settings provides options for assigning controls to emulated inputs,
+adjusting analog control settings, controlling toggle inputs, and testing input
+devices. You can reach the Input Settings menu by selecting **Input Settings**
+from the :ref:`main menu <menus-main>`. The items shown on this menu depend on
+available emulated inputs for the running system. Available emulated inputs may
+depend on slot options, machine configuration settings and DIP switch settings.
+
+Input Assignments (this system)
+ Lets you select assign controls to emulated inputs for the running system.
+ See the section on :ref:`configuring inputs <ui-inptcfg>` for more details.
+ This item is not shown if the running system has no enabled inputs that can
+ be assigned controls.
+Analog Input Adjustments
+ Shows the Analog Input Adjustments menu, where you can adjust sensitivity,
+ auto-centring speed and inversion settings for emulated analog inputs, and
+ see how the emulated analog inputs respond to controls with your settings.
+ For more details, see the :ref:`analog input settings <ui-inptcfg-analog>`
+ section for more details. This item is not shown if the running system has
+ no enabled analog inputs.
+Keyboard Selection
+ Shows the :ref:`Keyboard Selection menu <menus-keyboard>`, where you can
+ select between emulated and natural keyboard modes, and enable and disable
+ keyboard and keypad inputs for individual emulated devices. This item is
+ not shown if the running system has no keyboard or keypad inputs.
+Toggle Inputs
+ Shows the :ref:`Toggle Inputs menu <menus-inputtoggle>`, where you can view
+ and adjust the state of multi-position or toggle inputs. This item is not
+ shown if the running system has no enabled toggle inputs.
+Input Assignments (general)
+ Lets you select assign user interface controls, or assign default controls
+ for all emulated systems. See the section on :ref:`configuring inputs
+ <ui-inptcfg>` for more details.
+Input Devices
+ Shows the :ref:`Input Devices menu <menus-inputdevices>`, which lists the
+ input devices recognised by MAME.
+
+
+.. _menus-inputtoggle:
+
+Toggle Inputs menu
+------------------
+
+The Toggle Inputs menu shows the current state of multi-position or toggle
+inputs. Common examples include mechanically locking Caps Lock keys on
+computers, and two-position gear shit levers on driving games. You can reach
+the Toggle Inputs menu by selecting **Toggle Inputs** from the :ref:`Input
+Settings menu <menus-inputopts>`. Note that available emulated inputs may
+depend on slot options, machine configuration settings and DIP switch settings.
+
+Inputs are grouped by the emulated device they belong to. You can move between
+devices using the **Next Group** and **Previous Group** keys or buttons. Names
+of inputs are shown on the left, and the current settings are shown on the
+right.
+
+To change the state of an input, highlight it and use the **UI Left** and **UI
+Right** keys or buttons, or click the arrows beside the current setting.
+
+
+.. _menus-keyboard:
+
+Keyboard Selection menu
+-----------------------
+
+The Keyboard Selection menu lets your switch between emulated and natural
+keyboard modes, and enable or disable keyboard inputs for individual emulated
+devices. You can reach the Keyboard Selection menu by selecting **Keyboard
+Selection** from the :ref:`Input Settings menu <menus-inputopts>`.
+
+In emulated keyboard mode, keyboard and keypad inputs behave like any other
+digital inputs, responding to their assigned controls. In natural keyboard
+mode, MAME attempts to translate typed characters to emulated keystrokes. The
+initial keyboard mode is set using the :ref:`natural option
+<mame-commandline-natural>`.
+
+There are a number of unavoidable limitations in natural keyboard mode:
+
+* The emulated system must to support it.
+* The selected keyboard *must* match the keyboard layout selected in the
+ emulated software.
+* Keystrokes that don’t produce characters can’t be translated. (e.g. pressing a
+ modifier key on its own, such as **Shift** or **Control**).
+* 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.
+* Complex input methods will not work at all (e.g. for Chinese/Japanese/Korean).
+
+Each emulated device in the system that has keyboard and/or keypad inputs is
+listed on the menu, allowing keyboard/keypad inputs to be enabled or disabled
+for individual devices. By default, keyboard/keypad inputs are enabled for the
+first device with keyboard inputs (if any), and for all other devices that have
+keypad inputs but no keyboard inputs. The enabled keyboard/keypad inputs are
+automatically saved to the configuration file for the system when the emulation
+session ends.
+
+
+.. _menus-inputdevices:
+
+Input Devices menu
+------------------
+
+The Input Devices menu lists input devices recognised by MAME and enabled with
+your current settings. Recognised input devices depend on the
+:ref:`keyboardprovider <mame-commandline-keyboardprovider>`, :ref:`mouseprovider
+<mame-commandline-mouseprovider>`, :ref:`lightgunprovider
+<mame-commandline-lightgunprovider>` and :ref:`joystickprovider
+<mame-commandline-joystickprovider>` options. Classes of input devices can be
+enabled or disabled using the :ref:`mouse <mame-commandline-nomouse>`,
+:ref:`lightgun <mame-commandline-nolightgun>` and :ref:`joystick
+<mame-commandline-nojoystick>` options. You can reach the Input Devices menu by
+selecting **Input Devices** from the :ref:`Input Settings menu
+<menus-inputopts>` or the General Settings menu.
-[todo: This needs SERIOUS expansion. Waiting on answer to a few questions..]
+Input devices are grouped by device class (for example keyboards or light guns).
+You can move between device classes using the **Next Group** and **Previous
+Group** keys or buttons. For each device, the device number (within its class)
+is shown on the left, and the name is shown on the right.
+Select a device to show the supported controls for the device. The name of
+each control is displayed on the left and its current state is shown on the
+right. When an analog axis control is highlighted, its state is also shown in
+graphical form below the menu. Digital control states are either zero
+(inactive) or one (active). Analog axis input states range from -65,536 to
+65,536 with the neutral position at zero. You can also select **Copy Device
+ID** to copy the device’s ID to the clipboard. This is useful for setting up
+:ref:`stable controller IDs <devicemap>` in :ref:`controller configuration files
+<ctrlrcfg>`.
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst
index 1956ca939cd..60bb55618a2 100644
--- a/docs/source/usingmame/ui.rst
+++ b/docs/source/usingmame/ui.rst
@@ -11,7 +11,7 @@ MAME’s User Interface
Introduction
------------
-MAME provides a simple user interface for selecting a system and software to
+MAME provides a simple user interface for selecting the system and software to
run and changing settings while running an emulated system. MAME’s user
interface is designed to be usable with a keyboard, game controller, or pointing
device, but will require a keyboard for initial configuration.
@@ -20,13 +20,13 @@ The default settings for the most important controls to know when running an
emulated system, and the settings they correspond to in case you want to change
them, are as follows:
-Scroll Lock, or Forward Delete on macOS (UI Toggle)
+Scroll Lock, or Forward Delete on macOS (Toggle UI Controls)
For emulated systems with keyboard inputs, enable or disable UI controls.
(MAME starts with UI controls disabled for systems with keyboard inputs
unless the :ref:`ui_active option <mame-commandline-uiactive>` is on.)
-Tab (Config Menu)
+Tab (Show/Hide Menu)
Show or hide the menu during emulation.
-Escape (UI Cancel)
+Escape (UI Back and UI Cancel)
Return to the system selection menu, or exit if MAME was started with a
system specified (from the command line or using an
:ref:`external front-end <frontends>`).
@@ -60,10 +60,11 @@ Return/Enter keypad Enter (UI Select)
Select the highlighted menu item.
Forward Delete, or Fn+Delete on some compact keyboards (UI Clear)
Clear setting or reset to default value.
-Escape (UI Cancel)
+Escape (UI Back and UI Cancel)
Clear the search if searching the menu, otherwise close the menu, returning
- to the previous menu, or returning to the emulated machine for the main menu
- (there’s usually an item at the bottom of the menu for the same purpose).
+ to the previous menu, or returning to the emulated system in the case of the
+ main menu (there’s usually an item at the bottom of the menu for the same
+ purpose).
Home (UI Home)
Highlight the first menu item and scroll to the top of the menu.
End (UI End)
@@ -91,14 +92,24 @@ most important UI controls have joystick assignments by default:
* Move the first joystick left or right in the X axis to adjust settings.
* Press the first button on the first joystick to select the highlighted menu
item.
+* If the first joystick has at least three buttons, press the second button on
+ the first joystick to close the menu, returning to the previous menu, or
+ returning to the emulated system in the case of the main menu (there’s usually
+ an item at the bottom of the menu for the same purpose).
+
+For gamepad-style controllers, the left analog thumb stick and directional pad
+usually control UI navigation. Depending on the controller, the right analog
+thumb stick, triggers and additional buttons may automatically be assigned to UI
+inputs. Check the **User Interface** input assignments menu to see how controls
+are assigned.
If you want to be able to use MAME with a game controller without needing a
keyboard, you’ll need to assign joystick buttons (or combinations of buttons) to
these controls as well:
-* **Config Menu** to show or dismiss the menu during emulation
-* **UI Cancel** to close menus, return to the system selection menu, or exit
- MAME
+* **Show/Hide Menu** to show or hide the menu during emulation
+* **UI Back** to close menus
+* **UI Cancel** to return to the system selection menu or exit MAME
* **UI Clear** isn’t essential for basic emulation, but it’s used to clear or
reset some settings to defaults
* **UI Home**, **UI End**, **UI Page Up**, **UI Page Down**, **UI Previous
@@ -133,8 +144,8 @@ pointing device:
* Click toolbar items to select them, or hover over them to see a description.
If you have enough additional mouse buttons, you may want to assign button
-combinations to the **Config Menu**, **Pause** and/or **UI Cancel** inputs to
-make it possible to use MAME without a keyboard.
+combinations to the **Show/Hide Menu**, **Pause**, **UI Back** and/or
+**UI Cancel** inputs to make it possible to use MAME without a keyboard.
.. _ui-inptcfg:
@@ -145,26 +156,31 @@ Configuring inputs
MAME needs a flexible input system to support the control schemes of the vast
array of systems it emulates. In MAME, inputs that only have two distinct
states, on and off or active and inactive, are called *digital inputs*, and all
-other inputs are called *analog inputs*, even if this is not strictly true.
+other inputs are called *analog inputs*, even if this is not strictly true (for
+example multi-position switches are called analog inputs in MAME).
To assign MAME’s user interface controls or the default inputs for all systems,
-select **Input (general)** from the main menu during emulation, or select
-**Configure Options** from the system selection menu and then select **General
-Inputs**. From there, select a category.
-
-To assign inputs for the currently running machine, select **Input (this
-Machine)** from the main menu during emulation. Inputs are grouped by device
-and sorted by type. You can move between devices with the next group and
-previous group keys/buttons (**[** and **]** on the keyboard by default).
+select **Input Settings** from the main menu during emulation and then select
+**Input Assignments (general)** from the Input Settings menu, or select
+**General Settings** from the system selection menu and then select **Input
+Assignments** from the General Settings menu. From there, select a category.
+
+To assign inputs for the currently running system, select **Input Settings**
+from the main menu during emulation and then select **Input Assignments (this
+system)** from the Input Settings menu. Inputs are grouped by device and sorted
+by type. You can move between devices with the next group and previous group
+keys/buttons (opening/closing brackets **[** and **]** on the keyboard by
+default).
The input assignment menus show the name of the emulated input or user interface
-control on the left, and the input (or combination of inputs) assigned to it on
-the right.
+control on the left, and the controls (or combination of controls) assigned to
+it on the right.
To adjust the sensitivity, auto-centre speed and inversion settings, or to see
-how emulated analog controls react to your inputs, select **Analog Controls**
-from the main menu during emulation. (This item only appears on the main menu
-for systems with analog controls.)
+how emulated analog controls react to your inputs, select **Input Settings**
+from the main menu during emulation, and then select **Analog Input
+Adjustments** from the Input Settings Menu (this item only appears on the Input
+Settings menu for systems with analog controls).
.. _ui-inptcfg-digital:
@@ -173,7 +189,7 @@ Digital input settings
~~~~~~~~~~~~~~~~~~~~~~
Each emulated digital input has a single assignment setting. For flexibility,
-MAME can combine host inputs (keys, buttons and joystick axes) using logical
+MAME can combine controls (keys, buttons and joystick axes) using logical
**and**, **not** and **or** operations. This is best illustrated with some
examples:
@@ -195,11 +211,12 @@ Kbd P Kbd Shift or Kbd P Kbd Right Shift
(In technical terms, MAME uses Boolean sum of products logic to combine inputs.)
When a digital input setting is highlighted, the prompt below the menu shows
-whether selecting it will set the assignment or append an **or** operation to
-it. Press **UI Left/Right** before selecting the setting to switch between
-setting or appending an **or** operation. Press **UI Clear** (**Delete** or
-**Forward Delete** by default) to clear the setting or restore the default
-assignment.
+whether selecting it will replace the current assignment or append an **or**
+operation to it. Press **UI Left/Right** before selecting the setting to switch
+between replacing the assignment or appending an **or** operation to it. Press
+**UI Clear** (**Delete** or **Forward Delete** by default) to clear the
+highlighted setting, or restore the default assignment if it is currently
+cleared.
When you select a digital input setting, MAME will wait for you to enter an
input or a combination of inputs for a logical **and** operation:
@@ -209,10 +226,7 @@ input or a combination of inputs for a logical **and** operation:
* Press a key or button or move an analog control twice to add a **not** item to
the **and** operation. Pressing the same key or button or moving the same
analog control additional times toggles the **not** on and off.
-* Pressing **UI Cancel** (**Escape** by default) *before* activating any other
- controls clears the setting or restores the default assignment.
-* Pressing **UI Cancel** *after* activating another control leaves the setting
- unchanged.
+* Press **UI Cancel** (**Escape** by default) to leave the setting unchanged.
* The new setting is shown below the menu. Wait one second after activating an
input to accept the new setting.
@@ -242,14 +256,14 @@ Each emulated analog input has three assignment settings:
input. The axis setting uses the name of the input with the suffix “Analog”.
For example the axis setting for the steering wheel in Ridge Racer is called
**Steering Wheel Analog**.
-* Use the *increment setting* assign an input (or combination of inputs) to
+* Use the *increment setting* assign a control (or combination of controls) to
increase the value of the emulated analog input. The increment setting uses
the name of the input with the suffix “Analog Inc”. For example the increment
setting for the steering wheel in Ridge Racer is called **Steering Wheel
Analog Inc**. This is a digital input setting – if an analog axis is
assigned to it, MAME will not increase the emulated input value at a
proportional speed.
-* Use the *decrement setting* assign an input (or combination of inputs) to
+* Use the *decrement setting* assign a control (or combination of controls) to
decrease the value of the emulated analog input. The decrement setting uses
the name of the input with the suffix “Analog Dec”. For example the decrement
setting for the steering wheel in Ridge Racer is called **Steering Wheel
@@ -272,12 +286,12 @@ You can assign one or more analog axes to the axis setting for an emulated
analog input. When multiple axes are assigned to an axis setting, they will be
added together, but absolute position controls will override relative position
controls. For example suppose for Arkanoid you assign the **Dial Analog** axis
-setting to **Mouse X or Joy 1 LSX or Joy 1 RSX** on a mouse Xbox-style
+setting to **Mouse X or Joy 1 LSX or Joy 1 RSX** on a mouse and Xbox-style
controller. You will be able to control the paddle with the mouse or either
analog stick, but the mouse will only take effect if both analog sticks are in
the neutral position (centred) on the X axis. If either analog stick is *not*
centred on the X axis, the mouse will have no effect, because a mouse is a
-relative position control while a joystick is an absolute position control.
+relative position control while joysticks are absolute position controls.
For absolute position controls like joysticks and pedals, MAME allows you to
assign either the full range of an axis or the range on one side of the neutral
@@ -311,10 +325,10 @@ Mouse X or Joy 1 LT or Joy 1 RT Reverse
direction to the left trigger.
Joy 1 LB Joy 1 LSX
Use horizontal movement of the left analog stick to control the emulated
- input, but *only* while holding the left shoulder button. If the right
+ input, but *only* while holding the left shoulder button. If the left
shoulder button is released while the left analog stick is not centred
- horizontally, the emulated input will hold its value until the right
- shoulder button is pressed again (a “sticky” control).
+ horizontally, the emulated input will hold its value until the left shoulder
+ button is pressed again (a “sticky” control).
not Joy 1 RB Joy 1 RSX or Joy 1 RB Joy 1 RSX Reverse
Use horizontal movement of the right analog stick to control the emulated
input, but invert the control if the right shoulder button is held.
@@ -333,23 +347,21 @@ When you select an axis setting, MAME will wait for you to enter an input:
direction of the control on or off.
* When appending to a setting, move an analog control other than the last
assigned control or press a key or button to add an **or** operation.
-* Pressing **UI Cancel** (**Escape** by default) *before* activating any other
- controls clears the setting or restores the default assignment.
-* Pressing **UI Cancel** *after* activating another control leaves the setting
- unchanged.
+* Pressing **UI Cancel** (**Escape** by default) leaves the setting unchanged.
* The new setting is shown below the menu. Wait one second after moving an
analog control to accept the new setting.
To adjust sensitivity, auto-centring speed and inversion settings for emulated
-analog inputs, or to see how they respond to your settings, select **Analog
-Controls** from the main menu during emulation. Settings for emulated analog
+analog inputs, or to see how they respond to controls with your settings, select
+**Input Settings** from the main menu during emulation, and then select **Analog
+Input Adjustments** from the Input Settings Menu. Settings for emulated analog
inputs are grouped by device and sorted by type. You can move between devices
-with the next group and previous group keys/buttons (**[** and **]** on the
-keyboard by default). The state of the emulated analog inputs is shown below
-the menu, and reacts in real time. Press the **On Screen Display** key or
-button (the backtick/tilde key by default on a US ANSI QWERTY keyboard) to hide
-the menu to make it easier to test without changing settings. Press the same
-key or button to show the menu again.
+with the next group and previous group keys/buttons (opening/closing brackets
+**[** and **]** on the keyboard by default). The state of the emulated analog
+inputs is shown below the menu, and reacts in real time. Press the **On Screen
+Display** key or button (the backtick/tilde key by default on a US ANSI QWERTY
+keyboard) to hide the menu to make it easier to test without changing settings.
+Press the same key or button to show the menu again.
Each emulated input has four settings on the **Analog Controls** menu:
@@ -387,7 +399,7 @@ The system and software selection menus
If you start MAME without specifying a system on the command line, the system
selection menu will be shown (assuming the
:ref:`ui option <mame-commandline-ui>` is set to **cabinet**). The system
-selection menu is also shown if you select **Select New Machine** from the main
+selection menu is also shown if you select **Select New System** from the main
menu during emulation. Selecting a system that uses software lists shows the
similar software selection menu.
@@ -407,7 +419,7 @@ The system and software selection menus have the following parts:
* The list of systems or software in the centre. For the system selection menu,
there are configuration options below the list of systems. Clones are shown
with a different text colour (grey by default). You can right-click a system
- name as a shortcut to show the machine configuration options for the system.
+ name as a shortcut to show the System Settings menu for the system.
Systems or software items are sorted by full name or description, keeping
clones immediately below their parents. This may appear confusing if your
@@ -454,8 +466,8 @@ Navigation controls
In addition to the usual :ref:`menu navigation controls <ui-menus>`, the system
and software selection menus have additional configurable controls for
navigating the multi-pane layout, and providing alternatives to toolbar buttons
-if you don’t want to use a pointing device. The default additional controls (on
-a US ANSI QWERTY keyboard), and the settings they correspond to, are:
+if you don’t want to use a pointing device. The default additional controls
+(with a US ANSI QWERTY keyboard), and the settings they correspond to, are:
Tab (UI Focus Next)
Move focus to the next area. The order is system/software list,
@@ -488,7 +500,7 @@ The simple system selection menu
--------------------------------
If you start MAME without specifying a system on the command line (or choose
-**Select New Machine** from the main menu during emulation) with the
+**Select New System** from the main menu during emulation) with the
:ref:`ui option <mame-commandline-ui>` set to **simple**, the simple system
selection menu will be shown. The simple system selection menu shows fifteen
randomly selected systems that have ROM sets present in your configured
diff --git a/docs/source/usingmame/usingmame.rst b/docs/source/usingmame/usingmame.rst
index f808199cb52..4fa014fe3da 100644
--- a/docs/source/usingmame/usingmame.rst
+++ b/docs/source/usingmame/usingmame.rst
@@ -3,7 +3,7 @@ Using MAME
If you want to dive right in and skip the command line, there's a nice graphical
way to use MAME without the need to download and set up a front end. Simply
-start MAME with no parameters, by doubleclicking the **mame.exe** file or
+start MAME with no parameters, by double-clicking the **mame.exe** file or
running it directly from the command line. If you're looking to harness the
full power of MAME, keep reading further.
@@ -14,7 +14,7 @@ to missing glyphs.
If you are a new MAME user, you could find this emulator a bit complex at
first. Let's take a moment to talk about software lists, as they can simplify
matters quite a bit. If the content you are trying to play is a documented
-entry on one of the MAME sotware lists, starting the content is as easy as
+entry on one of the MAME software lists, starting the content is as easy as
**mame.exe** *<system>* *<software>*
@@ -79,18 +79,19 @@ gives a basic summary of command line options for MAME, as explained above.
**mame.exe -showusage**
gives you the (quite long) list of available command line options for MAME.
-The main options are described, in the :ref:`universal-command-line` section of
-this manual.
+The main options are described, in the :ref:`mame-commandline-universal` section
+of this manual.
**mame.exe -showconfig**
gives you a (quite long) list of available configuration options for MAME.
-These optons can always be modified at command line, or by editing them in
+These options can always be modified at command line, or by editing them in
mame.ini which is the main configuration file for MAME. You can find a
-description of some configuration options in the :ref:`universal-command-line`
-section of the manual (in most cases, each configuration option has a
-corresponding command line option to configure and modify it).
+description of some configuration options in the
+:ref:`mame-commandline-universal` section of the manual (in most cases, each
+configuration option has a corresponding command line option to configure and
+modify it).
**mame.exe -createconfig**
diff --git a/docs/source/whatis.rst b/docs/source/whatis.rst
index 6f6f772e480..e6e93382ea3 100644
--- a/docs/source/whatis.rst
+++ b/docs/source/whatis.rst
@@ -19,7 +19,7 @@ that were its initial focus.
|
| **MAME®**
-| **Copyright © 1997-2021 Nicola Salmoria and the MAME team**
+| **Copyright © 1997-2024 MAMEdev and contributors**
| **MAME is a registered trademark of Gregory Ember**
|
@@ -77,7 +77,7 @@ your derivative work. In general, this means you must request
permission, which requires that you follow the guidelines above.
The version number of any derivative work should reflect the version
-number of the MAME release from which it was was derived.
+number of the MAME release from which it was derived.
V. Official Contact Information
diff --git a/docs/swlist/n64jp.csv b/docs/swlist/n64jp.csv
deleted file mode 100644
index 03be4c9c989..00000000000
--- a/docs/swlist/n64jp.csv
+++ /dev/null
@@ -1,236 +0,0 @@
-ZIP Name,Last MAME version tested,Game Flags,Additional Notes
-1080snowu,,1,
-64oozum2,,0,
-fzeroxj,,1,
-hiryuken,,1,
-jikkjlea,,1,Screen image looks too dark. Missing fog?
-starfoxj,,0,
-sm64j,,0,
-yoshistoj,,0,
-007goldnj,,0,
-64dhtama,,0,
-64hana,,0,
-64oozumo,,0,
-64trumpc,,0,
-aerogaugjd,,0,
-aerogaugj,,0,
-aishogi3,,0,
-airboardj,,0,
-akumajo,,0,
-akumajog,,0,
-bakubomb,,0,
-bakubom2,,0,
-bangaioh,,0,
-bakushou,,0,
-banjokazj,,0,
-banjotooj,,0,
-bassrush,,0,
-beetlearj,,0,
-biohaz2,,0,
-blastdoz,,0,
-bokujom2,,0,
-bokujom2a,,0,
-bokujom2b,,0,
-bombmnae,,0,
-bombheroj,,0,
-buckbumbj,,0,
-chtwistj,,0,
-chtwist2j,,0,
-choroq,,0,
-choroq2,,0,
-cknight,,0,
-cknight2,,0,
-snobokd2j,,0,
-citytour,,0,
-custrobo,,0,
-custrob2,,0,
-ddrdisny,,0,
-dendeg64,,1,
-dstall64p,,0,
-dstall64,,0,
-dezaemon,,1,Mouse doesn't work?
-dkracingj,,0,
-dk64j,,0,
-doom64j,,3,Black screen after initial disclaimer.
-doraemon,,0,
-doraemn2,,0,
-doraemn3,,0,
-doubutsu,,0,
-dualheroj,,0,
-eikousa,,0,
-eltale,,1,(Barely tested)
-excitbikj,,0,
-extremegj,,0,
-extremg2j,,0,
-f1wgpj,,0,
-famista,,0,
-fifa98j,,0,
-fightcup,,1,
-furaish2,,1,
-gaspj,,0,
-ggoemddd,,0,
-ggoemneo,,0,
-olymp2k,,0,
-gauntlegj,,0,
-gettlove,,0,
-goemnsug,,0,
-hamstmon,,0,
-harukana,,3,Has mirrored gfx. eventually leads to a RSP assert
-heiwapw,,0,
-hexenj,,3,No 3d graphics including enemies.
-kirby64j,,3,Black screen at Level 1
-kirby64j1,,0,
-kirby64j2,,0,
-kirby64j3,,0,
-humangp,,0,
-hybridhj,,2,Asserts if throttled. garbled text
-naganoj,,0,
-ideyosuk,,3,Black screen. access 0x1ff00000 area (debug ROM?)
-iggyreckj,,0,
-itoishig,,0,
-jldyna64,,0,
-jleleven,,0,
-jllive64,,0,
-jltactic,,0,
-jltactic1,,0,
-jangsim,,0,
-jikkg1,,0,
-jikkg1a,,0,
-jikkjl99,,0,
-jikkjl99a,,0,
-powyak2k,,0,
-powyak2ka,,0,
-powyak4,,0,
-powyak4a,,0,
-powyak5,,0,
-powyak5a,,0,
-powyak5b,,0,
-powyak6,,0,
-powyak6a,,0,
-powyak6b,,0,
-powyk2k1,,0,
-powyk2k1a,,0,
-jikksc98,,0,
-jikksc98a,,0,
-jikksc98b,,0,
-jikkscr3,,0,
-turokj,,0,
-jinsei64,,0,
-daikatanj,,0,
-fcmaniax,,0,
-kinghill,,0,
-kiratt64,,0,
-knifeedgj,,0,
-lastleg,,0,
-letsmash,,0,
-ldrun3dj,,0,
-mtetriscj,,0,
-mahjong,,0,
-mjhoroki,,0,
-mjmaster,,0,
-marioglfj,,0,
-marioglfj1,,0,
-mariokrtj,,0,
-mariokrtj1,,0,
-mariopho,,0,
-marioparj,,0,
-mariopr2j,,0,
-mariopr3j,,0,
-mariosto,,0,
-mariotenj,,0,
-mickspedj,,0,
-moritash,,0,
-mrcj,,0,
-nbazon98j,,0,
-nbazone2,,0,
-evangeln,,3,Black screen.
-nintama,,0,
-smashbroj,,0,
-nustsu64,,0,
-nustsu64a,,0,
-nusts64s,,0,
-ogrebatlj,,2,Flipped hand icon.
-olymph98j,,0,
-onegai,,0,
-pachinko,,0,
-parlrpro,,0,
-pdultram,,0,
-pdarkj,,0,
-pikachu,,0,
-pilotwinj,,0,
-pokesnapj,,0,
-pokestdj,,0,
-pokestd2j,,0,
-pokestdk,,0,
-pleague,,0,
-mjkiwame,,1,
-mjkiwame1,,0,
-mjtsuwa,,0,
-puyopuy4,,1,(Not tested all features)
-puyopsun,,1,
-pbobble,,0,
-rakugaj,,0,
-rally99,,0,
-robotpon,,3,Heavy gfx artifacts. eventually leads to black screen
-rockmand,,0,
-saikyou,,0,
-sdhiryu,,0,
-shadgatej,,0,
-sprowres,,0,
-sprowrs2,,0,
-simcit2k,,0,
-snobokidj,,0,
-snowsped,,0,
-sonicwing,,0,
-spacedyn,,0,
-ssiliconj,,0,
-starsoldj,,0,
-startwin,,0,
-swshutsu,,0,
-swteiko,,0,
-swracerj,,0,
-sbdaman,,0,
-sbowlingj,,0,
-sm64jse,,0,
-srobospi,mame0163-159-gf2891c8,1,Wrong foreground text during battle
-srobot64,,1,Minor gfx artifacts with some elements (stripped textures)
-ssrace64,,0,
-puzldama,,0,
-tetris64,,3,White screen
-toonpan,,0,
-tghj,,0,
-tgoverdrj,,0,
-tgrallyj,,0,
-tgrally2j,,0,
-beastwarj,,0,
-tsumibat,,0,
-utchan,,0,
-vrally99j,,0,
-vkiller,,0,
-vprowrs2,,0,
-vprowres,,0,
-waveracej,,0,
-waveracej1,,0,
-waveracej2,,0,
-wg3dhj,,0,
-wetrixj,,0,
-wildchop,,0,
-winbackj,,0,
-winbackj1,,0,
-wprojj2,,0,
-wmania2kj,,0,
-yakouch2,,0,
-yukeyuke,,0,
-zeldamajj,,0,
-zeldamajj1,,0,
-zeldaootj,,0,
-zeldaootj1,,0,
-zeldaootj2,,0,
-zool,,0,
-zeldaootmqj,,0,
-zeldaootj3,,0,
-zeldamajj2,,0,
-64gbchk,,2,Doesn't seem to do anything useful.
-photovw,,0,
-u64demo,,0,
-dlpnctrl,,2,Doesn't seem to do anything.
diff --git a/docs/swlist/readme.txt b/docs/swlist/readme.txt
deleted file mode 100644
index 9002b35bac7..00000000000
--- a/docs/swlist/readme.txt
+++ /dev/null
@@ -1,10 +0,0 @@
-Compatibility lists for console/computers in MAME, in CSV format.
-
-File format for a single line is:
-<zipname>;<rev_number or MAME version>;<game_flags>;<additional_notes>\n
-
-<game_flags> are in integer format, these are:
-0 - Not Tested
-1 - Working
-2 - Partial
-3 - Not Working
diff --git a/docs/swlist/x1_flop.csv b/docs/swlist/x1_flop.csv
deleted file mode 100644
index c35cbb05eaa..00000000000
--- a/docs/swlist/x1_flop.csv
+++ /dev/null
@@ -1,375 +0,0 @@
-ZIP Name,Last MAME version tested,Game Flags,Additional Notes
-177,,0,
-1942,,0,
-4thunit,,0,
-aressha,,0,
-advfant,,0,
-advfantd,,0,
-alpha,,0,
-amtruck,,0,
-aokiooka,,0,
-arcus,,0,
-argo,,0,
-arion,,0,
-aspicsp,,0,
-aztec,,0,
-batlcity,,0,
-blckonyx,,0,
-bokensha,,0,
-bosco,,0,
-bbreaker,,0,
-carmine,,0,
-chackn,,0,
-cprowsp,,0,
-crimson,,0,
-crimsona,,0,
-blassty,,0,
-dside,,0,
-daisenr,,0,
-daisenra,,0,
-daiva,,0,
-daivaa,,0,
-dezeniwl,,0,
-diablo,,0,
-megamit,,0,
-megamitb,,0,
-megamita,,0,
-dbuster,,0,
-euphory,,0,
-exoa2,,0,
-fantsian,,0,
-murdclub,,0,
-fzone,,0,
-fzonea,,0,
-gaiamons,,0,
-gaiflame,,0,
-galforce,,0,
-gambler,,1,
-gambler2,,1,
-gamma5,,0,
-gandhara,,0,
-goonies,,0,
-gradius,,0,
-gradiusa,,0,
-gradiusb,,0,
-gradiusk,,0,
-gruppe,,0,
-hajafuin,,0,
-herzog,,0,
-hokuto,,0,
-hfox,,0,
-hfoxa,,0,
-hfox2,,0,
-hydlide,,0,
-hydlidea,,0,
-hydlide2,,0,
-hydlide2a,,0,
-hydlide2b,,0,
-hydlide3,,0,
-hydlide3a,,0,
-hydlide3b,,0,
-jesus,,0,
-jesusd,,0,
-legkage,,0,
-karuizaw,,0,
-kingkngt,,0,
-powermj,,0,
-kugyokud,,0,
-kugyokuda,,0,
-lagrange,,0,
-laplace,,0,
-lasvegas,,0,
-lastarmg,,0,
-ldrun,,0,
-lostpow,,0,
-lunacity,,0,
-lupin,,0,
-luxsor,,0,
-mule,,0,
-mulea,,0,
-mjkyojs,,0,
-maidum,,0,
-maiduma,,0,
-mikkoku,,0,
-mikkokuk,,0,
-majavent,,0,
-makaifuk,,0,
-manilove,,0,
-manhatrq,,0,
-mappy,,0,
-mightmag,,0,
-mrproy88,,0,
-mugen2,,0,
-valis,,0,
-nobunaga,,0,
-nobuseng,,0,
-nobuzenk,,0,
-ojibinbm,,0,
-ojibinbma,,0,
-ojibinbmb,,0,
-orbit3,,0,
-outroyd,,0,
-outroyda,,0,
-phantas,,0,
-profmj,,0,
-psyoblad,,0,
-relics,,0,
-reviver,,0,
-revolty2,,0,
-riglas,,0,
-robowres,,0,
-romancia,,0,
-romanciaa,,0,
-sangoku2,,0,
-sangoku2a,,0,
-screamer,,0,
-seijoden,,0,
-seijodena,,0,
-seijopan,,0,
-seijopana,,0,
-shanghai,,0,
-shanghaia,,0,
-skugyokd,,0,
-shintake,,0,
-sofia,,0,
-silvergh,,0,
-sorcer,,0,
-sorcera,,0,
-gilgasor,,0,
-sorcerexp4,,0,
-sorcerexp,,0,
-sorcerexp2,,0,
-sorcerexp3,,0,
-sorcersel1,,0,
-sorcersel2,,0,
-sorcersel3,,0,
-sorcersel4,,0,
-sorcersel5,,0,
-sorcerutil,,0,
-sorcerutila,,0,
-sorcermd,,0,
-sharrier,,0,
-sharriera,,0,
-spchange,,0,
-spyvsspy,,0,
-scruiser,,0,
-suikoden,,0,
-slaydock,,0,
-slaydocka,,0,
-slaydocm,,0,
-smbsp,,0,
-smbspa,,0,
-asteka2,,0,
-tankent2,,0,
-tetris,,0,
-thexder,,0,
-thndrbal,,0,
-timepara,,0,
-tokyo,,0,
-tokyons,,0,
-topzip,,0,
-druaga,,0,
-toypop,,0,
-triton,,0,
-trumpkyo,,0,
-ultima4,,0,
-ultima4a,,0,
-uootoy,,0,
-victnine,,0,
-wibarm,,0,
-wibarma,,0,
-will,,0,
-wingman,,0,
-wingman2,,0,
-wizardry,,0,
-wizardr2,,0,
-wizardr4,,0,
-woodypoc,,0,
-woodypoca,,0,
-woodypocb,,0,
-worldgl2,,0,
-xanadu,,0,
-xanadu2,,0,
-ys,,0,
-ys2,,0,
-zeliard,,0,
-algarna,,0,
-bastard,,0,
-mars,,0,
-marsa,,0,
-marsb,,0,
-darkstrm,,0,
-dezeni,,0,
-dezenia,,0,
-dialide,,0,
-dialidea,,0,
-dione,,0,
-dslayer,,0,
-fairires,,0,
-5sdream,,0,
-frontlin,,0,
-galaga,,0,
-galaxian,,0,
-gatlabyr,,0,
-hyprol84,,0,
-irohanih,,0,
-issural,,0,
-knither,,0,
-labyrint,,0,
-lizard,,0,
-lovechas,,0,
-lovechasa,,0,
-marvels,,0,
-marvelsa,,0,
-marvelsb,,0,
-mikichan,,0,
-newtype,,0,
-newtypea,,0,
-punchbal,,0,
-poplemon,,0,
-portopia,,0,
-rwings,,0,
-saziri,,0,
-saziria,,0,
-state,,0,
-bshashsc,,0,
-tforce,,0,
-vip,,0,
-vipa,,0,
-vipb,,0,
-vipc,,0,
-vipd,,0,
-wizardr3,,0,
-xevious,,0,
-xeviousa,,0,
-ys3,,0,
-zeta5,,0,
-pstar2,,0,
-dokkin,,0,
-triviaq,,0,
-namcovgm,,0,
-kudokika,,0,
-sayaka,,0,
-moritash,,0,
-emono1,,0,
-tenshit,,0,
-albatros,,0,
-albatrosx,,0,
-albatrosjc,,0,
-albatrosv,,0,
-albatrosw,,0,
-arctic,,0,
-asteka,,0,
-balonfgt,,0,
-btanuki,,0,
-bgorilla,,0,
-byaku,,0,
-casablan,,0,
-csoldier,,0,
-dome,,0,
-donjuan,,0,
-elthlead,,0,
-golques,,0,
-gyrodine,,0,
-afterdrk,,0,
-hayato,,0,
-hotdog,,0,
-ishinara,,0,
-jotunn,,0,
-kaleidos,,0,
-kohakuir,,0,
-laptick,,0,
-lastwar,,0,
-legend,,0,
-madelein,,0,
-melonsod,,0,
-nukenind,,0,
-penguinw,,0,
-produce,,0,
-rebirth,,0,
-srambo,,0,
-sirius1,,0,
-sangoku,,0,
-satsujin,,0,
-kissmurd,,0,
-sf3dopv,,0,
-startrap,,0,
-uruseiya,,0,
-zgundam,,0,
-eggyd,,0,
-yaksadem,,0,
-x1demo,,0,
-x1cdemo,,0,
-x1demoa,,0,
-x1fdemo,,0,
-x1gdemo,,0,
-x1gdemoa,,0,
-x1tdemo,,0,
-srdemo,,0,
-hubasic1,,0,
-hubasic2,,0,
-turbobas,,0,
-turbobasa,,0,
-turbzbas,,0,
-tapbas,,0,
-dbbasic,,0,
-cpm22,,0,
-swordos,,0,
-swordosa,,0,
-jodanos,,0,
-jodanosa,,0,
-xdos,,0,
-extrahyp,,0,
-extrahypa,,0,
-hyperdsk,,0,
-jetterm,,0,
-filemast,,0,
-tap2dsk,,0,
-graphtol,,0,
-newfmdrv,,0,
-davinci,,0,
-expertx1,,0,
-dskanlzr,,0,
-fmdata,,0,
-unk_fl1,,0,
-blank,,0,
-basic1,,0,
-basic2,,0,
-game6,,0,
-game01,,0,
-game02,,0,
-game03,,0,
-game04,,0,
-game05,,0,
-game06,,0,
-game07,,0,
-game08,,0,
-game09,,0,
-game10,,0,
-game11,,0,
-game12,,0,
-game13,,0,
-game14,,0,
-game15,,0,
-game16,,0,
-game17,,0,
-game18,,0,
-game19,,0,
-game20,,0,
-x1gmpk1,,0,
-x1gmpk2,,0,
-x1gmpk3,,0,
-casgame1,,0,
-casgame2,,0,
-gamee,,0,
-gameea,,0,
-gamepck1,,0,
-gamepck2,,0,
-gamepck3,,0,
-gamepck4,,0,
-gamepk1,,0,
-gamepk2,,0,
-jodanpk1,,0,
-mbm,,0,
-uedabgm1,,0,
-uedabgm2,,0,
diff --git a/docs/swlist/x68k_flop.csv b/docs/swlist/x68k_flop.csv
deleted file mode 100644
index 3130baf89c3..00000000000
--- a/docs/swlist/x68k_flop.csv
+++ /dev/null
@@ -1,1784 +0,0 @@
-177;;1;
-2069ad;;1;
-3takun;;0;
-38mankk;;1;
-4thunit;;0;
-4thunit2;;0;
-dualtarg;;0;
-zero;;0;
-dagain;;0;
-aressha2;;0;
-aressh2o;;0;
-aressha3;;0;
-aressha3mc;;0;
-aressha3mc1;;0;
-aressha3log;;0;
-aressha3oms;;0;
-aburner2;;0;
-acombat2;;0;
-airmanag;;0;
-ajax;;0;
-akiko;;0;
-akumajo;;1;
-akumajod;;0;
-alfaim;;0;
-algarna;;0;
-alice;;0;
-alice2;;0;
-aliensyn;;1;
-abart1;;0;
-abart2;;0;
-abart3;;0;
-abart4;;0;
-alshark;;0;
-ambiv;;0;
-animjv3;;0;
-animjv3d;;0;
-animjv3da;;0;
-animjv3t;;0;
-genchohi;;0;
-genghis;;0;
-aquales;;0;
-arcshu;;0;
-arcusod;;0;
-arcus;;0;
-arcus2;;0;
-argos;;0;
-arknoid2;;0;
-votoms;;0;
-votomsd;;0;
-artemis;;0;
-atomrobo;;0;
-asuka120;;0;
-chelnov;;0;
-ayumimon;;0;
-baraduke;;0;
-barufuku;;0;
-btlchess;;0;
-btech;;0;
-beast;;0;
-beast2;;0;
-bellaven;;0;
-bellavn2;;0;
-peachang;;0;
-peachangd;;0;
-birdywld;;0;
-cgdai1;;0;
-cgdai2;;0;
-bgfxd1;;0;
-bgfxd2;;0;
-bgfxd3;;0;
-bgfxd4;;0;
-bgfxd5;;0;
-bgfxd6;;0;
-bshashms;;0;
-blitzkrg;;0;
-blodia;;0;
-bombermn;;0;
-bnzabros;;0;
-bonnoyob;;0;
-bonnoyo2;;0;
-bonnoyo3;;0;
-bosco;;0;
-branmrkr;;0;
-bretonne;;0;
-bretsce1;;0;
-bretsce2;;0;
-bretsce3;;0;
-bretscen;;0;
-bublbobl;;0;
-butasan;;0;
-byakuya;;0;
-cal;;0;
-cal2;;0;
-cameltry;;0;
-cancanb;;0;
-cancanbs;;0;
-cancanbp;;0;
-cancanbe;;0;
-carat;;0;
-caroll;;0;
-casablan;;0;
-castles;;0;
-catsp1;;0;
-chaossb;;0;
-chasehq;;0;
-chinmoku;;0;
-choubang;;0;
-choujin;;0;
-choujind;;0;
-chukatai;;0;
-cinderel;;0;
-cockpit;;0;
-codezero;;1;wrong scrolling effect for title screen, player explosion looks bad
-collectd;;0;
-columns;;0;
-cntinent;;0;
-cospsyco;;0;
-cotton;;0;
-cclimber;;0;
-crescent;;0;
-cuarto;;0;
-cuberunr;;0;
-cybrbloc;;0;
-cybrcore;;0;
-dodokid1;;0;
-dodokid2;;0;
-dodokid3;;0;
-dodokid4;;0;
-dodokid5;;0;
-dreturn;;0;
-daikokai;;0;
-daimakai;;2;CRT Mode 2 causes offsetted sprites
-daisenr2;;0;
-daisenr3;;0;
-daisenr3d;;0;
-daisenr3mc1;;0;
-daisenr3mc2;;0;
-daikaint;;0;
-daikains;;0;
-dalk;;0;
-darwin;;0;
-dashyar;;0;
-kyoko;;0;
-deja;;0;
-deadbrn;;0;
-deathbra;;0;
-dbringer;;0;
-deflektr;;1;
-cybwrite;;0;
-cybwrites1;;0;
-dtwinbee;;0;
-dtwinbeed;;0;
-diebahn;;0;
-digdug;;0;
-dinoland;;0;
-dios;;0;
-dokicard;;0;
-dome;;0;
-albion;;0;
-dor;;0;
-dor2;;0;
-dor3;;0;
-dorse93;;0;
-dorsesak;;0;
-dbleagle;;0;
-dokyusei;;0;
-downtown;;0;
-drstop;;0;
-drachaku;;0;
-dragon;;0;
-dbuster;;0;
-drgcityx;;0;
-drageyes;;0;
-dknight;;0;
-dknight2;;0;
-dknight3;;0;
-dknight4;;0;
-dslayed;;0;
-dspirit;;0;
-drgnwars;;0;
-drgstrik;;0;
-drakkhen;;0;
-dngmster;;0;
-dynduke;;0;
-eikan;;0;
-elle;;0;
-emerald;;0;
-emeraldd;;0;
-emperor;;0;
-entfuhr;;0;
-etoile;;0;
-eurosens;;0;
-evilstn;;0;
-evilstnk;;0;
-excthour;;0;
-exon;;0;
-exterlin;;0;
-f15se2;;0;
-flstory;;0;
-fairytk;;0;
-fantzone;;0;
-farside;;0;
-ffight;;0;
-fqueen2;;0;
-flappy2;;0;
-foxy2;;0;
-fruitfld;;0;
-fss;;0;
-fullthrt;;0;
-fushikab;;0;
-nadia;;0;
-nadiamfd;;0;
-futwars;;0;
-fzsenki;;0;
-gr;;0;
-gakubomb;;0;
-galaga88;;0;
-gamejang;;0;
-gammapl;;0;
-garou;;0;
-garou2;;0;
-garousp;;0;
-gaudi;;0;
-gemini;;0;
-genjuki;;0;
-genocide;;0;
-genocid2;;0;
-genocid2d;;0;
-genpei;;0;
-geoseal;;0;
-geoseald;;0;
-gingaed;;0;
-gingaed2;;0;
-ginga2dx;;0;
-gingpow;;0;
-girlpara;;0;
-gizexix;;0;
-gokichi;;0;
-gorakuin;;0;
-gradius;;0;
-gradius2;;0;
-gramcat2;;0;
-granada;;0;
-granadad;;0;
-grandifl;;0;
-grndmast;;0;
-groupx;;0;
-glyeward;;0;
-gunship;;0;
-ayayo;;0;
-ayayo2;;0;
-ayayo3;;0;
-hanayori;;0;
-hanayor2;;0;
-hanahour;;0;
-hanateng;;0;
-haresawa;;0;
-heavynov;;0;
-himihana;;0;
-fshark;;0;
-fsharkd;;0;
-elthlead;;0;
-hoshisun;;0;
-hoshisu2;;0;
-hotelwar;;0;
-hhunt1;;0;
-hhunt2;;0;
-hhunt3;;0;
-hhunt6;;0;
-hhunt11;;0;
-manyrobo;;0;
-hydlide3;;0;
-illumina;;0;
-illcity;;0;
-image;;0;
-imagefig;;0;
-imitatn;;0;
-imperial;;0;
-inindo;;0;
-irohanih;;0;
-ishido;;0;
-ishinara;;0;
-kissmurd;;0;
-murdcldx;;0;
-manhatrq;;0;
-nicklaus;;0;
-nicklausc1;;0;
-nicklausc2;;0;
-janjaka;;0;
-jane;;0;
-jangou1;;0;
-jangou2;;0;
-janshqst;;0;
-janshqstd;;0;
-jesus2;;0;
-billiard;;0;
-joker;;0;
-joker2;;0;
-joshidol;;0;
-joshua;;0;
-kaerimic;;0;
-kareinar;;0;
-kawaichi;;0;
-keeper;;0;
-kensoson;;0;
-kerakera;;0;
-kibunpas;;0;
-sap2;;0;
-kikoshid;;0;
-kikoshidd;;0;
-kimidake;;0;
-chicago;;0;
-kitahei;;0;
-kiwame;;0;
-klax;;0;
-knghtarm;;0;
-knghtarmd;;0;
-kohakuir;;0;
-powermj2;;0;
-koberenm;;0;
-noriko;;0;
-kouryuuk;;0;
-ku2;;0;
-ku2fr;;0;
-kurukaji;;0;
-kudokika;;0;
-kudokik2;;0;
-ktiger;;0;
-lagoon;;0;
-lammal;;0;
-laplace;;0;
-lasvegas;;0;
-lastarmg;;0;
-lastbat;;0;
-lastbatd;;0;
-leadingc;;0;
-lemmings;;0;
-lenam;;0;
-libbler;;0;
-libido7;;0;
-lifendth;;0;
-lightbac;;0;
-lipsadv;;0;
-lipsadv3;;0;
-lipsadv2;;0;
-lodossfk;;0;
-lodoss;;0;
-lodoss2;;0;
-ldb_x68k;;0;
-looperas;;0;
-loopz;;0;
-lovelyho;;0;
-lua;;0;
-lucyshot;;0;
-madstlkr;;0;
-magshot;;0;
-mjclinic;;0;
-mjfantas;;0;
-mjkyojs;;0;
-mjmaster;;0;
-mjsaikyo;;0;
-mjyuench;;0;
-mahoudai;;0;
-mai;;0;
-mikkokuk;;0;
-majinkyu;;0;
-kumiko;;0;
-manilove;;0;
-marble;;0;
-marchen;;0;
-marchenp;;0;
-marinebs;;0;
-mariridx;;0;
-martlage;;0;
-mastmon2;;0;
-mayumi;;0;
-megalo;;0;
-mercury;;0;
-metaleye;;0;
-metalsig;;0;
-mclown;;0;
-midgarts;;0;
-mightmag;;0;
-milktime;;0;
-mirage;;0;
-misty1;;0;
-misty2;;0;
-misty3;;0;
-misty4;;0;
-misty5;;0;
-misty6;;0;
-misty7;;0;
-gundamco;;0;
-momo;;0;
-mooncrst;;0;
-moonligt;;0;
-mooncrys;;0;
-moritas2;;0;
-motos;;0;
-mrdo;;0;
-valis2;;0;
-valis2d;;0;
-myeyes;;0;
-myeyesa;;0;
-naious;;0;
-namachuk;;0;
-namcovgm;;0;
-nectaris;;0;
-nejishik;;0;
-nejishikd;;0;
-nekdodge;;0;
-neksoccr;;0;
-nemesis;;0;
-nemesisd;;0;
-neurgear;;0;
-n3dgaugu;;0;
-n3dg8lak;;0;
-tnzs;;0;
-nicoll;;0;
-nikoniko;;0;
-noah;;0;
-noblemnd;;0;
-nobubufu;;0;
-nobuhao;;0;
-nobuseng;;0;
-nobuzenk;;0;
-nost1907;;0;
-ohpai;;0;
-okumanch;;0;
-olteus2;;0;
-oedohanj;;0;
-orangeib;;0;
-ougonras;;0;
-overtake;;0;
-pacland;;0;
-pacmania;;0;
-pachinko;;0;
-parodius;;0;
-parodiusd;;0;
-purplcat;;0;
-purplct3;;0;
-purupuru;;0;
-phalanx;;0;
-phantas3;;0;
-phantas4;;0;
-pias;;0;
-pbpinbal;;0;
-pinky1;;0;
-pinkypon;;0;
-pinkypn2;;0;
-pinkypn3;;0;
-pipedrem;;0;
-pipyan;;0;
-pitapat;;0;
-ponyon;;0;
-populous;;0;
-populus2;;0;
-populopl;;0;
-pleague;;0;
-pmonger;;0;
-premium;;0;
-premium2;;0;
-present;;0;
-present2;;0;
-prettydl;;0;
-ppersia;;0;
-princess;;0;
-prosoccr;;0;
-prostudg;;0;
-ptennwc;;0;
-proyak;;0;
-prodmang;;0;
-profmjg;;0;
-puppetsh;;0;
-puyopuyo;;0;
-puyopuyod;;0;
-puzznic;;0;
-quarters;;0;
-quarth;;0;
-quenduel;;0;
-quintia;;0;
-quizbanc;;0;
-quiztori;;0;
-rcrobotc;;0;
-rcrobot2;;0;
-rcrobot3;;0;
-rcrobot4;;0;
-rtype;;0;
-rance3;;0;
-raygun;;0;
-reichsr;;0;
-reinforc;;0;
-relics;;0;
-review;;0;
-rtishtar;;0;
-ringmst;;0;
-ringmst2;;0;
-tanba;;0;
-risinsun;;0;
-rogueall;;0;
-rouge;;0;
-royalbld;;0;
-runewort;;0;
-ryunaki;;0;
-ryukyu;;0;
-sabnack;;0;
-salamand;;0;
-sangoku;;0;
-sangoku3;;0;
-saori;;0;
-saotome;;0;
-saotome2;;0;
-sap;;0;
-schwarzs;;0;
-scorpius;;0;
-sekakimi;;0;
-shanghai;;0;
-shanghaiod;;0;
-shangh2;;0;
-shangh2d;;0;
-shangrli;;0;
-shangr2;;0;
-shangr2s;;0;
-shootrng;;0;
-shoot68k;;0;
-shogisei;;0;
-shojoden;;0;
-shflpuck;;0;
-signchou;;0;
-silentmb;;0;
-simant;;0;
-simcity;;1;
-simcitycd2;;0;
-simcitycd1;;0;
-simcityed;;0;
-simcitylog;;0;
-simearth;;0;
-slimyer;;0;
-softhard;;0;
-softhrd2;;0;
-solfeace;;0;
-soniclnk;;0;
-sotsugyo;;0;
-sotsugym;;0;
-sokoperf;;0;
-cannonsg;;0;
-sharrier;;0;
-spcrogue;;0;
-spindiz2;;0;
-spindiz2d;;0;
-squarers;;0;
-scruiser;;0;
-starfrce;;0;
-starlust;;0;
-starmobl;;0;
-startrad;;0;
-starwars;;0;
-starship;;0;
-strawdsn;;0;
-sf2ce;;0;
-strider;;0;
-suikoden;;0;
-superdps;;0;
-supdaisn;;0;
-supdaisnmc;;0;
-supdaisnpk;;0;
-shangon;;1;Back layer pen issues.
-slasvegs;;0;
-slasveg2;;0;
-sshangh;;0;
-srmp23;;0;
-srmp4;;0;
-ssf2;;0;
-ssf2a;;0;
-sweetang;;0;
-sweetemo;;0;
-syvalion;;0;
-tdf;;0;
-taiheiyo;;0;
-taikoris;;0;
-teiketsu;;0;
-telenetm;;0;
-tenkatou;;0;
-tenkatoud;;0;
-tenkyuh;;0;
-tenkyusp;;0;
-tenshinr;;0;
-tenshi3r;;0;
-tensh3bh;;0;
-tenshi4;;0;
-tenshi6;;0;
-tessera;;0;
-tetris;;0;
-thanatos;;0;
-thrice;;0;
-tblade;;0;
-tf2;;0;
-tf2d;;0;
-tokimecb;;0;
-tokyojs1;;0;
-tokyojs2;;0;
-bakkonst;;0;
-bakkons2;;0;
-toshinto;;0;
-toshintoh;;0;
-trilogyk;;0;
-tricornf;;0;
-tsukagag;;0;
-tunnelst;;0;
-twilight;;0;
-twiligh3;;0;
-twiligh4;;0;
-twinbee;;0;
-usvball;;0;
-ujincol;;0;
-funnybee;;0;
-ukbusin;;0;
-ultima4;;0;
-ultima5;;0;
-ultima6;;0;
-urotsuki;;0;
-vampireh;;0;
-versnag;;0;
-viewpoin;;0;
-viperv6t;;0;
-viperv8t;;0;
-willdeng;;0;
-warning;;0;
-wings;;0;
-winpost;;0;
-wordwort;;0;
-worldgl3;;0;
-savagemp;;0;
-wrestan3;;0;
-wrestans;;0;
-xak;;0;
-xenon2;;0;
-xevious;;0;
-xeviousd;;0;
-xna;;0;
-yajiuma;;0;
-yajiuma90;;0;
-yamikets;;0;
-yamiket2;;0;
-yaritai1;;0;
-yaritai2;;0;
-yesterd;;0;
-yorutens;;0;
-yojuclub;;0;
-yojuclb2;;0;
-yoju2048;;0;
-ys;;0;
-ys3;;0;
-zan;;0;
-zansc1;;0;
-zansc2;;0;
-zark;;0;
-zavas;;0;
-zenkaidn;;0;
-abunaten;;0;
-cresmoon;;0;
-dps;;0;
-dpssg;;0;
-dpssg2;;0;
-dpssg3;;0;
-rance;;0;
-rance2;;0;
-pacman;;0;
-human68k;;0;
-human68ka;;0;
-human68kb;;0;
-human68k_301;;0;
-human68k_301a;;0;
-human68k_301b;;0;
-human68k_202;;0;
-human68k_201;;0;
-human68k_20x;;0;
-sxwin31;;0;
-sxwin31a;;0;
-sxwin30;;0;
-sxwin20;;0;
-sxwin10;;0;
-sxwkkit;;0;
-os9;;0;
-os9cpro;;0;
-kowindow;;0;
-kowinap1;;0;
-kowinap2;;0;
-kowinap3;;0;
-kowinap4;;0;
-backpama;;0;
-backppro;;0;
-backupp1;;0;
-business;;0;
-ccompilr;;0;
-ccompilr210;;0;
-ccompilr200;;0;
-ctrace;;0;
-canvas;;0;
-canvasgl1;;0;
-canvasgl2;;0;
-cardpro;;0;
-cdrom;;0;
-communic;;0;
-physicn;;0;
-copyaid;;0;
-cybrnote;;0;
-cyclone;;0;
-cyclonea;;0;
-des;;0;
-easydraw;;0;
-easypnt;;0;
-ewword;;0;
-expansfdo;;0;
-expansfd;;0;
-fcalc;;0;
-fcardgt;;0;
-filem1g;;0;
-filem2g;;0;
-filem3g;;0;
-filem4g;;0;
-filem5g;;0;
-filem6g;;0;
-filem7g;;0;
-filemst100;;0;
-filemst100a;;0;
-filemst110;;0;
-filemst110a;;0;
-filemst;;0;
-fileprof;;0;
-final;;0;
-fixer100;;0;
-fixer;;0;
-formul68;;0;
-easygfxt;;0;
-gyopicha;;0;
-honyakuh;;0;
-hostpro;;0;
-hotfile1;;0;
-hotfile5;;0;
-hotfile6;;0;
-hotfile7;;0;
-hyperudv;;0;
-hyperwor;;0;
-itekomas;;0;
-kamikaze;;0;
-kiss;;0;
-konetjk1;;0;
-konetjk2;;0;
-lzd;;0;
-lzh;;0;
-magicpal;;0;
-matier10;;0;
-matier20;;0;
-matier;;0;
-messiah;;0;
-mu1;;0;
-multiwrd;;0;
-musicpro;;0;
-musicmid;;0;
-musicstd;;0;
-necodemo;;0;
-newprint;;0;
-newprintgl1;;0;
-newprintgl2;;0;
-newprintgc;;0;
-newprnt2;;0;
-nihonwp;;0;
-pattern;;0;
-personal;;0;
-polyphon;;0;
-prism68k;;0;
-sampling;;0;
-scsiutil;;0;
-soundpro;;0;
-spritedt;;0;
-statnary;;0;
-ssurgeon;;0;
-teleport;;0;
-terazzos;;0;
-termin;;0;
-termin2;;0;
-toystool;;0;
-twincp1;;0;
-twincp10;;0;
-wetpaint;;0;
-wetpain2;;0;
-wetpain3;;0;
-windex;;0;
-x68kcoll;;0;
-x68kcolla;;0;
-x68kace;;0;
-x68kacea;;0;
-x68kdev;;0;
-x68kfree;;0;
-x68klibc;;0;
-x68lscan;;0;
-x68mlang;;0;
-x68ktex;;0;
-xbas2c;;0;
-zpro68kv1;;0;
-zpro68kv2;;0;
-zpro68k;;0;
-zxvi68k;;0;
-triphodc;;0;
-sion;;0;
-sion2;;0;
-sion4;;0;
-brain31;;0;
-brain32;;0;
-brain33;;0;
-brain34;;0;
-brain35;;0;
-carrot8;;0;
-carrot9;;0;
-carrot11;;0;
-carrot13;;0;
-carrot14;;0;
-carrot15;;0;
-carrot16;;0;
-carrot18;;0;
-elfgraf;;0;
-dennocbi;;0;
-dennocc1;;0;
-dennocc2;;0;
-dennocc3;;0;
-dennocji;;0;
-dennocjn;;0;
-dennoc01;;0;
-dennoc02;;0;
-dennoc03;;0;
-dennoc04;;0;
-dennoc05;;0;
-dennoc06;;0;
-dennoc07;;0;
-dennoc08;;0;
-dennoc09;;0;
-dennoc10;;0;
-dennoc11;;0;
-dennoc12;;0;
-dennoc13;;0;
-dennoc14;;0;
-dennoc15;;0;
-dennoc16;;0;
-dennoc17;;0;
-dennoc18;;0;
-dennoc19;;0;
-dennoc20;;0;
-dennoc21;;0;
-dennoc22;;0;
-dennoc23;;0;
-dennoc24;;0;
-dennoc25;;0;
-dennoc26;;0;
-dennoc27;;0;
-dennoc28;;0;
-dennoc29;;0;
-dennoc30;;0;
-dennoc31;;0;
-dennoc32;;0;
-dennoc33;;0;
-dennoc34;;0;
-dennoc35;;0;
-dennoc36;;0;
-dennoc37;;0;
-dennoc38;;0;
-dennoc39;;0;
-dennoc40;;0;
-dennoc41;;0;
-dennoc42;;0;
-dennoc43;;0;
-dennoc44;;0;
-dennoc45;;0;
-dennoc46;;0;
-dennoc47;;0;
-dennoc48;;0;
-dennoc49;;0;
-dennoc50;;0;
-dennoc51;;0;
-dennoc52;;0;
-dennoc53;;0;
-dennoc54;;0;
-dennoc55;;0;
-dennoc56;;0;
-dennoc57;;0;
-dennoc58;;0;
-dennoc59;;0;
-dennoc60;;0;
-dennoc61;;0;
-dennoc62;;0;
-dennoc63;;0;
-dennoc64;;0;
-dennoc65;;0;
-dennoc66;;0;
-dennoc67;;0;
-dennoc68;;0;
-dennoc69;;0;
-dennoc70;;0;
-dennoc71;;0;
-dennoc72;;0;
-dennoc73;;0;
-dennoc74;;0;
-dennoc75;;0;
-dennoc76;;0;
-dennoc77;;0;
-dennoc78;;0;
-dennoc79;;0;
-dennoc80;;0;
-dennoc81;;0;
-dennoc82;;0;
-dennoc83;;0;
-dennoc84;;0;
-dennoc85;;0;
-dennoc86;;0;
-dennoc87;;0;
-dennoc88;;0;
-dennoc89;;0;
-dennoc90;;0;
-dennoc91;;0;
-dennoc92;;0;
-dennoc93;;0;
-dennoc95;;0;
-elrinda1;;0;
-finalm21;;0;
-finalm27;;0;
-hayabusa;;0;
-ohxzmus1;;0;
-ohxzmus1a;;0;
-ohxzmus2;;0;
-ohxzmus2a;;0;
-ohxs10;;0;
-ohx9006;;0;
-ohx9006a;;0;
-ohx9105;;0;
-ohx9105a;;0;
-ohx91xx;;0;
-ohx9206;;0;
-ohx9206a;;0;
-ohx9207;;0;
-ohx9310;;0;
-ohx9403;;0;
-ohx9405;;0;
-ohx9407;;0;
-ohx9410;;0;
-ohx9410a;;0;
-ohx9412;;0;
-ohx9412a;;0;
-ohx9505;;0;
-ohx9508;;0;
-ohx9512;;0;
-sennots1;;0;
-sennotmt;;0;
-tokkan3;;0;
-unform91;;0;
-unformtj;;0;
-unformat;;0;
-unformsj;;0;
-yippee1;;0;
-yippee2;;0;
-3danhen;;0;
-cybrmiss;;0;
-deltaarm;;0;
-fly;;0;
-galseed;;0;
-japan213;;0;
-ohootsuk;;0;
-scarlet1;;0;
-3meka;;0;
-37degc;;0;
-ajine;;0;
-aahime;;0;
-abuten;;0;
-accheat;;0;
-actshoot;;0;
-advland;;0;
-advland2;;0;
-advland2a;;0;
-aikoku;;0;
-airhork;;0;
-akazucha;;0;
-akazucc;;0;
-akazukin;;0;
-alfarne;;0;
-amamori;;0;
-amegame;;0;
-amheroes;;0;
-amheroesa;;0;
-andromed;;0;
-angeldiv;;0;
-anmira;;0;
-anzufly;;0;
-arianshu;;0;
-rumikqz;;0;
-rumikqz2;;0;
-ams2;;0;
-ruhappy;;0;
-arsia;;0;
-artemisd;;0;
-arururu;;0;
-astqueen;;0;
-asteroid;;0;
-asteroi2;;0;
-atennis;;0;
-ayachan;;0;
-bpoint;;0;
-babafgt2;;0;
-babel;;0;
-babeltou;;0;
-badroad;;0;
-bakamed;;0;
-bakaniki;;0;
-bakukeid;;0;
-bakudanm;;0;
-bakuyugi;;0;
-balonfgt;;0;
-bf92ce;;0;
-bf92bang;;0;
-bf92;;0;
-baribar3;;0;
-bbknuckl;;0;
-batlcity;;0;
-btlgame;;0;
-btlmania;;0;
-btlunit;;0;
-btlunit2;;0;
-bslfght000;;0;
-bslfght;;0;
-bsmnfght210;;0;
-bsmnfght;;0;
-slrmnkdk;;0;
-slrmntia;;0;
-bssmnfgt;;0;
-bssmnfgx;;0;
-sailrv3p;;0;
-sailrv5p;;0;
-sailrvf3;;0;
-sailrv2;;0;
-skirt1;;0;
-skirt2;;0;
-skirt3;;0;
-biyoyonc;;0;
-blanka;;0;
-bleedout;;0;
-blindspt;;0;
-bljack2;;0;
-blockout;;0;
-blocksto;;0;
-bluwaver;;0;
-bluwing2;;0;
-bm68;;0;
-bodhidh2;;0;
-bodhidha030;;0;
-bodhidha;;0;
-bombmand;;0;
-bonnou2;;0;
-bonnou2d;;0;
-bonnoumu;;0;
-bottoro2;;0;
-boynboyn;;0;
-boyoyon;;0;
-breakdwn;;0;
-breed;;0;
-butarian;;0;
-butasanq;;0;
-conz;;0;
-captcolr;;0;
-caterpi;;0;
-cavecrwd;;0;
-celcion;;0;
-celia;;0;
-celiad;;0;
-chachafv;;0;
-chachafv100;;0;
-chami;;0;
-chaosang;;0;
-chijou;;0;
-chikyugi;;0;
-chottohn;;0;
-chotmswp;;0;
-choubaku;;0;
-chorensa;;0;
-chorensa045;;0;
-chorensa035;;0;
-chorensa010;;0;
-circusx2;;0;
-citycon;;0;
-clayshot;;0;
-clearlap;;0;
-sailorq;;0;
-columnsg;;0;
-columnsm;;0;
-cmdxray;;0;
-cosmopzl;;0;
-cosmopzlm;;0;
-crarrow;;0;
-xfireex;;0;
-cryoku;;0;
-cryokud;;0;
-crystwr;;0;
-cubegrd3;;0;
-cylips;;0;
-cybrfld;;0;
-cybrrpg;;0;
-cynthia;;0;
-daifugou;;0;
-daikon;;0;
-daisn2ue;;0;
-dmgfgh2p;;0;
-dancexp;;0;
-dangarea;;0;
-dariball;;0;
-darius;;0;
-dariusdt;;0;
-dariuse;;0;
-darkcstl;;0;
-dastard;;0;
-datsugok;;0;
-dccard;;0;
-deathf2;;0;
-deepscak;;0;
-deepscan;;0;
-deep;;0;
-degon;;0;
-demslay;;0;
-demslay2;;0;
-demslay3;;0;
-dennogak;;0;
-desperad011;;0;
-desperad;;0;
-devilinv;;0;
-devilch;;0;
-devilch2;;0;
-diamexp;;0;
-diamexp2;;0;
-digdugd;;0;
-limnoama;;0;
-dion;;0;
-directx;;0;
-discoscr;;0;
-disk7fmv;;0;
-disk8fmv;;0;
-disk9fmv;;0;
-diveon2d;;0;
-diveon;;0;
-diveond;;0;
-diver;;0;
-dofmoria;;0;
-dogfight;;0;
-dokiaman;;0;
-doordoor;;0;
-doridor;;0;
-dorix;;0;
-dbltargt;;0;
-drasan;;0;
-drorima;;0;
-dslayer;;0;
-dragonx;;0;
-drgnprov;;0;
-dquest100;;0;
-dquest;;0;
-drnksmok;;0;
-drnksmod;;0;
-duelfgh2;;0;
-duelfght;;0;
-dungseek;;0;
-dynamics;;0;
-eeledit;;0;
-eff;;0;
-elfcg;;0;
-elrinda2;;0;
-erionqst;;0;
-excitbik;;0;
-ezoris;;0;
-fastlap;;0;
-famass;;0;
-fancyqix;;0;
-fantsht;;0;
-farewell;;0;
-fevrie;;0;
-fifteen1;;0;
-fifteen2;;0;
-fifteen3;;0;
-fifteen4;;0;
-fifteen5;;0;
-fifteen6;;0;
-fifteen7;;0;
-fire;;0;
-firia;;0;
-1stblow;;0;
-fcrisis;;0;
-fmaindsh;;0;
-fmission;;0;
-fmissio2;;0;
-flmwing;;0;
-flmdart;;0;
-fleur;;0;
-flipflop;;0;
-flipull;;0;
-flyshoot;;0;
-formulax;;0;
-formxt;;0;
-formxy;;0;
-fortatk;;0;
-fortyone;;0;
-fourfall;;0;
-fourfallu;;0;
-frapull;;0;
-frayd;;0;
-friskytm;;0;
-frog;;0;
-frogger;;0;
-froggero;;0;
-fushigid;;0;
-gaiafght;;0;
-gaiarm;;0;
-gakutosh;;0;
-galagad;;0;
-galaxian;;0;
-galaxia2;;0;
-galax68k;;0;
-galwars;;0;
-galmind2;;0;
-gamex;;0;
-ganpaich;;0;
-gardislg;;0;
-gardisli202;;0;
-gardisli202a;;0;
-gawar;;0;
-gedou;;0;
-gedouret;;0;
-gekkan5;;0;
-gemdrop;;0;
-getready;;0;
-getsumen;;0;
-gigafght;;0;
-glacierd;;0;
-glacier;;0;
-godblazn;;0;
-gokiburi;;0;
-grobda;;0;
-grobdam;;0;
-guardian;;0;
-guardans;;0;
-gyaos;;0;
-htdash;;0;
-hakobune;;0;
-halfmind;;0;
-halfmnd2;;0;
-hanakoi;;0;
-hanaiko;;0;
-hatenkou;;0;
-hazard;;0;
-hrtsaph;;0;
-hnkyo68k;;0;
-heiankyo;;0;
-hellhoun;;0;
-helmet;;0;
-herohero;;0;
-heroher4;;0;
-heroher6;;0;
-heroher8;;0;
-hetzer;;0;
-hextris;;0;
-heysay;;0;
-heysay010;;0;
-higesori;;0;
-highlow;;0;
-highpos;;0;
-himegas;;0;
-hiroshi;;0;
-hiroshi2;;0;
-hyuusha;;0;
-hitomiza;;0;
-hitomizaa;;0;
-hitton;;0;
-hoippuru;;0;
-horiume;;0;
-horror;;0;
-hotjump;;0;
-hotjumpo;;0;
-htjewel;;0;
-hvrcraft;;0;
-hydlide;;0;
-hydlide2;;0;
-ikablade;;0;
-ikkakutc;;0;
-ilmlaser;;0;
-imazoman;;0;
-iinoyama;;0;
-integral;;0;
-intropro;;0;
-jaleckex;;0;
-jammes;;0;
-jankencb;;0;
-jastis;;0;
-jeena;;0;
-jotei1;;0;
-jotei2;;0;
-jotei3;;0;
-jotei4;;0;
-jumpsimn;;0;
-junkerpr;;0;
-kachofug;;0;
-kaisengd;;0;
-kaizoku;;0;
-kankyoss;;0;
-karouden;;0;
-karoudensd;;0;
-karoudensds;;0;
-karoudenhd;;0;
-karoudsp;;0;
-kateikyo;;0;
-kateiky2;;0;
-kawaisou;;0;
-kax;;0;
-kikoyosa202;;0;
-kikoyosa;;0;
-kingou2;;0;
-kisehazu;;0;
-kishikai;;0;
-klaxpm;;0;
-knightar;;0;
-knightmk;;0;
-koma;;0;
-korakora;;0;
-korette;;0;
-kosogens;;0;
-kukeisf;;0;
-kurukuru;;0;
-kyarukan;;0;
-kyunkyun;;0;
-kyunkyu2;;0;
-ksgikadv;;0;
-lamp;;0;
-lastpic2;;0;
-lasttemp;;0;
-laydock;;0;
-leshies;;0;
-levelpnta;;0;
-levelpnt;;0;
-lexus2;;0;
-libblerd;;0;
-libblerd1;;0;
-libblerd2;;0;
-liberty;;0;
-limeligt;;0;
-lilchin;;0;
-lilchind;;0;
-lilchinf;;0;
-lockon;;0;
-lockon2;;0;
-lockon3;;0;
-ldrun;;0;
-ldrun1;;0;
-longnigt;;0;
-lot3;;0;
-lumchan;;0;
-lumchank;;0;
-lunafant;;0;
-luster;;0;
-lyricalp;;0;
-macross;;0;
-madgear;;0;
-magery;;0;
-magery2;;0;
-magery3;;0;
-mageryot;;0;
-magcrash;;0;
-magritte;;0;
-mjtengok;;0;
-mahokuni;;0;
-mahousen;;0;
-majohall;;0;
-mappy1;;0;
-mappy2;;0;
-marblmag;;0;
-marblpan;;0;
-marblrevt;;0;
-marblrv2;;0;
-marblrev;;0;
-mario;;0;
-marmalad;;0;
-marss;;0;
-peepshot;;0;
-mcha;;0;
-menosakk;;0;
-jangken;;0;
-megamipn;;0;
-memobrkn;;0;
-metlunit;;0;
-metluni2;;0;
-meteowrs;;0;
-mikkunl;;0;
-millisht;;0;
-minami;;0;
-miragerw;;0;
-missile3;;0;
-missile2;;0;
-missile1;;0;
-missile1a;;0;
-missadlt;;0;
-mogu1990;;0;
-mogura;;0;
-mokonasp;;0;
-mokonas;;0;
-moloq;;0;
-momotaro;;0;
-momogaid;;0;
-momotar2;;0;
-monmonss;;0;
-monmons2;;0;
-monmons3;;0;
-monmonsx;;0;
-moneyh;;0;
-monstpan;;0;
-moria;;0;
-moritan;;0;
-mouichid;;0;
-mysteryh;;0;
-nageyari;;0;
-naniwa2;;0;
-naniwa;;0;
-naniwa3;;0;
-nmfire;;0;
-nasakemf;;0;
-nazors;;0;
-nemes93;;0;
-nemes94;;0;
-nervbj;;0;
-newbokow;;0;
-nicejan;;0;
-nininbtl;;0;
-nininbtla;;0;
-nisedqv;;0;
-nishitet;;0;
-norikotb;;0;
-noutendn;;0;
-nova;;0;
-nyankosw;;0;
-ohhajiki;;0;
-oraorabl;;0;
-oraorabl1;;0;
-orashoot;;0;
-origames;;0;
-ossandot;;0;
-otokodam;;0;
-ougonbut;;0;
-overdriv;;0;
-pacmanit;;0;
-pacmand;;0;
-pacmen;;0;
-pachisur51;;0;
-pachisur;;0;
-paikouka;;0;
-paroran212;;0;
-paroran;;0;
-parsec305;;0;
-parsec;;0;
-prtaxiom;;0;
-paruru;;0;
-patariro;;0;
-penjang;;0;
-pensancd;;0;
-pentaris;;0;
-peshipzl;;0;
-peshipz2;;0;
-phoenixq;;0;
-pinball1;;0;
-pizzabst;;0;
-plantinv;;0;
-plesea;;0;
-putiplin;;0;
-putiplina;;0;
-putiplinb;;0;
-pokersis;;0;
-pole2win;;0;
-popcard;;0;
-popjack;;0;
-porolith;;0;
-porttowr;;0;
-potton;;0;
-powerrac;;0;
-poyopoyo;;0;
-princenp;;0;
-prinbing;;0;
-princros;;0;
-profit;;0;
-projdhn1;;0;
-projdhn2;;0;
-projdhn3;;0;
-projmoon;;0;
-prostit;;0;
-proth68k;;0;
-fassbust;;0;
-psycharr;;0;
-puchipuc;;0;
-puninces;;0;
-pushbon;;0;
-pushbona;;0;
-puzzle;;0;
-puzzle15;;0;
-questqst;;0;
-questlnd;;0;
-quieazm2;;0;
-quieazum;;0;
-quieazmd;;0;
-quizbocc;;0;
-quizcult;;0;
-quizpon;;0;
-quizfght;;0;
-quizjan;;0;
-quizjigo;;0;
-quizjock;;0;
-quizmang;;0;
-quizsnip;;0;
-rplusr;;0;
-rplusrd;;0;
-r3golf;;0;
-raguna;;0;
-rallyx;;0;
-ramunecl;;0;
-raydefoxo2;;0;
-raydefoxo1;;0;
-raydefox;;0;
-raydefx2;;0;
-rayersht;;0;
-rayvs;;0;
-real;;0;
-redarms;;0;
-redarmsm;;0;
-refresh;;0;
-reserve;;0;
-riiyaden;;0;
-ripobita;;0;
-robotbt2;;0;
-rolldwn2;;0;
-rotateo;;0;
-rotate;;0;
-rotation;;0;
-sabaodam;;0;
-sades;;0;
-sailrmbk;;0;
-sailrms;;0;
-sailorv2;;0;
-sailorv3;;0;
-sailrmcq;;0;
-sakeruda;;0;
-samegame;;0;
-sarumune;;0;
-satelit2;;0;
-satbatle;;0;
-satelit;;0;
-satorisp;;0;
-satoris2;;0;
-isonofam;;0;
-scramble;;0;
-scrap;;0;
-sdfightr;;0;
-sdsadist;;0;
-sdtoki;;0;
-sebasuch;;0;
-seethru2;;0;
-seesaw;;0;
-seiruna;;0;
-seifukuk;;0;
-seiyudai;;0;
-sekaiss;;0;
-sekizudx;;0;
-sekizuhao;;0;
-sekizuha;;0;
-senegal;;0;
-senningm;;0;
-senshasn;;0;
-senshasna;;0;
-senshas3;;0;
-shikato;;0;
-shikendm;;0;
-shikenmi;;0;
-shikendu;;0;
-shimaimj100;;0;
-shimaimj110;;0;
-shimaimj130;;0;
-shimaimj;;0;
-sbbknuck;;0;
-shinkeis;;0;
-shouten;;0;
-silkrod2;;0;
-silkroad;;0;
-silsteel;;0;
-silsteelo;;0;
-silverbl;;0;
-silvrcry;;0;
-slimemst;;0;
-smsxmoon;;0;
-smsxsamp;;0;
-snell;;0;
-snowkibn;;0;
-solitair;;0;
-solitea;;0;
-sorcer;;0;
-sorcerys;;0;
-sorceryso;;0;
-sorcsugo;;0;
-souhoubp;;0;
-souhoutv;;0;
-sokoban;;0;
-sinv;;0;
-spacelnd;;0;
-spacesld;;0;
-spannerx;;0;
-spannera;;0;
-tenanmon;;0;
-spiralbl;;0;
-starblad;;0;
-starblap;;0;
-starchrg;;0;
-starcrs2;;0;
-starfght;;0;
-starlusd;;0;
-starpuls;;0;
-startrek;;0;
-starwar;;0;
-starfrcd;;0;
-steelgun;;0;
-stox;;0;
-haita2b;;0;
-haita2a;;0;
-haita2;;0;
-streetuc;;0;
-stripfgt;;0;
-stripfg2;;0;
-strokex;;0;
-suchabtl100;;0;
-suchabtl;;0;
-sukaparo;;0;
-sukatan;;0;
-superart;;0;
-supercgq;;0;
-superdai;;0;
-superfm;;0;
-superfis;;0;
-supergft;;0;
-superjck;;0;
-smb;;0;
-smponjan;;0;
-supermf;;0;
-spakris;;0;
-spakrisa;;0;
-sshinpi;;0;
-sss;;0;
-sssd;;0;
-sss2;;0;
-streetbm;;0;
-stphalnx;;0;
-superxdx;;0;
-superx95;;0;
-swordmst;;0;
-swordms2;;0;
-sxaoumio;;0;
-sxaoumi;;0;
-t94x;;0;
-tdquesto;;0;
-tdquest;;0;
-tdquestup;;0;
-tdquest2b;;0;
-tdquest2a;;0;
-tdquest2;;0;
-tacolis;;0;
-tailchas;;0;
-karatedo;;0;
-takeout;;0;
-takogame;;0;
-tankbatt;;0;
-tankbatl;;0;
-tank6;;0;
-target;;0;
-targetv2;;0;
-targetv2h;;0;
-tataka8k;;0;
-kcomik46;;0;
-kcomik47;;0;
-kcomikex;;0;
-tekkense;;0;
-tenchimu;;0;
-tenchipz;;0;
-terishu;;0;
-terradrv;;0;
-terumina;;0;
-tetrisse;;0;
-tetriscfb;;0;
-tetriscfa;;0;
-tetriscf;;0;
-tetrislca;;0;
-tetrislc;;0;
-texceed;;0;
-tf4go;;0;
-tf4g;;0;
-theater1;;0;
-theater2;;0;
-walldown;;0;
-timcc94;;0;
-timpaper;;0;
-timelag;;0;
-timeplt;;0;
-tinna7c;;0;
-tinyclmn;;0;
-tinyhopp;;0;
-tokimls;;0;
-tokimls2;;0;
-tokitais;;0;
-tokkoukf;;0;
-tokukeij;;0;
-tonkotsu;;0;
-toridesg;;0;
-tojodens;;0;
-druaga;;0;
-toypop;;0;
-triangle;;0;
-tripleya;;0;
-twinsoul;;0;
-twtwins2;;0;
-twins;;0;
-ueshitah;;0;
-uhauha2;;0;
-ultimagc;;0;
-uno;;0;
-uramikk;;0;
-uruseiya;;0;
-usagijmp;;0;
-vagrantf;;0;
-valentin;;0;
-vaystarn;;0;
-virgangl;;0;
-vision;;0;
-vsklith;;0;
-vulquar;;0;
-wbullet;;0;
-wtank;;0;
-wakaog;;0;
-wanders;;0;
-waterblu;;0;
-wfantas;;0;
-wildcard;;0;
-windblst;;0;
-wips2;;0;
-wrecking;;0;
-xtype;;0;
-xadlak;;0;
-xadlak221;;0;
-xadlako;;0;
-xanadu;;0;
-xevioud;;0;
-y2;;0;
-y2d;;0;
-yacolumn;;0;
-yonkaku;;0;
-ys1d;;0;
-ysmilk;;0;
-ys2miss;;0;
-ys2milk;;0;
-yctrump;;0;
-yugachas;;0;
-yugaiga2;;0;
-yugaigak;;0;
-yugaipzl;;0;
-yugaiwar;;0;
-yuzurugi;;0;
-zeromasto;;0;
-zeromast;;0;
-zerorei;;0;
-zolgus;;0;
-zounds;;0;
-zoutage;;0;
-zugya;;0;
-cryokua;;0;
-cynthi2;;0;
-formulaxa;;0;
-grdiusac;;0;
-todayjob;;0;
-larjis;;0;
-t94xa;;0;
-lcmyprin;;0;
-zeromastx;;0;
-smba;;0;