diff options
Diffstat (limited to 'docs/source/luascript/ref-core.rst')
-rw-r--r-- | docs/source/luascript/ref-core.rst | 635 |
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. |