summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r--docs/source/techspecs/luaengine.rst12
-rw-r--r--docs/source/techspecs/luareference.rst88
2 files changed, 90 insertions, 10 deletions
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst
index 5e97d4e3885..7f2ba99545a 100644
--- a/docs/source/techspecs/luaengine.rst
+++ b/docs/source/techspecs/luaengine.rst
@@ -53,9 +53,9 @@ Many of the classes are documented on the
Usage
-----
-MAME supports external scripting via Lua (>= 5.3) scripts, either entered at the
+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 ``-plugin console``) and you will be greeted
+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
@@ -78,7 +78,7 @@ Let’s first run MAME in a terminal to reach the Lua console:
::
- $ mame -console YOUR_ROM
+ $ mame -console YOUR_SYSTEM
/| /| /| /| /| _______
/ | / | / | / | / | / /
/ |/ | / | / |/ | / ____/
@@ -90,10 +90,10 @@ Let’s first run MAME in a terminal to reach the Lua console:
/ /
/ _/
- mame 0.227
+ mame 0.254
Copyright (C) Nicola Salmoria and the MAME team
- Lua 5.3
+ Lua 5.4
Copyright (C) Lua.org, PUC-Rio
[MAME]>
@@ -113,7 +113,7 @@ You can check at runtime which version of MAME you are running, with:
::
[MAME]> print(emu.app_name() .. " " .. emu.app_version())
- mame 0.227
+ mame 0.254
We now start exploring screen related methods. First, let's enumerate available
screens:
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
index ec7727916db..967fc889729 100644
--- a/docs/source/techspecs/luareference.rst
+++ b/docs/source/techspecs/luareference.rst
@@ -55,6 +55,82 @@ c:index_of(v)
value.
+.. _luareference-globals:
+
+Global objects
+--------------
+
+.. _luareference-globals-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 <luareference-core-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 <luareference-core-notifiersub>`.
+emu.add_machine_stop_notifier(callback)
+ Add a callback to receive notifications when the emulated system is stopped.
+ Returns a :ref:`notifier subscription <luareference-core-notifiersub>`.
+emu.add_machine_pause_notifier(callback)
+ Add a callback to receive notifications when the emulated system is paused.
+ Returns a :ref:`notifier subscription <luareference-core-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 <luareference-core-notifiersub>`.
+emu.add_machine_frame_notifier(callback)
+ Add a callback to receive notifications when an emulated frame completes.
+ Returns a :ref:`notifier subscription <luareference-core-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 <luareference-core-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 <luareference-core-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.
+
+
.. _luareference-core:
Core classes
@@ -1598,7 +1674,8 @@ Pass-through handler
Tracks a pass-through handler installed in an
:ref:`address space <luareference-mem-space>`. 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.
+modify the data that is read or written if desired. Note that pass-through handler
+callbacks are not run as coroutines.
Instantiation
^^^^^^^^^^^^^
@@ -3572,7 +3649,8 @@ Layout file
~~~~~~~~~~~
Wraps MAME’s ``layout_file`` class, representing the views loaded from a layout
-file for use by a render target.
+file for use by a render target. Note that layout file callbacks are not run as
+coroutines.
Instantiation
^^^^^^^^^^^^^
@@ -3616,7 +3694,8 @@ Layout view
Wraps MAME’s ``layout_view`` class, representing a view that can be displayed in
a render target. Views are created from XML layout files, which may be loaded
from external artwork, internal to MAME, or automatically generated based on the
-screens in the emulated system.
+screens in the emulated system. Note that layout view callbacks are not run as
+coroutines.
Instantiation
^^^^^^^^^^^^^
@@ -3695,7 +3774,8 @@ Layout view item
Wraps MAME’s ``layout_view_item`` class, representing an item in a view. An
item is drawn as a rectangular textured surface. The texture is supplied by an
-emulated screen or a layout element.
+emulated screen or a layout element. Note that layout view item callbacks are
+not run as coroutines.
Instantiation
^^^^^^^^^^^^^