diff options
author | 2023-07-06 09:52:10 +1000 | |
---|---|---|
committer | 2023-07-06 09:52:10 +1000 | |
commit | 12623c3fd35984f75e31144126689986af657a30 (patch) | |
tree | 8b8b01669ab168705148152e3f4a3622945dd04c /docs/source/luascript/ref-common.rst | |
parent | 737af4b6655d1de338895272bfeeec8bb7b7b17f (diff) |
docs: Moved Lua API reference to its own section - the page was far too long.
Diffstat (limited to 'docs/source/luascript/ref-common.rst')
-rw-r--r-- | docs/source/luascript/ref-common.rst | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/docs/source/luascript/ref-common.rst b/docs/source/luascript/ref-common.rst new file mode 100644 index 00000000000..a68a832b88f --- /dev/null +++ b/docs/source/luascript/ref-common.rst @@ -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. |