summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs/luareference.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/techspecs/luareference.rst')
-rw-r--r--docs/source/techspecs/luareference.rst2902
1 files changed, 0 insertions, 2902 deletions
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
deleted file mode 100644
index 98cf98b3530..00000000000
--- a/docs/source/techspecs/luareference.rst
+++ /dev/null
@@ -1,2902 +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-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.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.
-
-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 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 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, bottom, [color])
- Draws a line from (x1, y1) to (x2, y2).
-
- 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.
-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 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 foreground and background colours 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 foreground colour is not provided, the UI
- text colour is used; if the background colour is not provided, the UI
- background colour is used.
-
-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 input sequence 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: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 input sequence 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 input sequence for the specified sequence type. This
- gets per-machine input settings. The sequence type must be ``"standard"``,
- ``"increment"`` or ``"decrement"``.
-field:set_default_input_seq(seq_type, seq)
- Set the default input sequence for the specified sequence type. This is
- used to configure general input settings. The sequence type must be
- ``"standard"``, ``"increment"`` or ``"decrement"``.
-field:default_input_seq(seq_type)
- Gets the default input sequence for the specified sequence type. This is
- gets general input settings. 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 Boolen indicating whether the supplied input sequence is currently
- pressed.
-input:seq_clean(seq)
- Remove invalid elements from the supplied input sequence. Returns the new,
- cleaned input sequence.
-input:seq_name(seq)
- Get display text for an inptu sequence.
-input:seq_to_tokens(seq)
- Convert an input sequence to a token string. This should be used when
- saving configuration.
-input:seq_from_tokens(tokens)
- Convert a token string to an input sequence. 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 input sequence for configuring an analog input.
-input:axis_sequence_poller()
- Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an input sequence 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 input sequence. 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-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.
-
-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.
-
-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.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.