summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/luascript/ref-core.rst
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2023-07-06 09:52:10 +1000
committer Vas Crabb <vas@vastheman.com>2023-07-06 09:52:10 +1000
commit12623c3fd35984f75e31144126689986af657a30 (patch)
tree8b8b01669ab168705148152e3f4a3622945dd04c /docs/source/luascript/ref-core.rst
parent737af4b6655d1de338895272bfeeec8bb7b7b17f (diff)
docs: Moved Lua API reference to its own section - the page was far too long.
Diffstat (limited to 'docs/source/luascript/ref-core.rst')
-rw-r--r--docs/source/luascript/ref-core.rst635
1 files changed, 635 insertions, 0 deletions
diff --git a/docs/source/luascript/ref-core.rst b/docs/source/luascript/ref-core.rst
new file mode 100644
index 00000000000..f761b20f5de
--- /dev/null
+++ b/docs/source/luascript/ref-core.rst
@@ -0,0 +1,635 @@
+.. _luascript-ref-core:
+
+Lua Core Classes
+================
+
+Many of MAME’s core classes used to implement an emulation session are available
+to Lua scripts.
+
+.. contents::
+ :local:
+ :depth: 1
+
+
+.. _luascript-ref-notifiersub:
+
+Notifier subscription
+---------------------
+
+Wraps MAME’s ``util::notifier_subscription`` class, which manages a subscription
+to a broadcast notification.
+
+Methods
+~~~~~~~
+
+subscription:unsubscribe()
+ Unsubscribes from notifications. The subscription will become inactive and
+ no future notifications will be received.
+
+Properties
+~~~~~~~~~~
+
+subscription.is_active (read-only)
+ A Boolean indicating whether the subscription is active. A subscription
+ becomes inactive after explicitly unsubscribing or if the underlying
+ notifier is destroyed.
+
+
+.. _luascript-ref-attotime:
+
+Attotime
+--------
+
+Wraps MAME’s ``attotime`` class, which represents a high-precision time
+interval. Attotime values support addition and subtraction with other attotime
+values, and multiplication and division by integers.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.attotime()
+ Creates an attotime value representing zero (i.e. no elapsed time).
+emu.attotime(seconds, attoseconds)
+ Creates an attotime with the specified whole and fractional parts.
+emu.attotime(attotime)
+ Creates a copy of an existing attotime value.
+emu.attotime.from_double(seconds)
+ Creates an attotime value representing the specified number of seconds.
+emu.attotime.from_ticks(periods, frequency)
+ Creates an attotime representing the specified number of periods of the
+ specified frequency in Hertz.
+emu.attotime.from_seconds(seconds)
+ Creates an attotime value representing the specified whole number of
+ seconds.
+emu.attotime.from_msec(milliseconds)
+ Creates an attotime value representing the specified whole number of
+ milliseconds.
+emu.attotime.from_usec(microseconds)
+ Creates an attotime value representing the specified whole number of
+ microseconds.
+emu.attotime.from_nsec(nanoseconds)
+ Creates an attotime value representing the specified whole number of
+ nanoseconds.
+
+Methods
+~~~~~~~
+
+t:as_double()
+ Returns the time interval in seconds as a floating-point value.
+t:as_hz()
+ Interprets the interval as a period and returns the corresponding frequency
+ in Hertz as a floating-point value. Returns zero if ``t.is_never`` is true.
+ The interval must not be zero.
+t:as_khz()
+ Interprets the interval as a period and returns the corresponding frequency
+ kilohertz as a floating-point value. Returns zero if ``t.is_never`` is
+ true. The interval must not be zero.
+t:as_mhz()
+ Interprets the interval as a period and returns the corresponding frequency
+ megahertz as a floating-point value. Returns zero if ``t.is_never`` is
+ true. The interval must not be zero.
+t:as_ticks(frequency)
+ Returns the interval as a whole number of periods at the specified
+ frequency. The frequency is specified in Hertz.
+
+Properties
+~~~~~~~~~~
+
+t.is_zero (read-only)
+ A Boolean indicating whether the value represents no elapsed time.
+t.is_never (read-only)
+ A Boolean indicating whether the value is greater than the maximum number of
+ whole seconds that can be represented (treated as an unreachable time in the
+ future or overflow).
+t.attoseconds (read-only)
+ The fraction seconds portion of the interval in attoseconds.
+t.seconds (read-only)
+ The number of whole seconds in the interval.
+t.msec (read-only)
+ The number of whole milliseconds in the fractional seconds portion of the
+ interval.
+t.usec (read-only)
+ The number of whole microseconds in the fractional seconds portion of the
+ interval.
+t.nsec (read-only)
+ The number of whole nanoseconds in the fractional seconds portion of the
+ interval.
+
+
+.. _luascript-ref-mameman:
+
+MAME machine manager
+--------------------
+
+Wraps MAME’s ``mame_machine_manager`` class, which holds the running machine, UI
+manager, and other global components.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager
+ The MAME machine manager is available as a global variable in the Lua
+ environment.
+
+Properties
+~~~~~~~~~~
+
+manager.machine (read-only)
+ The :ref:`running machine <luascript-ref-machine>` for the current emulation
+ session.
+manager.ui (read-only)
+ The :ref:`UI manager <luascript-ref-uiman>` for the current session.
+manager.options (read-only)
+ The :ref:`emulation options <luascript-ref-emuopts>` for the current
+ session.
+manager.plugins[] (read-only)
+ Gets information about the :ref:`Lua plugins <luascript-ref-plugin>` that
+ are present, indexed by name. The index get, ``at`` and ``index_of``
+ methods have O(n) complexity.
+
+
+.. _luascript-ref-machine:
+
+Running machine
+---------------
+
+Wraps MAME’s ``running_machine`` class, which represents an emulation session.
+It provides access to the other core objects that implement an emulation session
+as well as the emulated device tree.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine
+ Gets the running machine instance for the current emulation session.
+
+Methods
+~~~~~~~
+
+machine:exit()
+ Schedules an exit from the current emulation session. This will either
+ return to the system selection menu or exit the application, depending on
+ how it was started. This method returns immediately, before the scheduled
+ exit takes place.
+machine:hard_reset()
+ Schedules a hard reset. This is implemented by tearing down the emulation
+ session and starting another emulation session for the same system. This
+ method returns immediately, before the scheduled reset takes place.
+machine:soft_reset()
+ Schedules a soft reset. This is implemented by calling the reset method of
+ the root device, which is propagated down the device tree. This method
+ returns immediately, before the scheduled reset takes place.
+machine:save(filename)
+ Schedules saving machine state to the specified file. If the file name is a
+ relative path, it is considered to be relative to the first configured save
+ state directory. This method returns immediately, before the machine state
+ is saved. If this method is called when a save or load operation is already
+ pending, the previously pending operation will be cancelled.
+machine:load(filename)
+ Schedules loading machine state from the specified file. If the file name
+ is a relative path, the configured save state directories will be searched.
+ This method returns immediately, before the machine state is saved. If this
+ method is called when a save or load operation is already pending, the
+ previously pending operation will be cancelled.
+machine:popmessage([msg])
+ Displays a pop-up message to the user. If the message is not provided, the
+ currently displayed pop-up message (if any) will be hidden.
+machine:logerror(msg)
+ Writes the message to the machine error log. This may be displayed in a
+ debugger window, written to a file, or written to the standard error output.
+
+Properties
+~~~~~~~~~~
+
+machine.time (read-only)
+ The elapsed emulated time for the current session as an
+ :ref:`attotime <luascript-ref-attotime>`.
+machine.system (read-only)
+ The :ref:`driver metadata <luascript-ref-driver>` for the current
+ system.
+machine.parameters (read-only)
+ The :ref:`parameters manager <luascript-ref-paramman>` for the current
+ emulation session.
+machine.video (read-only)
+ The :ref:`video manager <luascript-ref-videoman>` for the current emulation
+ session.
+machine.sound (read-only)
+ The :ref:`sound manager <luascript-ref-soundman>` for the current emulation
+ session.
+machine.output (read-only)
+ The :ref:`output manager <luascript-ref-outputman>` for the current
+ emulation session.
+machine.memory (read-only)
+ The :ref:`emulated memory manager <luascript-ref-memman>` for the current
+ session.
+machine.ioport (read-only)
+ The :ref:`I/O port manager <luascript-ref-ioportman>` for the current
+ emulation session.
+machine.input (read-only)
+ The :ref:`input manager <luascript-ref-inputman>` for the current emulation
+ session.
+machine.natkeyboard (read-only)
+ Gets the :ref:`natural keyboard manager <luascript-ref-natkbdman>`, used for
+ controlling keyboard and keypad input to the emulated system.
+machine.uiinput (read-only)
+ The :ref:`UI input manager <luascript-ref-uiinputman>` for the current
+ emulation session.
+machine.render (read-only)
+ The :ref:`render manager <luascript-ref-renderman>` for the current
+ emulation session.
+machine.debugger (read-only)
+ The :ref:`debugger manager <luascript-ref-debugman>` for the current
+ emulation session, or ``nil`` if the debugger is not enabled.
+machine.options (read-only)
+ The user-specified :ref:`options <luascript-ref-emuopts>` for the current
+ emulation session.
+machine.samplerate (read-only)
+ The output audio sample rate in Hertz.
+machine.paused (read-only)
+ A Boolean indicating whether emulation is not currently running, usually
+ because the session has been paused or the emulated system has not completed
+ starting.
+machine.exit_pending (read-only)
+ A Boolean indicating whether the emulation session is scheduled to exit.
+machine.hard_reset_pending (read-only)
+ A Boolean indicating whether a hard reset of the emulated system is pending.
+machine.devices (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`devices <luascript-ref-device>` in the emulated system.
+machine.palettes (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`palette devices <luascript-ref-dipalette>` in the emulated system.
+machine.screens (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`screen devices <luascript-ref-screendev>` in the emulated system.
+machine.cassettes (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`cassette image devices <luascript-ref-cassdev>` in the emulated
+ system.
+machine.images (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`media image devices <luascript-ref-diimage>` in the emulated system.
+machine.slots (read-only)
+ A :ref:`device enumerator <luascript-ref-devenum>` that yields all
+ :ref:`slot devices <luascript-ref-dislot>` in the emulated system.
+
+
+.. _luascript-ref-videoman:
+
+Video manager
+-------------
+
+Wraps MAME’s ``video_manager`` class, which is responsible for coordinating
+emulated video drawing, speed throttling, and reading host inputs.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.video
+ Gets the video manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+video:frame_update()
+ Updates emulated screens, reads host inputs, and updates video output.
+video:snapshot()
+ Saves snapshot files according to the current configuration. If MAME is
+ configured to take native emulated screen snapshots, one snapshot will be
+ saved for each emulated screen that is visible in a host window/screen with
+ the current view configuration. If MAME is not configured to use take
+ native emulated screen snapshots or if the system has no emulated screens, a
+ single snapshot will be saved using the currently selected snapshot view.
+video:begin_recording([filename], [format])
+ Stops any video recordings currently in progress and starts recording either
+ the visible emulated screens or the current snapshot view, depending on
+ whether MAME is configured to take native emulated screen snapshots.
+
+ If the file name is not supplied, the configured snapshot file name is used.
+ If the file name is a relative path, it is interpreted relative to the first
+ configured snapshot directory. If the format is supplied, it must be
+ ``"avi"`` or ``"mng"``. If the format is not supplied, it defaults to AVI.
+video:end_recording()
+ Stops any video recordings that are in progress.
+video:snapshot_size()
+ Returns the width and height in pixels of snapshots created with the current
+ snapshot target configuration and emulated screen state. This may be
+ configured explicitly by the user, or calculated based on the selected
+ snapshot view and the resolution of any visible emulated screens.
+video:snapshot_pixels()
+ Returns the pixels of a snapshot created using the current snapshot target
+ configuration as 32-bit integers packed into a binary string in host Endian
+ order. Pixels are organised in row-major order, from left to right then top
+ to bottom. Pixel values are colours in RGB format packed into 32-bit
+ integers.
+
+Properties
+~~~~~~~~~~
+
+video.speed_factor (read-only)
+ Configured emulation speed adjustment in per mille (i.e. the ratio to normal
+ speed multiplied by 1,000).
+video.throttled (read/write)
+ A Boolean indicating whether MAME should wait before video updates to avoid
+ running faster than the target speed.
+video.throttle_rate (read/write)
+ The target emulation speed as a ratio of full speed adjusted by the speed
+ factor (i.e. 1 is normal speed adjusted by the speed factor, larger numbers
+ are faster, and smaller numbers are slower).
+video.frameskip (read/write)
+ The number of emulated video frames to skip drawing out of every twelve, or
+ -1 to automatically adjust the number of frames to skip to maintain the
+ target emulation speed.
+video.speed_percent (read-only)
+ The current emulated speed as a percentage of the full speed adjusted by the
+ speed factor.
+video.effective_frameskip (read-only)
+ The number of emulated frames that are skipped out of every twelve.
+video.skip_this_frame (read-only)
+ A Boolean indicating whether the video manager will skip drawing emulated
+ screens for the current frame.
+video.snap_native (read-only)
+ A Boolean indicating whether the video manager will take native emulated
+ screen snapshots. In addition to the relevant configuration setting, the
+ emulated system must have at least one emulated screen.
+video.is_recording (read-only)
+ A Boolean indicating whether any video recordings are currently in progress.
+video.snapshot_target (read-only)
+ The :ref:`render target <luascript-ref-rendertarget>` used to produce
+ snapshots and video recordings.
+
+
+.. _luascript-ref-soundman:
+
+Sound manager
+-------------
+
+Wraps MAME’s ``sound_manager`` class, which manages the emulated sound stream
+graph and coordinates sound output.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.sound
+ Gets the sound manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+sound:start_recording([filename])
+ Starts recording to a WAV file. Has no effect if currently recording. If
+ the file name is not supplied, uses the configured WAV file name (from
+ command line or INI file), or has no effect if no WAV file name is
+ configured. Returns ``true`` if recording started, or ``false`` if
+ recording is already in progress, opening the output file failed, or no file
+ name was supplied or configured.
+sound:stop_recording()
+ Stops recording and closes the file if currently recording to a WAV file.
+sound:get_samples()
+ Returns the current contents of the output sample buffer as a binary string.
+ Samples are 16-bit integers in host byte order. Samples for left and right
+ stereo channels are interleaved.
+
+Properties
+~~~~~~~~~~
+
+sound.muted (read-only)
+ A Boolean indicating whether sound output is muted for any reason.
+sound.ui_mute (read/write)
+ A Boolean indicating whether sound output is muted at the request of the
+ user.
+sound.debugger_mute (read/write)
+ A Boolean indicating whether sound output is muted at the request of the
+ debugger.
+sound.system_mute (read/write)
+ A Boolean indicating whether sound output is muted at the request of the
+ emulated system.
+sound.attenuation (read/write)
+ The output volume attenuation in decibels. Should generally be a negative
+ integer or zero.
+sound.recording (read-only)
+ A Boolean indicating whether sound output is currently being recorded to a
+ WAV file.
+
+
+.. _luascript-ref-outputman:
+
+Output manager
+--------------
+
+Wraps MAME’s ``output_manager`` class, providing access to system outputs that
+can be used for interactive artwork or consumed by external programs.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.output
+ Gets the output manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+output:set_value(name, val)
+ Sets the specified output value. The value must be an integer. The output
+ will be created if it does not already exist.
+output:set_indexed_value(prefix, index, val)
+ Appends the index (formatted as a decimal integer) to the prefix and sets
+ the value of the corresponding output. The value must be an integer. The
+ output will be created if it does not already exist.
+output:get_value(name)
+ Returns the value of the specified output, or zero if it doesn’t exist.
+output:get_indexed_value(prefix, index)
+ Appends the index (formatted as a decimal integer) to the prefix and returns
+ the value of the corresponding output, or zero if it doesn’t exist.
+output:name_to_id(name)
+ Gets the per-session unique integer ID for the specified output, or zero if
+ it doesn’t exist.
+output:id_to_name(id)
+ Gets the name for the output with the specified per-session unique ID, or
+ ``nil`` if it doesn’t exist. This method has O(n) complexity, so avoid
+ calling it when performance is important.
+
+
+.. _luascript-ref-paramman:
+
+Parameters manager
+------------------
+
+Wraps MAME’s ``parameters_manager`` class, which provides a simple key-value
+store for metadata from system ROM definitions.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.machine.parameters
+ Gets the parameters manager for the current emulation session.
+
+Methods
+~~~~~~~
+
+parameters:lookup(tag)
+ Gets the value for the specified parameter if it is set, or an empty string
+ if it is not set.
+parameters:add(tag, value)
+ Sets the specified parameter if it is not set. Has no effect if the
+ specified parameter is already set.
+
+
+.. _luascript-ref-uiman:
+
+UI manager
+----------
+
+Wraps MAME’s ``mame_ui_manager`` class, which handles menus and other user
+interface functionality.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.ui
+ Gets the UI manager for the current session.
+
+Methods
+~~~~~~~
+
+ui:get_char_width(ch)
+ Gets the width of a Unicode character as a proportion of the width of the UI
+ container in the current font at the configured UI line height.
+ui:get_string_width(str)
+ Gets the width of a string as a proportion of the width of the UI container
+ in the current font at the configured UI line height.
+ui:set_aggressive_input_focus(enable)
+ On some platforms, this controls whether MAME should accept input focus in
+ more situations than when its windows have UI focus.
+ui:get_general_input_setting(type, [player])
+ Gets a description of the configured
+ :ref:`input sequence <luascript-ref-inputseq>` for the specified input type
+ and player suitable for using in prompts. The input type is an enumerated
+ value. The player number is a zero-based index. If the player number is
+ not supplied, it is assumed to be zero.
+
+Properties
+~~~~~~~~~~
+
+ui.options (read-only)
+ The UI :ref:`options <luascript-ref-coreopts>` for the current session.
+ui.line_height (read-only)
+ The configured UI text line height as a proportion of the height of the UI
+ container.
+ui.menu_active (read-only)
+ A Boolean indicating whether an interactive UI element is currently active.
+ Examples include menus and slider controls.
+ui.ui_active (read/write)
+ A Boolean indicating whether UI control inputs are currently enabled.
+ui.single_step (read/write)
+ A Boolean controlling whether the emulated system should be automatically
+ paused when the next frame is drawn. This property is automatically reset
+ when the automatic pause happens.
+ui.show_fps (read/write)
+ A Boolean controlling whether the current emulation speed and frame skipping
+ settings should be displayed.
+ui.show_profiler (read/write)
+ A Boolean controlling whether profiling statistics should be displayed.
+
+
+.. _luascript-ref-driver:
+
+System driver metadata
+----------------------
+
+Provides some metadata for an emulated system.
+
+Instantiation
+~~~~~~~~~~~~~
+
+emu.driver_find(name)
+ Gets the driver metadata for the system with the specified short name, or
+ ``nil`` if no such system exists.
+manager.machine.system
+ Gets the driver metadata for the current system.
+
+Properties
+~~~~~~~~~~
+
+driver.name (read-only)
+ The short name of the system, as used on the command line, in configuration
+ files, and when searching for resources.
+driver.description (read-only)
+ The full display name for the system.
+driver.year (read-only)
+ The release year for the system. May contain question marks if not known
+ definitively.
+driver.manufacturer (read-only)
+ The manufacturer, developer or distributor of the system.
+driver.parent (read-only)
+ The short name of parent system for organisation purposes, or ``"0"`` if the
+ system has no parent.
+driver.compatible_with (read-only)
+ The short name of a system that this system is compatible with software for,
+ or ``nil`` if the system is not listed as compatible with another system.
+driver.source_file (read-only)
+ The source file where this system driver is defined. The path format
+ depends on the toolchain the emulator was built with.
+driver.rotation (read-only)
+ A string indicating the rotation applied to all screens in the system after
+ the screen orientation specified in the machine configuration is applied.
+ Will be one of ``"rot0"``, ``"rot90"``, ``"rot180"`` or ``"rot270"``.
+driver.not_working (read-only)
+ A Boolean indicating whether the system is marked as not working.
+driver.supports_save (read-only)
+ A Boolean indicating whether the system supports save states.
+driver.no_cocktail (read-only)
+ A Boolean indicating whether screen flipping in cocktail mode is
+ unsupported.
+driver.is_bios_root (read-only)
+ A Boolean indicating whether this system represents a system that runs
+ software from removable media without media present.
+driver.requires_artwork (read-only)
+ A Boolean indicating whether the system requires external artwork to be
+ usable.
+driver.clickable_artwork (read-only)
+ A Boolean indicating whether the system requires clickable artwork features
+ to be usable.
+driver.unofficial (read-only)
+ A Boolean indicating whether this is an unofficial but common user
+ modification to a system.
+driver.no_sound_hw (read-only)
+ A Boolean indicating whether the system has no sound output hardware.
+driver.mechanical (read-only)
+ A Boolean indicating whether the system depends on mechanical features that
+ cannot be properly simulated.
+driver.is_incomplete (read-only)
+ A Boolean indicating whether the system is a prototype with incomplete
+ functionality.
+
+
+.. _luascript-ref-plugin:
+
+Lua plugin
+----------
+
+Provides a description of an available Lua plugin.
+
+Instantiation
+~~~~~~~~~~~~~
+
+manager.plugins[name]
+ Gets the description of the Lua plugin with the specified name, or ``nil``
+ if no such plugin is available
+
+Properties
+~~~~~~~~~~
+
+plugin.name (read-only)
+ The short name of the plugin, used in configuration and when accessing the
+ plugin programmatically.
+plugin.description (read-only)
+ The display name for the plugin.
+plugin.type (read-only)
+ The plugin type. May be ``"plugin"`` for user-loadable plugins, or
+ ``"library"`` for libraries providing common functionality to multiple
+ plugins.
+plugin.directory (read-only)
+ The path to the directory containing the plugin’s files.
+plugin.start (read-only)
+ A Boolean indicating whether the plugin enabled.