Lua Core Classes — MAME Documentation 0.287 documentation

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

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

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

machine:side_effects_disabled()

  Returns a Boolean indicating whether side effects are disabled.

### 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.volume (read/write)

  The output volume in decibels. Should generally be a negative 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.