Lua Core Classes¶

Many of MAME’s core classes used to implement an emulation session are available to Lua scripts.

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.

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.

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 running machine for the current emulation session.
manager.ui (read-only): The UI manager for the current session.
manager.options (read-only): The emulation options for the current session.
manager.plugins[] (read-only): Gets information about the Lua plugins that are present, indexed by name. The index get, at and index_of methods have O(n) complexity.

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 attotime.
machine.system (read-only): The driver metadata for the current system.
machine.parameters (read-only): The parameters manager for the current emulation session.
machine.video (read-only): The video manager for the current emulation session.
machine.sound (read-only): The sound manager for the current emulation session.
machine.output (read-only): The output manager for the current emulation session.
machine.memory (read-only): The emulated memory manager for the current session.
machine.ioport (read-only): The I/O port manager for the current emulation session.
machine.input (read-only): The input manager for the current emulation session.
machine.natkeyboard (read-only): Gets the natural keyboard manager, used for controlling keyboard and keypad input to the emulated system.
machine.uiinput (read-only): The UI input manager for the current emulation session.
machine.render (read-only): The render manager for the current emulation session.
machine.debugger (read-only): The debugger manager for the current emulation session, or nil if the debugger is not enabled.
machine.options (read-only): The user-specified options 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 device enumerator that yields all devices in the emulated system.
machine.palettes (read-only): A device enumerator that yields all palette devices in the emulated system.
machine.screens (read-only): A device enumerator that yields all screen devices in the emulated system.
machine.cassettes (read-only): A device enumerator that yields all cassette image devices in the emulated system.
machine.images (read-only): A device enumerator that yields all media image devices in the emulated system.
machine.slots (read-only): A device enumerator that yields all slot devices in the emulated system.

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 render target used to produce snapshots and video recordings.

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.

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.

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.

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 input sequence 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 options 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.

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.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.

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.