diff options
author | 2020-12-27 04:27:42 +1100 | |
---|---|---|
committer | 2020-12-27 04:27:42 +1100 | |
commit | a5e6f4ea8d468f8f8e50ad5199a9f8aa9a81e9f1 (patch) | |
tree | 13e47f6a7501b3a5f96d19018e26b0850d1d69ae /docs/source/techspecs | |
parent | c2f698a95f80512d8fd461bdabf3868cb8edc0c4 (diff) |
Expose a couple more things to Lua so the plugins can show the actual key mapped to UI clear.
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r-- | docs/source/techspecs/luaengine.rst | 31 | ||||
-rw-r--r-- | docs/source/techspecs/luareference.rst | 34 |
2 files changed, 45 insertions, 20 deletions
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst index d133ce1f51a..5d3565af214 100644 --- a/docs/source/techspecs/luaengine.rst +++ b/docs/source/techspecs/luaengine.rst @@ -35,25 +35,28 @@ Features The API is not yet complete, but this is a partial list of capabilities currently available to Lua scripts: -- machine metadata (app version, current emulated system, ROM details) -- machine control (starting, pausing, resetting, stopping) -- machine hooks (on frame painting and on user events) +- 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 HUD drawing (text, lines, boxes on multiple screens) +- 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 (>= 5.3) scripts, either written on the +MAME supports external scripting via Lua (>= 5.3) 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 -by a ``[MAME]>`` prompt where you can enter your script. +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 @@ -71,7 +74,7 @@ hooks to be invoked on specific events (e.g. at each frame rendering). Walkthrough ----------- -Let's first run MAME in a terminal to reach the Lua console: +Let’s first run MAME in a terminal to reach the Lua console: :: @@ -95,14 +98,14 @@ Let's first run MAME in a terminal to reach the Lua console: [MAME]> -At this point, your game is probably running in demo mode, let's pause it: +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 +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: @@ -120,10 +123,12 @@ screens: [MAME]> for tag, screen in pairs(manager.machine.screens) do print(tag) end :screen -``manager.machine`` is the root object of your currently running machine: we -will be using this often. ``screens`` is a table with all available screens; -most machines only have one main screen. In our case, the main and only screen -is tagged as ``:screen``, and we can further inspect it: +``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: :: diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst index eacbdd0a05f..d15c74efe0b 100644 --- a/docs/source/techspecs/luareference.rst +++ b/docs/source/techspecs/luareference.rst @@ -1557,17 +1557,37 @@ 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 port 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_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 I/O port group for the specified I/O port type and player - number. The I/O port type is an enumerated value. The player number is a - zero-based index. Returns an integer giving the grouping for the input. + 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 input sequence for the specified input type, player and - sequence type. The sequence type must be ``"standard"``, ``"increment"`` - or ``"decrement"``. This provides access to general input configuration. +ioport:type_seq(type, [player], [seqtype]) + Get the configured input sequence for the specified input type, player + number and sequence type. 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. 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 configuration. +ioport:token_to_input_type(string) + Returns the input type and player number for the specified input type token. +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 ^^^^^^^^^^ |