Sprinter/mame
2
0
Fork 0
mirror of https://github.com/holub/mame synced 2025-04-16 05:24:54 +03:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs: Moved Lua API reference to its own section - the page was far too long.

Browse Source
This commit is contained in:
Vas Crabb 2023-07-06 09:52:10 +10:00
parent 737af4b665
commit 12623c3fd3
15 changed files with 4712 additions and 4613 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/source/index.rst
View File

@ -26,6 +26,7 @@ MAME Documentation
advanced/index
debugger/index
luascript/index
tools/index
contributing/index

235
docs/source/luascript/index.rst Normal file
View File

@ -0,0 +1,235 @@
.. _luascript:
Lua Scripting Interface
=======================
.. contents:: :local:
.. _luascript-intro:
Introduction
------------
MAME provides Lua script bindings for a useful set of core functionality. This
feature first appeared in version 0.148, when a minimal Lua interface was
implemented. Today, the Lua interface is rich enough to let you inspect and
manipulate device state, access CPU registers, read and write memory, and draw
custom graphical overlays.
There are three ways to use MAME’s Lua scripting capabilities:
* Using the :ref:`interactive Lua console <luascript-console>`, enabled by the
:ref:`console option <mame-commandline-console>`.
* By providing a script file to run using the :ref:`-autoboot_script option
<mame-commandline-autobootscript>`. The :ref:`-autoboot_delay option
<mame-commandline-autobootdelay>` controls how long MAME waits after starting
the emulated system before running the script.
* By writing :ref:`Lua plugins <plugins>`. Several plugins are included with
MAME.
Internally, MAME makes extensive use of `Sol3 <https://github.com/ThePhD/sol2>`_
to implement Lua bindings.
The Lua API is not yet declared stable and may suddenly change without prior
notice. However, we expose methods to let you know at runtime which API version
you are running against, and most objects support some level of runtime
introspection.
.. _luascript-features:
Features
--------
The API is not yet complete, but this is a partial list of capabilities exposed
to Lua scripts:
* Session information (application version, current emulated system)
* Session control (starting, pausing, resetting, stopping)
* Event hooks (on frame painting and on user events)
* Device introspection (device tree listing, memory and register enumeration)
* Screen introspection (screens listing, screen details, frame counting)
* Screen overlay drawing (text, lines, boxes on multiple screens)
* Memory read/write (8/16/32/64 bits, signed and unsigned)
* Register and state control (state enumeration, get and set)
.. _luascript-api:
API reference
-------------
.. toctree::
:maxdepth: 2
ref-common
ref-core
ref-devices
ref-mem
ref-input
ref-render
ref-debugger
.. _luascript-console:
Interactive Lua console tutorial
--------------------------------
First run an arcade game in MAME at the command prompt with the ``-console``
and ``-window`` options to enable the Lua console:
::
$ mame -console -window YOUR_SYSTEM
/| /| /| /| /| _______
/ | / | / | / | / | / /
/ |/ | / | / |/ | / ____/
/ | / | / | / /_
/ |/ | / |/ __/
/ /| /| /| |/ /| /| /____
/ / | / | / | / | / | /
/ _/ |/ / / |___/ |/ /_______/
/ /
/ _/
mame 0.255
Copyright (C) Nicola Salmoria and the MAME team
Lua 5.4
Copyright (C) Lua.org, PUC-Rio
[MAME]>
At this point, your game is probably running in attract mode. Let’s pause it:
::
[MAME]> emu.pause()
[MAME]>
Even without textual feedback on the console, you’ll notice the game is now
paused. In general, commands are quiet and only print error messages.
You can check the version of MAME you are running with:
::
[MAME]> print(emu.app_name() .. " " .. emu.app_version())
mame 0.255
Let’s examine the emulated screens. First, enumerate the :ref:`screen devices
<luascript-ref-screendev>` in the system:
::
[MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end
:screen
``manager.machine`` is the :ref:`running machine <luascript-ref-machine>` object
for the current emulation session. We will be using this frequently.
``screens`` is a :ref:`device enumerator <luascript-ref-devenum>` that yields
all emulated screens in the system. Most arcade games only have one main
screen. In our case, the main and only screen has the absolute tag ``:screen``.
We can examine it further:
::
[MAME]> -- keep a reference to the main screen in a variable
[MAME]> s = manager.machine.screens[':screen']
[MAME]> print(s.width .. 'x' .. s.height)
320x224
Several methods are available for drawing an overlay on the screen using lines,
rectangles and text:
::
[MAME]> -- define a function for drawing an overlay and call it
[MAME]> function draw_overlay()
[MAME]>> s:draw_text(40, 40, 'foo') -- (x0, y0, msg)
[MAME]>> s:draw_box(20, 20, 80, 80, 0xff00ffff, 0) -- (x0, y0, x1, y1, line-color, fill-color)
[MAME]>> s:draw_line(20, 20, 80, 80, 0xff00ffff) -- (x0, y0, x1, y1, line-color)
[MAME]>> end
[MAME]> draw_overlay()
This will draw some useless lines and text over the screen. However, when the
emulated system is resumed, your overlay needs to be refreshed or it will just
disappear. In order to do this, you have to register your function to be called
on every video update:
::
[MAME]> emu.register_frame_done(draw_overlay, 'frame')
All colors are specified in ARGB format (eight bits per channel). The
coordinate origin (0,0) normally corresponds to the top-left corner of the
screen.
As with screens, you can examine all the emulated devices in the running system:
::
[MAME]> for tag, device in pairs(manager.machine.devices) do print(tag) end
:audiocpu
:maincpu
:saveram
:screen
:palette
[...]
For some of them, you can also inspect and manipulate memory and state:
::
[MAME]> cpu = manager.machine.devices[':maincpu']
[MAME]> -- enumerate, read and write register state
[MAME]> for k, v in pairs(cpu.state) do print(k) end
CURPC
rPC
IR
CURFLAGS
SSR
D0
[...]
[MAME]> print(cpu.state["D0"].value)
303
[MAME]> cpu.state['D0'].value = 255
[MAME]> print(cpu.state['D0'].value)
255
::
[MAME]> -- inspect memory
[MAME]> for name, space in pairs(cpu.spaces) do print(name) end
program
cpu_space
[MAME]> mem = cpu.spaces['program']
[MAME]> print(mem:read_i8(0xc000))
41
Note that many objects support symbol completion if you type part of a method or
property name and press the Tab key:
::
[MAME]>print(mem:read_<TAB>
read_direct_i8
read_u16
read_range
read_direct_u16
read_direct_i64
read_i64
read_i32
read_direct_u64
read_i8
read_u32
read_u8
read_u64
read_direct_u32
read_direct_i16
read_direct_i32
read_direct_u8
read_i16
[MAME]>print(mem:read_direct_i8

118
docs/source/luascript/ref-common.rst Normal file
View File

@ -0,0 +1,118 @@
.. _luascript-ref-common:
Lua Common Types and Globals
============================
.. contents::
:local:
:depth: 1
.. _luascript-ref-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 over 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 over 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.
.. _luascript-ref-emu:
Emulator interface
------------------
The emulator interface ``emu`` provides access to core functionality. Many
classes are also available as properties of the emulator interface.
Methods
~~~~~~~
emu.wait(duration, …)
Yields for the specified duration in terms of emulated time. The duration
may be specified as an :ref:`attotime <luascript-ref-attotime>` or a number
in seconds. Any additional arguments are returned to the caller. Returns a
Boolean indicating whether the duration expired normally.
All outstanding calls to ``emu.wait`` will return ``false`` immediately if a
saved state is loaded or the emulation session ends. Calling this function
from callbacks that are not run as coroutines will raise an error.
emu.wait_next_update(…)
Yields until the next video/UI update. Any arguments are returned to the
caller. Calling this function from callbacks that are not run as coroutines
will raise an error.
emu.wait_next_frame(…)
Yields until the next emulated frame completes. Any arguments are returned
to the caller. Calling this function from callbacks that are not run as
coroutines will raise an error.
emu.add_machine_reset_notifier(callback)
Add a callback to receive notifications when the emulated system is reset.
Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.add_machine_stop_notifier(callback)
Add a callback to receive notifications when the emulated system is stopped.
Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.add_machine_pause_notifier(callback)
Add a callback to receive notifications when the emulated system is paused.
Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.add_machine_resume_notifier(callback)
Add a callback to receive notifications when the emulated system is resumed
after being paused. Returns a
:ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.add_machine_frame_notifier(callback)
Add a callback to receive notifications when an emulated frame completes.
Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.add_machine_pre_save_notifier(callback)
Add a callback to receive notification before the emulated system state is
saved. Returns a
:ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.add_machine_post_load_notifier(callback)
Add a callback to receive notification after the emulated system is restored
to a previously saved state. Returns a
:ref:`notifier subscription <luascript-ref-notifiersub>`.
emu.print_error(message)
Print an error message.
emu.print_warning(message)
Print a warning message.
emu.print_info(message)
Print an informational message.
emu.print_verbose(message)
Print a verbose diagnostic message (disabled by default).
emu.print_debug(message)
Print a debug message (only enabled for debug builds by default).
emu.lang_translate([context], message)
Look up a message with optional context in the current localised message
catalog. Returns the message unchanged if no corresponding localised
message is found.
emu.subst_env(string)
Substitute environment variables in a string. The syntax is dependent on
the host operating system.

635
docs/source/luascript/ref-core.rst Normal file
View File

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

451
docs/source/luascript/ref-debugger.rst Normal file
View File

@ -0,0 +1,451 @@
.. _luascript-ref-debugger:
Lua Debugger Classes
====================
Some of MAME’s core debugging features can be controlled from Lua script. The
debugger must be enabled to use the debugger features (usually by passing
``-debug`` on the command line).
.. contents::
:local:
:depth: 1
.. _luascript-ref-debugsymtable:
Symbol table
------------
Wrap’s MAME’s ``symbol_table`` class, providing named symbols that can be used
in expressions. Note that symbol tables can be created and used even when the
debugger is not enabled.
Instantiation
~~~~~~~~~~~~~
emu.symbol_table(machine)
Creates a new symbol table in the context of the specified machine,
emu.symbol_table(parent, [device])
Creates a new symbol table with the specified parent symbol table. If a
device is specified and it implements ``device_memory_interface``, it will
be used as the base for looking up address spaces and memory regions. Note
that if a device that does not implement ``device_memory_interface`` is
supplied, it will not be used (address spaces and memory regions will be
looked up relative to the root device).
emu.symbol_table(device)
Creates a new symbol table in the context of the specified device. If the
device implements ``device_memory_interface``, it will be used as the base
for looking up address spaces and memory regions. Note that if a device
that does not implement ``device_memory_interface`` is supplied, it will
only be used to determine the machine context (address spaces and memory
regions will be looked up relative to the root device).
Methods
~~~~~~~
symbols:set_memory_modified_func(cb)
Set a function to call when memory is modified via the symbol table. No
arguments are passed to the function and any return values are ignored.
Call with ``nil`` to remove the callback.
symbols:add(name, [value])
Adds a named integer symbol. The name must be a string. If a value is
supplied, it must be an integer. If a value is supplied, a read-only symbol
is added with the supplied value. If no value is supplied, a read/write
symbol is created with and initial value of zero. If a symbol entry with
the specified name already exists in the symbol table, it will be replaced.
Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
symbols:add(name, getter, [setter], [format])
Adds a named integer symbol using getter and optional setter callbacks. The
name must be a string. The getter must be a function returning an integer
for the symbol value. If supplied, the setter must be a function that
accepts a single integer argument for the new value of the symbol. A format
string for displaying the symbol value may optionally be supplied. If a
symbol entry with the specified name already exists in the symbol table, it
will be replaced.
Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
symbols:add(name, minparams, maxparams, execute)
Adds a named function symbol. The name must be a string. The minimum and
maximum numbers of parameters must be integers. If a symbol entry with the
specified name already exists in the symbol table, it will be replaced.
Returns the new :ref:`symbol entry <luascript-ref-debugsymentry>`.
symbols:find(name)
Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
specified name, or ``nil`` if there is no symbol with the specified name in
the symbol table.
symbols:find_deep(name)
Returns the :ref:`symbol entry <luascript-ref-debugsymentry>` with the
specified name, or ``nil`` if there is no symbol with the specified name in
the symbol table or any of its parent symbol tables.
symbols:value(name)
Returns the integer value of the symbol with the specified name, or zero if
there is no symbol with the specified name in the symbol table or any of its
parent symbol tables. Raises an error if the symbol with specified name is
a function symbol.
symbols:set_value(name, value)
Sets the value of the symbol with the specified name. Raises an error if
the symbol with the specified name is a read-only integer symbol or if it is
a function symbol. Has no effect if there is no symbol with the specified
name in the symbol table or any of its parent symbol tables.
symbols:memory_value(name, space, offset, size, disable_se)
Read a value from memory. Supply the name or tag of the address space or
memory region to read from, or ``nil`` to use the address space or memory
region implied by the ``space`` argument. See
:ref:`memory accesses in debugger expressions <debugger-express-mem>` for
access type specifications that can be used for the ``space`` argument.
The access size is specified in bytes, and must be 1, 2, 4 or 8. The
``disable_se`` argument specifies whether memory access side effects should
be disabled.
symbols:set_memory_value(name, space, offset, value, size, disable_se)
Write a value to memory. Supply the name or tag of the address space or
memory region to write to, or ``nil`` to use the address space or memory
region implied by the ``space`` argument. See
:ref:`memory accesses in debugger expressions <debugger-express-mem>` for
access type specifications that can be used for the ``space`` argument.
The access size is specified in bytes, and must be 1, 2, 4 or 8. The
``disable_se`` argument specifies whether memory access side effects should
be disabled.
symbols:read_memory(space, address, size, apply_translation)
Read a value from an address space. The access size is specified in bytes,
and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
the address will be translated with debug read intention. Returns a value
of the requested size with all bits set if address translation fails.
symbols:write_memory(space, address, data, size, apply_translation)
Write a value to an address space. The access size is specified in bytes,
and must be 1, 2, 4, or 8. If the ``apply_translation`` argument is true,
the address will be translated with debug write intention. The symbol
table’s memory modified function will be called after the value is written.
The value will not be written and the symbol table’s memory modified
function will not be called if address translation fails.
Properties
~~~~~~~~~~
symbols.entries[]
The :ref:`symbol entries <luascript-ref-debugsymentry>` in the symbol table,
indexed by name. The ``at`` and ``index_of`` methods have O(n) complexity;
all other supported operations have O(1) complexity.
symbols.parent (read-only)
The parent symbol table, or ``nil`` if the symbol table has no parent.
.. _luascript-ref-debugexpression:
Parsed expression
-----------------
Wraps MAME’s ``parsed_expression`` class, which represents a tokenised debugger
expression. Note that parsed expressions can be created and used even when the
debugger is not enabled.
Instantiation
~~~~~~~~~~~~~
emu.parsed_expression(symbols)
Creates an empty expression that will use the supplied
:ref:`symbol table <luascript-ref-debugsymtable>` to look up symbols.
emu.parsed_expression(symbols, string, [default_base])
Creates an expression by parsing the supplied string, looking up symbols in
the supplied :ref:`symbol table <luascript-ref-debugsymtable>`. If the
default base for interpreting integer literals is not supplied, 16 is used
(hexadecimal). Raises an :ref:`expression error
<luascript-ref-debugexpressionerror>` if the string contains syntax errors
or uses undefined symbols.
Methods
~~~~~~~
expression:set_default_base(base)
Set the default base for interpreting numeric literals. The base must be a
positive integer.
expression:parse(string)
Parse a debugger expression string. Replaces the current contents of the
expression if it is not empty. Raises an :ref:`expression error
<luascript-ref-debugexpressionerror>` if the string contains syntax errors
or uses undefined symbols. The previous content of the expression is not
preserved when attempting to parse an invalid expression string.
expression:execute()
Evaluates the expression, returning an unsigned integer result. Raises an
:ref:`expression error <luascript-ref-debugexpressionerror>` if the
expression cannot be evaluated (e.g. attempting to call a function with an
invalid number of arguments).
Properties
~~~~~~~~~~
expression.is_empty (read-only)
A Boolean indicating whether the expression contains no tokens.
expression.original_string (read-only)
The original string that was parsed to create the expression.
expression.symbols (read/write)
The :ref:`symbol table <luascript-ref-debugsymtable>` used for to look up
symbols in the expression.
.. _luascript-ref-debugsymentry:
Symbol entry
------------
Wraps MAME’s ``symbol_entry`` class, which represents an entry in a
:ref:`symbol table <luascript-ref-debugsymtable>`. Note that symbol entries
must not be used after the symbol table they belong to is destroyed.
Instantiation
~~~~~~~~~~~~~
symbols:add(name, [value])
Adds an integer symbol to a
:ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
entry.
symbols:add(name, getter, [setter], [format])
Adds an integer symbol to a
:ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
entry.
symbols:add(name, minparams, maxparams, execute)
Adds function symbol to a
:ref:`symbol table <luascript-ref-debugsymtable>`, returning the new symbol
entry.
Properties
~~~~~~~~~~
entry.name (read-only)
The name of the symbol entry.
entry.format (read-only)
The format string used to convert the symbol entry to text for display.
entry.is_function (read-only)
A Boolean indicating whether the symbol entry is a callable function.
entry.is_lval (read-only)
A Boolean indicating whether the symbol entry is an integer symbol that can
be set (i.e. whether it can be used on the left-hand side of assignment
expressions).
entry.value (read/write)
The integer value of the symbol entry. Attempting to set the value raises
an error if the symbol entry is read-only. Attempting to get or set the
value of a function symbol raises an error.
.. _luascript-ref-debugman:
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.
.. _luascript-ref-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 <luascript-ref-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 <luascript-ref-watchpoint>`.
.. _luascript-ref-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 <luascript-ref-devdebug>`.
breakpoint.enabled (read/write)
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.
.. _luascript-ref-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 <luascript-ref-devdebug>`.
watchpoint.enabled (read/write)
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.
.. _luascript-ref-debugexpressionerror:
Expression error
----------------
Wraps MAME’s ``expression_error`` class, describing an error occurring while
parsing or executing a debugger expression. Raised on errors when using
:ref:`parsed expressions <luascript-ref-debugexpression>`. Can be converted to
a string to provide a description of the error.
Properties
~~~~~~~~~~
err.code (read-only)
An implementation-dependent number representing the category of error.
Should not be displayed to the user.
err.offset (read-only)
The offset within the expression string where the error was encountered.

764
docs/source/luascript/ref-devices.rst Normal file
View File

@ -0,0 +1,764 @@
.. _luascript-ref-dev:
Lua Device Classes
==================
Several device classes and device mix-ins classes are exposed to Lua. Devices
can be looked up by tag or enumerated.
.. contents::
:local:
:depth: 1
.. _luascript-ref-devenum:
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 <luascript-ref-device>` in the system.
manager.machine.palettes
Returns a device enumerator that will iterate over
:ref:`palette devices <luascript-ref-dipalette>` in the system.
manager.machine.screens
Returns a device enumerator that will iterate over
:ref:`screen devices <luascript-ref-screendev>` in the system.
manager.machine.cassettes
Returns a device enumerator that will iterate over
:ref:`cassette image devices <luascript-ref-cassdev>` in the system.
manager.machine.images
Returns a device enumerator that will iterate over
:ref:`media image devices <luascript-ref-diimage>` in the system.
manager.machine.slots
Returns a device enumerator that will iterate over
:ref:`slot devices <luascript-ref-dislot>` in the system.
emu.device_enumerator(device, [depth])
Returns a device enumerator that will iterate over
:ref:`devices <luascript-ref-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.palette_enumerator(device, [depth])
Returns a device enumerator that will iterate over
:ref:`palette devices <luascript-ref-dipalette>` in the sub-tree starting at
the specified device. The specified device will be included if it is a
palette 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.screen_enumerator(device, [depth])
Returns a device enumerator that will iterate over
:ref:`screen devices <luascript-ref-screendev>` 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 <luascript-ref-cassdev>` 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 <luascript-ref-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 <luascript-ref-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).
.. _luascript-ref-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 <luascript-ref-memshare>` by tag relative to the
device, or ``nil`` if no such memory share exists.
device:membank(tag)
Gets a :ref:`memory bank <luascript-ref-membank>` by tag relative to the
device, or ``nil`` if no such memory bank exists.
device:memregion(tag)
Gets a :ref:`memory region <luascript-ref-memregion>` by tag relative to the
device, or ``nil`` if no such memory region exists.
device:ioport(tag)
Gets an :ref:`I/O port <luascript-ref-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 <luascript-ref-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.state[] (read-only)
The :ref:`state entries <luascript-ref-distateentry>` for devices that
expose the register state interface, indexed by symbol, or ``nil`` for other
devices. The index operator and ``index_of`` methods have O(n) complexity;
all other supported operations have O(1) complexity.
device.spaces[] (read-only)
A table of the device’s :ref:`address spaces <luascript-ref-addrspace>`,
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.
.. _luascript-ref-dipalette:
Palette device
--------------
Wraps MAME’s ``device_palette_interface`` class, which represents a device that
translates pen values to colours.
Colours are represented in alpha/red/green/blue (ARGB) format. Channel values
range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive.
Colour channel values are not pre-multiplied by the alpha value. Channel values
are packed into the bytes of 32-bit unsigned integers, in the order alpha, red,
green, blue from most-significant to least-significant byte.
Instantiation
~~~~~~~~~~~~~
manager.machine.palettes[tag]
Gets a palette device by tag relative to the root machine device, or ``nil``
if no such device exists or it is not a palette device.
Methods
~~~~~~~
palette:pen(index)
Gets the remapped pen number for the specified palette index.
palette:pen_color(pen)
Gets the colour for the specified pen number.
palette:pen_contrast(pen)
Gets the contrast value for the specified pen number. The contrast is a
floating-point number.
palette:pen_indirect(index)
Gets the indirect pen index for the specified palette index.
palette:indirect_color(index)
Gets the indirect pen colour for the specified palette index.
palette:set_pen_color(pen, color)
Sets the colour for the specified pen number. The colour may be specified
as a single packed 32-bit value; or as individual red, green and blue
channel values, in that order.
palette:set_pen_red_level(pen, level)
Sets the red channel value of the colour for the specified pen number.
Other channel values are not affected.
palette:set_pen_green_level(pen, level)
Sets the green channel value of the colour for the specified pen number.
Other channel values are not affected.
palette:set_pen_blue_level(pen, level)
Sets the blue channel value of the colour for the specified pen number.
Other channel values are not affected.
palette:set_pen_contrast(pen, factor)
Sets the contrast value for the specified pen number. The value must be a
floating-point number.
palette:set_pen_indirect(pen, index)
Sets the indirect pen index for the specified pen number.
palette:set_indirect_color(index, color)
Sets the indirect pen colour for the specified palette index. The colour
may be specified as a single packed 32-bit value; or as individual red,
green and blue channel values, in that order.
palette:set_shadow_factor(factor)
Sets the contrast value for the current shadow group. The value must be a
floating-point number.
palette:set_highlight_factor(factor)
Sets the contrast value for the current highlight group. The value must be
a floating-point number.
palette:set_shadow_mode(mode)
Sets the shadow mode. The value is the index of the desired shadow table.
Properties
~~~~~~~~~~
palette.palette (read-only)
The underlying :ref:`palette <luascript-ref-palette>` managed by the
device.
palette.entries (read-only)
The number of colour entries in the palette.
palette.indirect_entries (read-only)
The number of indirect pen entries in the palette.
palette.black_pen (read-only)
The index of the fixed black pen entry.
palette.white_pen (read-only)
The index of the fixed white pen.
palette.shadows_enabled (read-only)
A Boolean indicating whether shadow colours are enabled.
palette.highlights_enabled (read-only)
A Boolean indicating whether highlight colours are enabled.
palette.device (read-only)
The underlying :ref:`device <luascript-ref-device>`.
.. _luascript-ref-screendev:
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:`luascript-ref-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, the visible area width and visible area height.
Pixels are returned 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 emulated screen pixels,
with the origin at (0, 0). Note that emulated 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(x0, y0, x1, y1, [color])
Draws a line from (x0, y0) to (x1, y1).
Coordinates are floating-point numbers in units of emulated screen pixels,
with the origin at (0, 0). Note that emulated 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 emulated screen pixels,
with the origin at (0, 0). Note that emulated 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 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 foreground colour
is not provided, the UI text colour is used; if the background colour is not
provided, it is fully transparent.
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 <luascript-ref-rendercontainer>` used to draw the
screen.
screen.palette (read-only)
The :ref:`palette device <luascript-ref-dipalette>` used to translate pixel
values to colours, or ``nil`` if the screen uses a direct colour pixel
format.
.. _luascript-ref-cassdev:
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:`luascript-ref-device`
* :ref:`luascript-ref-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.
.. _luascript-ref-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 ``nil`` if no error
or a string describing an error if an error occurred.
image:load_software(name)
Loads a media image described in a software list. Returns ``nil`` if no
error or a string describing an error if an error occurred.
image:unload()
Unloads the mounted image.
image:create(filename)
Creates and mounts a media image file with the specified name. Returns
``nil`` if no error or a string describing an error if an error
occurred.
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 <luascript-ref-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 <luascript-ref-device>`.
.. _luascript-ref-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 <luascript-ref-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 <luascript-ref-device>`.
.. _luascript-ref-distateentry:
Device state entry
------------------
Wraps MAME’s ``device_state_entry`` class, which allows access to named
registers exposed by a :ref:`device <luascript-ref-device>`. Supports
conversion to string for display.
Instantiation
~~~~~~~~~~~~~
manager.machine.devices[tag].state[symbol]
Gets a state entry for a given device by symbol.
Properties
~~~~~~~~~~
entry.value (read/write)
The numeric value of the state entry, as either an integer or floating-point
number. Attempting to set the value of a read-only state entry raises an
error.
entry.symbol (read-only)
The state entry’s symbolic name.
entry.visible (read-only)
A Boolean indicating whether the state entry should be displayed in the
debugger register view.
entry.writeable (read-only)
A Boolean indicating whether it is possible to modify the state entry’s
value.
entry.is_float (read-only)
A Boolean indicating whether the state entry’s value is a floating-point
number.
entry.datamask (read-only)
A bit mask of the valid bits of the value for integer state entries.
entry.datasize (read-only)
The size of the underlying value in bytes for integer state entries.
entry.max_length (read-only)
The maximum display string length for the state entry.
.. _luascript-ref-imagefmt:
Media image format
------------------
Wraps MAME’s ``image_device_format`` class, which describes a media file format
supported by a :ref:`media image device <luascript-ref-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.
.. _luascript-ref-slotopt:
Slot option
-----------
Wraps MAME’s ``device_slot_interface::slot_option`` class, which represents a
child device that a :ref:`slot device <luascript-ref-dislot>` can be
configured to instantiate.
Instantiation
~~~~~~~~~~~~~
manager.machine.slots[tag].options[name]
Gets a slot option for a given :ref:`slot device <luascript-ref-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.

776
docs/source/luascript/ref-input.rst Normal file
View File

@ -0,0 +1,776 @@
.. _luascript-ref-input:
Lua Input System Classes
========================
Allows scripts to get input from the user, and access I/O ports in the emulated
system.
.. contents::
:local:
:depth: 1
.. _luascript-ref-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 type may be an enumerated value or an
:ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
enumerated value, the player number may be supplied as a zero-based index;
if the player number is not supplied, it is assumed to be zero. If the
input type is an input type entry, the player number may not be supplied
separately.
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 :ref:`input sequence <luascript-ref-inputseq>` for the
specified input type, player number and sequence type. The input type may
be an enumerated value or an
:ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
enumerated value, the player number may be supplied as a zero-based index;
if the player number is not supplied, it is assumed to be zero. If the
input type is an input type entry, the player number may not be supplied
separately. 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 assignments.
ioport:set_type_seq(type, [player], seqtype, seq)
Set the configured :ref:`input sequence <luascript-ref-inputseq>` for the
specified input type, player number and sequence type. The input type may
be an enumerated value or an
:ref:`input type <luascript-ref-inputtype>` entry. If the input type is an
enumerated value, the player number must be supplied as a zero-based index.
If the input type is an input type entry, the player number may not be
supplied separately. The sequence type must be ``"standard"``,
``"increment"`` or ``"decrement"``.
This allows general input assignments to be set.
ioport:token_to_input_type(string)
Returns the input type and player number for the specified input type token
string.
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.types[] (read-only)
Gets the supported :ref:`input types <luascript-ref-inputtype>`. Keys are
arbitrary indices. All supported operations have O(1) complexity.
ioport.ports[]
Gets the emulated :ref:`I/O ports <luascript-ref-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.
.. _luascript-ref-natkbdman:
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 <luascript-ref-natkbddev>` in
the emulated system, indexed by absolute device tag. Index get has O(n)
complexity; all other supported operations have O(1) complexity.
.. _luascript-ref-natkbddev:
Keyboard input device
---------------------
Represents a keyboard or keypad input device managed by the
:ref:`natural keyboard manager <luascript-ref-natkbdman>`. Note that this is
not a :ref:`device <luascript-ref-device>` class.
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 :ref:`device <luascript-ref-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.
.. _luascript-ref-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 <luascript-ref-ioportfield>`
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 <luascript-ref-ioportfield>` indexed by name.
.. _luascript-ref-ioportfield:
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:clear_value()
Clear programmatically overridden value and restore the field’s regular
behaviour.
field:set_input_seq(seqtype, seq)
Set the :ref:`input sequence <luascript-ref-inputseq>` 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 :ref:`input sequence <luascript-ref-inputseq>` for the
specified sequence type. This gets per-machine input assignments. The
sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
field:set_default_input_seq(seq_type, seq)
Set the default :ref:`input sequence <luascript-ref-inputseq>` for the
specified sequence type. This overrides the default input assignment for a
specific input. The sequence type must be ``"standard"``, ``"increment"``
or ``"decrement"``.
field:default_input_seq(seq_type)
Gets the default :ref:`input sequence <luascript-ref-inputseq>` for the
specified sequence type. If the default assignment is not overridden, this
returns the general input assignment for the field’s input type. 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 <luascript-ref-ioport>` that the field belongs to.
field.live (read-only)
The :ref:`live state <luascript-ref-ioportfieldlive>` 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.minvalue (read-only)
The minimum allowed value for analog fields, or ``nil`` for digital fields.
field.maxvalue (read-only)
The maximum allowed value for analog fields, or ``nil`` for digital fields.
field.sensitivity (read-only)
The sensitivity or gain for analog fields, or ``nil`` for digital 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.
.. _luascript-ref-ioportfieldlive:
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.
.. _luascript-ref-inputtype:
Input type
----------
Wraps MAME’s ``input_type_entry`` class, representing an emulated input type or
emulator UI input type. Input types are uniquely identified by the combination
of their enumerated type value and player index.
Instantiation
~~~~~~~~~~~~~
manager.machine.ioport.types[index]
Gets a supported input type.
Properties
~~~~~~~~~~
type.type (read-only)
An enumerated value representing the type of input.
type.group (read-only)
An integer giving the grouping for the input type. Should be used to
provide canonical grouping in an input configuration UI.
type.player (read-only)
The zero-based player number, or zero for non-player controls.
type.token (read-only)
The token string for the input type, used in configuration files.
type.name (read-only)
The display name for the input type.
type.is_analog (read-only)
A Boolean indicating whether the input type is analog or digital. Inputs
that only have on and off states are considered digital, while all other
inputs are considered analog, even if they can only represent discrete
values or positions.
.. _luascript-ref-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 Boolean indicating whether the supplied
:ref:`input sequence <luascript-ref-inputseq>` is currently pressed.
input:seq_clean(seq)
Remove invalid elements from the supplied
:ref:`input sequence <luascript-ref-inputseq>`. Returns the new, cleaned
input sequence.
input:seq_name(seq)
Get display text for an :ref:`input sequence <luascript-ref-inputseq>`.
input:seq_to_tokens(seq)
Convert an :ref:`input sequence <luascript-ref-inputseq>` to a token string.
This should be used when saving configuration.
input:seq_from_tokens(tokens)
Convert a token string to an
:ref:`input sequence <luascript-ref-inputseq>`. This should be used when
loading configuration.
input:axis_code_poller()
Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
obtaining an analog host input code.
input:switch_code_poller()
Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
obtaining a host switch input code.
input:keyboard_code_poller()
Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
obtaining a host switch input code that only considers keyboard input
devices.
input:axis_sequence_poller()
Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
an analog input assignment.
input:axis_sequence_poller()
Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
a digital input assignment.
Properties
~~~~~~~~~~
input.device_classes[] (read-only)
Gets a table of host
:ref:`input device classes <luascript-ref-inputdevclass>` indexed by name.
.. _luascript-ref-inputcodepoll:
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.
.. _luascript-ref-inputseqpoll:
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 :ref:`input sequence <luascript-ref-inputseq>`. 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.
.. _luascript-ref-inputseq:
Input sequence
--------------
Wraps MAME’s ``input_seq`` class, representing a combination of host inputs that
can be read or assigned to an emulated input. Input sequences can be
manipulated using :ref:`input manager <luascript-ref-inputman>` methods. Use an
:ref:`input sequence poller <luascript-ref-inputseqpoll>` to obtain an input
sequence from the user.
Instantiation
~~~~~~~~~~~~~
emu.input_seq()
Creates an empty input sequence.
emu.input_seq(seq)
Creates a copy of an existing input sequence.
Methods
~~~~~~~
seq:reset()
Clears the input sequence, removing all items.
seq:set_default()
Sets the input sequence to a single item containing the metavalue specifying
that the default setting should be used.
Properties
~~~~~~~~~~
seq.empty (read-only)
A Boolean indicating whether the input sequence is empty (contains no items,
indicating an unassigned input).
seq.length (read-only)
The number of items in the input sequence.
seq.is_valid (read-only)
A Boolean indicating whether the input sequence is a valid. To be valid, it
must contain at least one item, all items must be valid codes, all product
groups must contain at least one item that is not negated, and items
referring to absolute and relative axes must not be mixed within a product
group.
seq.is_default (read-only)
A Boolean indicating whether the input sequence specifies that the default
setting should be used.
.. _luascript-ref-inputdevclass:
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 <luascript-ref-inputdev>` in the
class. Keys are one-based indices.
.. _luascript-ref-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 <luascript-ref-inputdevitem>`, indexed
by item ID. The item ID is an enumerated value.
.. _luascript-ref-inputdevitem:
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 <luascript-ref-inputman>` with the item’s code.
item.code (read-only)
The input item’s identification code. This is used by several
:ref:`input manager <luascript-ref-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 <luascript-ref-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.
.. _luascript-ref-uiinputman:
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:reset()
Clears pending events and UI input states. Should be called when leaving a
modal state where input is handled directly (e.g. configuring an input
combination).
uiinput:find_mouse()
Returns host system mouse pointer X position, Y position, button state, and
the :ref:`render target <luascript-ref-rendertarget>` 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.

449
docs/source/luascript/ref-mem.rst Normal file
View File

@ -0,0 +1,449 @@
.. _luascript-ref-mem:
Lua Memory System Classes
=========================
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.
.. contents::
:local:
:depth: 1
.. _luascript-ref-memman:
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 <luascript-ref-memshare>` 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 <luascript-ref-membank>` 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 <luascript-ref-memregion>` 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.
.. _luascript-ref-addrspace:
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.
space:add_change_notifier(callback)
Add a callback to receive notifications for handler changes in address
space. The callback function is passed a single string as an argument,
either ``r`` if read handlers have potentially changed, ``w`` if write
handlers have potentially changed, or ``rw`` if both read and write handlers
have potentially changed.
Returns a :ref:`notifier subscription <luascript-ref-notifiersub>`.
space:install_read_tap(start, end, name, callback)
Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
will receive notifications on reads from the specified range of addresses in
the address space. The start and end addresses are inclusive. The name
must be a string, and the callback must be a function.
The callback is passed three arguments for the access offset, the data read,
and the memory access mask. The offset is the absolute offset into the
address space. To modify the data being read, return the modified value
from the callback function as an integer. If the callback does not return
an integer, the data will not be modified.
space:install_write_tap(start, end, name, callback)
Installs a :ref:`pass-through handler <luascript-ref-addrspacetap>` that
will receive notifications on write to the specified range of addresses in
the address space. The start and end addresses are inclusive. The name
must be a string, and the callback must be a function.
The callback is passed three arguments for the access offset, the data
written, and the memory access mask. The offset is the absolute offset into
the address space. To modify the data being written, return the modified
value from the callback function as an integer. If the callback does not
return an integer, the data will not be modified.
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 <luascript-ref-addrmap>` for the space or
``nil``.
.. _luascript-ref-addrspacetap:
Pass-through handler
--------------------
Tracks a pass-through handler installed in an
:ref:`address space <luascript-ref-addrspace>`. A memory pass-through handler
receives notifications on accesses to a specified range of addresses, and can
modify the data that is read or written if desired. Note that pass-through handler
callbacks are not run as coroutines.
Instantiation
~~~~~~~~~~~~~
manager.machine.devices[tag].spaces[name]:install_read_tap(start, end, name, callback)
Installs a pass-through handler that will receive notifications on reads
from the specified range of addresses in an
:ref:`address space <luascript-ref-addrspace>`.
manager.machine.devices[tag].spaces[name]:install_write_tap(start, end, name, callback)
Installs a pass-through handler that will receive notifications on writes to
the specified range of addresses in an
:ref:`address space <luascript-ref-addrspace>`.
Methods
~~~~~~~
passthrough:reinstall()
Reinstalls the pass-through handler in the address space. May be necessary
if the handler is removed due to other changes to handlers in the address
space.
passthrough:remove()
Removes the pass-through handler from the address space. The associated
callback will not be called in response to future memory accesses.
Properties
~~~~~~~~~~
passthrough.addrstart (read-only)
The inclusive start address of the address range monitored by the
pass-through handler (i.e. the lowest address that the handler will be
notified for).
passthrough.addrend (read-only)
The inclusive end address of the address range monitored by the pass-through
handler (i.e. the highest address that the handler will be notified for).
passthrough.name (read-only)
The display name for the pass-through handler.
.. _luascript-ref-addrmap:
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 <luascript-ref-addrmapentry>` in the address
map. Uses 1-based integer indices. The index operator and the ``at``
method have O(n) complexity.
.. _luascript-ref-addrmapentry:
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 <luascript-ref-memhandlerdata>` for the read handler.
entry.write (read-only)
:ref:`Additional data <luascript-ref-memhandlerdata>` 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.
.. _luascript-ref-memhandlerdata:
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``.
.. _luascript-ref-memshare:
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.
.. _luascript-ref-membank:
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.
.. _luascript-ref-memregion:
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.

1248
docs/source/luascript/ref-render.rst Normal file
View File

File diff suppressed because it is too large Load Diff

2
docs/source/plugins/console.rst
View File

@ -6,4 +6,4 @@ Console Plugin
The console plugin provides functionality for MAME’s interactive Lua console.
It is not used directly. Use the
:ref:`console option <mame-commandline-console>` to activate the interactive Lua
console. See :ref:`luaengine` for more information about MAME’s Lua API.
console. See :ref:`luascript` for more information about MAME’s Lua API.

2
docs/source/plugins/index.rst
View File

@ -14,7 +14,7 @@ Introduction
MAME supports plugins that can provide additional functionality. Plugins
have been written to communicate with external programs, play games
automatically, display internal game structures like hitboxes, provide alternate
user interfaces, and automatically test emulation. See :ref:`luaengine` for
user interfaces, and automatically test emulation. See :ref:`luascript` for
more information about MAME’s Lua API.

2
docs/source/techspecs/index.rst
View File

@ -18,7 +18,5 @@ MAME’s source or working on scripts that run within the MAME framework.
memory
floppy
nscsi
luaengine
luareference
m6502
poly_manager

60
docs/source/techspecs/layout_script.rst
View File

@ -36,9 +36,8 @@ Practical examples
Before diving into the technical details of how it works, we’ll start with some
example layout files using Lua script for enhancement. It’s assumed that you’re
familiar with MAME’s artwork system and have a basic understanding of Lua
scripting. For details on MAME’s layout file, see :ref:`layfile`; for an
introduction to Lua scripting in MAME, see :ref:`luaengine`; for detailed
descriptions of MAME’s Lua classes, see :ref:`luareference`.
scripting. For details on MAME’s layout file, see :ref:`layfile`; for detailed
descriptions of MAME’s Lua interface, see :ref:`luascript`.
.. _layscript-examples-espial:
@ -188,19 +187,21 @@ as a function by the layout plugin when the layout file is loaded. The layout
views have been built at this point, but the emulated system has not finished
starting. In particular, it’s not safe to access inputs and outputs at this
time. The key variable in the script environment is ``file``, which gives the
script access to its layout file.
script access to its :ref:`layout file <luascript-ref-renderlayfile>`.
We supply a function to be called after tags in the layout file have been
resolved. At this point, the emulated system will have completed starting.
This function does the following tasks:
* Looks up the two I/O ports used for player input. I/O ports can be looked up
by tag relative to the device that caused the layout file to be loaded.
* Looks up the two view items used to display joystick state. Views can be
looked up by name (i.e. value of the ``name`` attribute), and items within a
view can be looked up by ID (i.e. the value of the ``id`` attribute).
* Looks up the two :ref:`I/O ports <luascript-ref-ioport>` used for player
input. I/O ports can be looked up by tag relative to the device that caused
the layout file to be loaded.
* Looks up the two :ref:`view items <luascript-ref-renderlayitem>` used to
display joystick state. Views can be looked up by name (i.e. value of the
``name`` attribute), and items within a view can be looked up by ID (i.e. the
value of the ``id`` attribute).
* Supplies a function to be called before view items are added to the render
target.
target when drawing a frame.
* Hides the warning that reminds the user to enable the layout plugin by setting
the element state for the item to 0 (the text component is only drawn when
the element state is 1).
@ -414,20 +415,20 @@ Here’s our layout file:
The layout has a ``script`` element containing the Lua script, to be called as a
function by the layout plugin when the layout file is loaded. This happens
after the layout views have been build, but before the emulated system has
finished starting. The layout file object is supplied to the script in the
``file`` variable.
finished starting. The :ref:`layout file <luascript-ref-renderlayfile>` object
is supplied to the script in the ``file`` variable.
We supply a function to be called after tags in the layout file have been
resolved. This function does the following:
* Looks up the analog axis inputs.
* Looks up the view item that draws the outline of area where the yoke position
is displayed.
* Looks up the analog axis :ref:`inputs <luascript-ref-ioport>`.
* Looks up the :ref:`view item <luascript-ref-renderlayitem>` that draws the
outline of area where the yoke position is displayed.
* Declares some variables to hold calculated values across function calls.
* Supplies a function to be called when the view’s dimensions have been
recomputed.
* Supplies a function to be called before adding view items to the render
container.
container when drawing a frame.
* Supplies functions that will supply the bounds for the animated items.
* Hides the warning that reminds the user to enable the layout plugin by setting
the element state for the item to 0 (the text component is only drawn when
@ -472,18 +473,23 @@ The layout script environment
The Lua environment is provided by the layout plugin. It’s fairly minimal, only
providing what’s needed:
* ``file`` giving the script’s layout file object. Has a ``device`` property
for obtaining the device that caused the layout file to be loaded, and a
``views`` property for obtaining the layout’s views (indexed by name).
* ``machine`` giving MAME’s current running machine.
* ``emu.render_bounds`` and ``emu.render_color`` functions for creating bounds
and colour objects.
* ``emu.print_error``, ``emu.print_info`` and ``emu.print_debug`` functions for
diagnostic output.
* Standard Lua ``pairs``, ``ipairs``, ``table.insert`` and ``table.remove``
functions for manipulating tables and other containers.
* ``file`` giving the script’s :ref:`layout file <luascript-ref-renderlayfile>`
object. Has a ``device`` property for obtaining the :ref:`device
<luascript-ref-device>` that caused the layout file to be loaded, and a
``views`` property for obtaining the layout’s :ref:`views
<luascript-ref-renderlayview>` (indexed by name).
* ``machine`` giving MAME’s current :ref:`running machine
<luascript-ref-machine>`.
* ``emu.attotime``, ``emu.render_bounds`` and ``emu.render_color`` functions for
creating :ref:`attotime <luascript-ref-attotime>`, :ref:`bounds
<luascript-ref-renderbounds>` and :ref:`colour <luascript-ref-rendercolor>`
objects.
* ``emu.print_verbose``, ``emu.print_error``, ``emu.print_warning``,
``emu.print_info`` and ``emu.print_debug`` functions for diagnostic output.
* Standard Lua ``tonumber``, ``tostring``, ``pairs`` and ``ipairs`` functions,
and ``table`` and ``string`` objects for manipulating strings, tables and
other containers.
* Standard Lua ``print`` function for text output to the console.
* Standard Lua ``string.format`` function for string formatting.
.. _layscript-events:

203
docs/source/techspecs/luaengine.rst
View File

@ -1,203 +0,0 @@
.. _luaengine:
Scripting MAME via Lua
======================
.. contents:: :local:
.. _luaengine-intro:
Introduction
------------
It is now possible to externally drive MAME via Lua scripts. This feature
initially appeared in version 0.148, when a minimal Lua engine was implemented.
Today, the Lua interface is rich enough to let you inspect and manipulate
devices’ state, access CPU registers, read and write memory, and draw a custom
HUD on screen.
Internally, MAME makes extensive use of `Sol3 <https://github.com/ThePhD/sol2>`_
to implement this feature. The idea is to transparently expose as many of the
useful internals as possible.
Finally, a warning: the Lua API is not yet declared stable and may suddenly
change without prior notice. However, we expose methods to let you know at
runtime which API version you are running against, and most of the objects
support runtime you can introspection.
.. _luaengine-features:
Features
--------
The API is not yet complete, but this is a partial list of capabilities
currently available to Lua scripts:
- session information (app version, current emulated system, ROM details)
- session control (starting, pausing, resetting, stopping)
- event hooks (on frame painting and on user events)
- device introspection (device tree listing, memory and register enumeration)
- screen introspection (screens listing, screen details, frame counting)
- screen overlay drawing (text, lines, boxes on multiple screens)
- memory read/write (8/16/32/64 bits, signed and unsigned)
- register and state control (state enumeration, get and set)
Many of the classes are documented on the
:ref:`Lua class reference <luareference>` page.
.. _luaengine-usage:
Usage
-----
MAME supports external scripting via Lua scripts, either entered at the
interactive console or loaded as a file. To reach the console, enable the
console plugin (e.g. run MAME with ``-console``) and you will be greeted
with a ``[MAME]>`` prompt where you can enter Lua script interactively.
To load a whole script at once, store it in a plain text file and pass it using
``-autoboot_script``. Please note that script loading may be delayed (a few
seconds by default), but you can override the default with the
``-autoboot_delay`` option.
To control the execution of your code, you can use a loop-based or event-based
approach. The former is not encouraged as it is resource-intensive and makes
control flow unnecessarily complex. Instead, we suggest to register custom
hooks to be invoked on specific events (e.g. at each frame rendering).
.. _luaengine-walkthrough:
Walkthrough
-----------
Let’s first run MAME in a terminal to reach the Lua console:
::
$ mame -console YOUR_SYSTEM
/| /| /| /| /| _______
/ | / | / | / | / | / /
/ |/ | / | / |/ | / ____/
/ | / | / | / /_
/ |/ | / |/ __/
/ /| /| /| |/ /| /| /____
/ / | / | / | / | / | /
/ _/ |/ / / |___/ |/ /_______/
/ /
/ _/
mame 0.254
Copyright (C) Nicola Salmoria and the MAME team
Lua 5.4
Copyright (C) Lua.org, PUC-Rio
[MAME]>
At this point, your game is probably running in demo mode, let’s pause it:
::
[MAME]> emu.pause()
[MAME]>
Even without textual feedback on the console, you’ll notice the game is now
paused. In general, commands are quiet and only print back error messages.
You can check at runtime which version of MAME you are running, with:
::
[MAME]> print(emu.app_name() .. " " .. emu.app_version())
mame 0.254
We now start exploring screen related methods. First, let's enumerate available
screens:
::
[MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end
:screen
``manager.machine`` is the :ref:`running machine <luareference-core-machine>`
object for your current emulation session. We will be using this frequently.
``screens`` is a :ref:`device enumerator <luareference-dev-enum>` that yields
all emulated screens in the system; most arcade games only have one main screen.
In our case, the main and only screen is tagged as ``:screen``, and we can
further inspect it:
::
[MAME]> -- keep a reference to the main screen in a variable
[MAME]> s = manager.machine.screens[":screen"]
[MAME]> print(s.width .. "x" .. s.height)
320x224
We have several methods to draw a HUD on the screen composed of lines, boxes and
text:
::
[MAME]> -- we define a HUD-drawing function, and then call it
[MAME]> function draw_hud()
[MAME]>> s:draw_text(40, 40, "foo") -- (x0, y0, msg)
[MAME]>> s:draw_box(20, 20, 80, 80, 0xff00ffff, 0) -- (x0, y0, x1, y1, line-color, fill-color)
[MAME]>> s:draw_line(20, 20, 80, 80, 0xff00ffff) -- (x0, y0, x1, y1, line-color)
[MAME]>> end
[MAME]> draw_hud()
This will draw some useless art on the screen. However, when resuming the game,
your HUD needs to be refreshed otherwise it will just disappear. In order to do
this, you have to register your hook to be called on every frame repaint:
::
[MAME]> emu.register_frame_done(draw_hud, "frame")
All colors are specified in ARGB format (eight bits per channel), while screen
origin (0,0) normally corresponds to the top-left corner.
Similarly to screens, you can inspect all the devices attached to a machine:
::
[MAME]> for tag, device in pairs(manager.machine.devices) do print(tag) end
:audiocpu
:maincpu
:saveram
:screen
:palette
[...]
On some of them, you can also inspect and manipulate memory and state:
::
[MAME]> cpu = manager.machine.devices[":maincpu"]
[MAME]> -- enumerate, read and write state registers
[MAME]> for k, v in pairs(cpu.state) do print(k) end
D5
SP
A4
A3
D0
PC
[...]
[MAME]> print(cpu.state["D0"].value)
303
[MAME]> cpu.state["D0"].value = 255
[MAME]> print(cpu.state["D0"].value)
255
::
[MAME]> -- inspect memory
[MAME]> for name, space in pairs(cpu.spaces) do print(name) end
program
[MAME]> mem = cpu.spaces["program"]
[MAME]> print(mem:read_i8(0xc000))
41

4379
docs/source/techspecs/luareference.rst
View File

File diff suppressed because it is too large Load Diff