diff options
author | 2020-11-26 13:47:02 +1100 | |
---|---|---|
committer | 2020-11-26 13:47:02 +1100 | |
commit | e8998a9236992afa5c1fa4a41beaad534209faf9 (patch) | |
tree | fa0ed2d8697d32d8d5033d35ceaa5fe92cc864d9 /docs/source/techspecs/luaengine.rst | |
parent | 149a2523fe9db23120b48f2e5596219733c7a5e7 (diff) |
-luaengine_render.cpp: Work around MSVC ambiguous overload error.
-docs: Clean up a little.
* Includes typo fixes from Alexander Miller.
Diffstat (limited to 'docs/source/techspecs/luaengine.rst')
-rw-r--r-- | docs/source/techspecs/luaengine.rst | 104 |
1 files changed, 64 insertions, 40 deletions
diff --git a/docs/source/techspecs/luaengine.rst b/docs/source/techspecs/luaengine.rst index 6abde32f54c..4b9c3f0e555 100644 --- a/docs/source/techspecs/luaengine.rst +++ b/docs/source/techspecs/luaengine.rst @@ -4,41 +4,53 @@ Scripting MAME via LUA Introduction ------------ -It is now possible to externally drive MAME via LUA scripts. This feature initially appeared in version 0.148, when a minimal -``luaengine`` was implemented. Nowadays, 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. +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 ``luabridge`` to implement this feature: the idea is to transparently expose as many of the useful internals as possible. +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 you can introspect most of the objects at runtime. +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. Features -------- -The API is not yet complete, but this is a partial list of capabilities currently available to LUA scripts: +The API is not yet complete, but this is a partial list of capabilities +currently available to Lua scripts: -- machine metadata (app version, current rom, rom details) +- machine metadata (app version, current emulated system, ROM details) - machine control (starting, pausing, resetting, stopping) - machine hooks (on frame painting and on user events) -- devices introspection (device tree listing, memory and register - enumeration) -- screens introspection (screens listing, screen details, frames - counting) +- 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) - memory read/write (8/16/32/64 bits, signed and unsigned) -- registers and states control (states enumeration, get and set) +- register and state control (state enumeration, get and set) Usage ----- -MAME supports external scripting via LUA (>= 5.3) scripts, either written on the interactive console or loaded as a file. To reach the -console, just run MAME with **-console** and you will be greeted by a naked ``>`` prompt where you can input your script. +MAME supports external scripting via Lua (>= 5.3) scripts, either written on 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. -To load a whole script at once, store it in a plain text file and pass it via **-autoboot_script**. Please note that script loading may be delayed (few seconds by default), but you can override the default with the **-autoboot_delay** argument. +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 an 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 (eg. at each frame rendering). +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). Walkthrough ----------- @@ -48,12 +60,18 @@ Let's first run MAME in a terminal to reach the LUA console: :: $ mame -console YOUR_ROM - _/ _/ _/_/ _/ _/ _/_/_/_/ - _/_/ _/_/ _/ _/ _/_/ _/_/ _/ - _/ _/ _/ _/_/_/_/ _/ _/ _/ _/_/_/ - _/ _/ _/ _/ _/ _/ _/ - _/ _/ _/ _/ _/ _/ _/_/_/_/ - mame v0.217 + /| /| /| /| /| _______ + / | / | / | / | / | / / + / |/ | / | / |/ | / ____/ + / | / | / | / /_ + / |/ | / |/ __/ + / /| /| /| |/ /| /| /____ + / / | / | / | / | / | / + / _/ |/ / / |___/ |/ /_______/ + / / + / _/ + + mame 0.226 Copyright (C) Nicola Salmoria and the MAME team Lua 5.3 @@ -68,35 +86,38 @@ 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. +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.217 + mame 0.226 -We now start exploring screen related methods. First, let's enumerate available screens: +We now start exploring screen related methods. First, let's enumerate available +screens: :: - [MAME]> for i,v in pairs(manager:machine().screens) do print(i) end + [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 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: :: - [MAME]> -- let's define a shorthand for the main screen + [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 on the screen a HUD composed of lines, boxes and text: +We have several methods to draw a HUD on the screen composed of lines, boxes and +text: :: @@ -108,19 +129,22 @@ We have several methods to draw on the screen a HUD composed of lines, boxes and [MAME]>> end [MAME]> draw_hud(); -This will draw some useless art on the screen. However, when unpausing 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: +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 expected in ARGB format (32b unsigned), while screen origin (0,0) normally corresponds to the top-left corner. +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 k,v in pairs(manager:machine().devices) do print(k) end + [MAME]> for tag, device in pairs(manager:machine().devices) do print(tag) end :audiocpu :maincpu :saveram @@ -134,7 +158,7 @@ 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 + [MAME]> for k, v in pairs(cpu.state) do print(k) end D5 SP A4 @@ -151,8 +175,8 @@ On some of them, you can also inspect and manipulate memory and state: :: [MAME]> -- inspect memory - [MAME]> for k,v in pairs(cpu.spaces) do print(k) end + [MAME]> for name, space in pairs(cpu.spaces) do print(name) end program [MAME]> mem = cpu.spaces["program"] - [MAME]> print(mem:read_i8(0xC000)) + [MAME]> print(mem:read_i8(0xc000)) 41 |