diff options
author | 2021-10-24 05:48:05 +1100 | |
---|---|---|
committer | 2021-10-24 05:48:05 +1100 | |
commit | 669b1f6adecfd940d5ae8b97150dc73db04894c5 (patch) | |
tree | 3b32a4f2d55f558be04294ebe818c8f35135ef8b /docs/source/plugins | |
parent | 3a11f9168703f33f2f066c3e9d0f6905f2c95453 (diff) |
-docs: Started documenting plugins.
* Also added a couple of missing command-line options, and added a local
table of contents to the (rather long) command line options page.
-Added a separate CI target for localisation updates that produces an
artefact, and removed the message catalogs from the trigger paths for
the Linux CI build.
Diffstat (limited to 'docs/source/plugins')
-rw-r--r-- | docs/source/plugins/autofire.rst | 109 | ||||
-rw-r--r-- | docs/source/plugins/console.rst | 9 | ||||
-rw-r--r-- | docs/source/plugins/data.rst | 54 | ||||
-rw-r--r-- | docs/source/plugins/discord.rst | 10 | ||||
-rw-r--r-- | docs/source/plugins/dummy.rst | 9 | ||||
-rw-r--r-- | docs/source/plugins/gdbstub.rst | 13 | ||||
-rw-r--r-- | docs/source/plugins/hiscore.rst | 19 | ||||
-rw-r--r-- | docs/source/plugins/index.rst | 72 | ||||
-rw-r--r-- | docs/source/plugins/layout.rst | 9 | ||||
-rw-r--r-- | docs/source/plugins/timer.rst | 20 |
10 files changed, 324 insertions, 0 deletions
diff --git a/docs/source/plugins/autofire.rst b/docs/source/plugins/autofire.rst new file mode 100644 index 00000000000..56adef9b66f --- /dev/null +++ b/docs/source/plugins/autofire.rst @@ -0,0 +1,109 @@ +.. _plugins-autofire: + +Autofire Plugin +=============== + +.. contents:: :local: + + +.. _plugins-autofire-intro: + +Introduction +------------ + +The autofire plugin allows you to simulate repeatedly pressing an emulated +button by holding down a key or button combination. This can help people with +certain disabilities or injuries play shooting games, and may help reduce the +risk of repetitive strain injuries (or keyboard damage). + +To configure the autofire plugin, activate the main menu (press **Tab** during +emulation by default), select **Plugin Options**, and then select **Autofire**. +Configured autofire buttons for the current system are listed, along with their +repetition rates and activation hotkeys (initially there will be no autofire +buttons configured). Select an autofire button to change settings, or choose +**Add autofire button** to set up a new autofire button. See +:ref:`plugins-autofire-settings` for details on setting up an autofire button. +You can delete an autofire button by highlighting it in the menu and pressing +the UI Clear key (Del/Delete/Forward Delete on the keyboard by default). + +Autofire settings are saved in the **autofire** folder in the plugin data +folder (see the :ref:`homepath option <mame-commandline-homepath>`). A file is +created for each system with autofire buttons configured, named according to the +system’s short name (or ROM set name), with the extension ``.cfg``. For +example, autofire settings for Super-X will be saved in the file **superx.cfg** +in the **autofire** folder in your plugin data folder. The autofire settings +are stored in JSON format. + + +.. _plugins-autofire-settings: + +Autofire buttons settings +------------------------- + +The options for adding a new autofire button or modifying an existing autofire +button are the same. + +Select **Input** to set the emulated button that you want to simulate pressing +repeatedly. Currently, only player buttons are supported. Typically you’ll set +this to the primary fire button for shooting games. This is most often *P1 +Button 1* or the equivalent for another player, but it might have have a +different name. On Konami’s Gradius games, *P1 Button 2* is the primary fire +button. + +Select **Hotkey** to set the input combination you’ll use to activate the +autofire button. This can be any combination that MAME supports for activating +a digital input. + +**On frames** and **Off frames** are the number of consecutive emulated video +frames that the emulated button will be held and released for, respectively. +Adjust the value with the UI Left/Right keys, or click the arrows. Press the UI +Clear key to reset the values to one frame. Lower values correspond to pressing +the button at a faster rate. Depending on how fast the system reads inputs, you +may need higher numbers than 1 for the system to recognise the button being +released and pressed again (e.g. 2 on frames and 2 off frames works for Alcon). +Experiment with different values to get the best effect. + +When adding a new autofire button, there is a **Cancel** option that changes to +**Create** after you set the input and hotkey. Select **Create** to finish +creating the autofire button and return to the list of autofire buttons. The +new autofire button will be added at the end of the list. Press the UI Cancel +key (Escape/Esc on the keyboard by default), or select **Cancel** before setting +the input/hotkey, to return to the previous menu without creating the new +autofire button. + +When modifying an existing autofire button, select **Done** or press the UI +Cancel key to return to the list of autofire buttons. Changes take effect +immediately. + + +.. _plugins-autofire-notes: + +Notes and potential pitfalls +---------------------------- + +Autofire buttons act as if they’re wired in parallel with MAME’s regular inputs. +This means that if you set the activation hotkey for an autofire button to a +button or key that’s also assigned to one of the emulated inputs directly, you +may get unexpected results. Using Gradius as an example: + +* Suppose you set button 1 on your controller to fire, and set an autofire + hotkey to button 1 as well. Holding the button down to shoot will not trigger + the autofire effect: the button will never be released as you’re holding the + non-autofire button 1 down. This will also happen if you set a different + button as autofire (say, button 3 in this case), and hold button 1 down while + also pressing button 3. +* If you set button 3 on your controller to autofire and assign button 3 to + powerup as well, you will trigger the powerup action every time you grab a + powerup because the powerup button is also being held down along with the + autofire button. + +It is suggested you choose input combinations for autofire hotkeys that are not +assigned to any other emulated inputs in the system. + +Autofire is not necessarily desirable in all situations. For example using +autofire in Super-X with the blue “lightning” weapon equipped at high power +levels will only produce a single beam, greatly reducing the weapon’s +effectiveness. The fire button must be held down to produce all beams. Some +shooting games (e.g. Raiden Fighters) require the primary fire button to be held +down for a charged special attack. This means it’s often necessary to have a +non-autofire input for the primary fire button assigned to play effectively. diff --git a/docs/source/plugins/console.rst b/docs/source/plugins/console.rst new file mode 100644 index 00000000000..0afdb1f796c --- /dev/null +++ b/docs/source/plugins/console.rst @@ -0,0 +1,9 @@ +.. _plugins-console: + +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. diff --git a/docs/source/plugins/data.rst b/docs/source/plugins/data.rst new file mode 100644 index 00000000000..5585fe8fd43 --- /dev/null +++ b/docs/source/plugins/data.rst @@ -0,0 +1,54 @@ +.. _plugins-data: + +Data Plugin +=========== + +The data plugin loads information from various external support files so it can +be displayed in MAME. If the plugin is enabled, info is show in the **Infos** +tab of the right-hand pane on the system and software selection menus. The info +viewer can be shown by clicking the toolbar button on the system and software +selection menus, or by choosing **External DAT View** from the main menu during +emulation (this menu item will not appear if the data plugin is not enabled, or +if no information is available for the emulated system). + +To set the folders where the data plugin looks for supported files, choose +**Configure Options** on the system selection menu, then choose +**Configure Directories**, and then choose **DATs**. You can also set the +``historypath`` option in your **ui.ini** file. + +The following files are supported: + +history.xml + From `Gaming-History <https://www.arcade-history.com/>`_ (formerly + Arcade-History) +mameinfo.dat + From `MASH’s MAMEINFO <https://mameinfo.mameworld.info/>`_ +messinfo.dat + From `progetto-SNAPS MESSINFO.dat + <https://www.progettosnaps.net/messinfo/>`_ +gameinit.dat + From `progetto-SNAPS GameInit.dat + <https://www.progettosnaps.net/gameinit/>`_ +command.dat + from `progetto-SNAPS Command.dat + <https://www.progettosnaps.net/command/>`_ +score3.htm + `Top Scores <http://replay.marpirc.net/txt/scores3.htm>`_ from + the `MAME Action Replay Page <http://replay.marpirc.net/>`_ +Japanese mameinfo.dat and command.dat + From `MAME E2J <https://e2j.net/downloads/>`_ +sysinfo.dat + From the defunct Progetto EMMA site +story.dat + From the defunct MAMESCORE site + +If you install `hi2txt <https://greatstoneex.github.io/hi2txt-doc/>`_, the data +plugin can also show high scores from non-volatile memory or saved by the +:ref:`hiscore support plugin <plugins-hiscore>` for supported games. + +Note that you can only use a single file of each type at a time. You cannot, +for example, use the English and Japanese **mameinfo.dat** files simultaneously. + +The data plugin creates a **history.db** file in the first configured DATs +folder. This file stores the information from the support files in a format +suitable for rapid loading. It uses the SQLite3 database format. diff --git a/docs/source/plugins/discord.rst b/docs/source/plugins/discord.rst new file mode 100644 index 00000000000..c3cefe22eef --- /dev/null +++ b/docs/source/plugins/discord.rst @@ -0,0 +1,10 @@ +.. _plugins-discord: + +Discord Presence Plugin +======================= + +The Dicord presence plugin works with the Discord app for Windows, macOS or +Linux to set your activity to show what you’re doing in MAME. The activity is +set to *In menu* if you’re using the system or software selection menu, +*Playing* if emulation is running, or *Paused* if emulation is paused. The +details are set to show the system name and software description if applicable. diff --git a/docs/source/plugins/dummy.rst b/docs/source/plugins/dummy.rst new file mode 100644 index 00000000000..78cc262c53e --- /dev/null +++ b/docs/source/plugins/dummy.rst @@ -0,0 +1,9 @@ +.. _plugins-dummy: + +Dummy Test Plugin +================= + +This is a sample plugin that shows how to set necessary plugin metadata, +register callbacks, and display a simple menu. It prints status messages if the +:ref:`verbose <mame-commandline-verbose>` option is on, and it adds a **Dummy** +option to the **Plugin Options** menu. diff --git a/docs/source/plugins/gdbstub.rst b/docs/source/plugins/gdbstub.rst new file mode 100644 index 00000000000..bf2fd9ce67a --- /dev/null +++ b/docs/source/plugins/gdbstub.rst @@ -0,0 +1,13 @@ +.. _plugins-gdbstub: + +GDB Stub Plugin +=============== + +The GDB stub plugin acts as a remote debugging server for the GNU debugger +(GDB). This allows you to connect to MAME and debug supported systems using +GDB. The plugin listens for connections on port 2159 on the IPv4 loopback +address (127.0.0.1). Only Intel 80386 (i386) family processors are supported. + +See the :ref:`debugger option <mame-commandline-debugger>` for another GDB +remote debugging implementation with support for more CPUs and configurable +listening ports. diff --git a/docs/source/plugins/hiscore.rst b/docs/source/plugins/hiscore.rst new file mode 100644 index 00000000000..c3ac41d15d4 --- /dev/null +++ b/docs/source/plugins/hiscore.rst @@ -0,0 +1,19 @@ +.. _plugins-hiscore: + +Hiscore Support Plugin +====================== + +The hiscore support plugin saves and restores high scores for games that did not +originally save high scores in non-volatile memory. Note that this plugin +modifies the contents of memory directly with no coordination with the emulated +software, and hence changes behaviour. This may have undesirable effects, +including broken gameplay or causing the emulated software to crash. + +The plugin includes a **hiscore.dat** file that contains the information on how +to save and restore high scores for supported systems. This file must be kept +up-to-date when system definitions change in MAME. + +High score data is saved in the **hi** folder in the working directory. A file +with a name corresponding the system short name (or ROM set name) with the +extension ``.hi``. For example, high scores for the game Moon Cresta will be +saved in the file **mooncrst.hi** in the **hi** folder. diff --git a/docs/source/plugins/index.rst b/docs/source/plugins/index.rst new file mode 100644 index 00000000000..5fbc501eec8 --- /dev/null +++ b/docs/source/plugins/index.rst @@ -0,0 +1,72 @@ +.. _plugins: + +Plugins +======= + +.. contents:: :local: + + +.. _plugins-intro: + +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 +more information about MAME’s Lua API. + + +.. _plugins-using: + +Using plugins +------------- + +To enable plugins, you need to turn on the +:ref:`plugins option <mame-commandline-plugins>`, and make sure the +:ref:`pluginspath option <mame-commandline-pluginspath>` includes the folder +where your plugins are stored. You can set the plugins option in an INI file +or on the command line. You can set the pluginspath option by selecting +**Configure Options** from the system selection menu, then selecting +**Configure Directories**, and then selecting **Plugins** (you can also set it +in an INI file or on the command line). + +Many plugins need to store settings and/or data. The +:ref:`homepath option <mame-commandline-homepath>` sets the folder where plugins +should save data (defaults to the working directory). You can change this by +selecting **Configure Options** from the system selection menu, thens selecting +**Configure Directories**, and then selecting **Plugin Data**. + +To turn individual plugins on or off, first make sure plugins are enabled, then +select **Configure Options** from the system selection menu, and then select +**Plugins**. You will need to completely exit MAME and start it again for +changes to the enabled plugins to take effect. You can also use the +:ref:`plugin option <mame-commandline-plugin>` on the command line, or change +the settings in the **plugin.ini** file. + +If an enabled plugin needs additional configuration, or if it needs to show +information, a **Plugin Options** item will appear in the main menu (accessed by +pressing **Tab** during emulation by default). + + +.. _plugins-included: + +Included plugins +---------------- + +MAME includes several plugins providing useful functionality, and serving as +sample code that you can use as a starting point when writing your own plugins. + +.. toctree:: + :titlesonly: + + autofire + console + data + discord + dummy + gdbstub + hiscore + layout + timer diff --git a/docs/source/plugins/layout.rst b/docs/source/plugins/layout.rst new file mode 100644 index 00000000000..5c57afccb7a --- /dev/null +++ b/docs/source/plugins/layout.rst @@ -0,0 +1,9 @@ +.. _plugins-layout: + +Layout Plugin +============= + +When enabled, the layout plugin allows embedded Lua scripts in layout files to +run. Built-in artwork for some machines and some external artwork packages can +use Lua scripts to provide enhanced interactive features. See :ref:`layscript` +for an introduction to layout file scripting. diff --git a/docs/source/plugins/timer.rst b/docs/source/plugins/timer.rst new file mode 100644 index 00000000000..84d803d38aa --- /dev/null +++ b/docs/source/plugins/timer.rst @@ -0,0 +1,20 @@ +Timer Plugin +============ + +The timer plugin records the total time spent emulating each combination of a +system and a software list item, as well as the number of times each combination +has been launched. To see the statistics, bring up the main menu (press **Tab** +during emulation by default), choose **Plugin Options**, and then choose +**Timer**. + +Note that this plugin records wall clock time, not emulated time. That is, it +records the real time duration elapsed while the emulation is running, according +to the host OS. This may be shorter than the elapsed emulated time if you turn +off throttling or use MAME’s “fast forward” feature, or it may be longer than +the elapsed emulated time if you pause the emulation of if the emulation is too +demanding to run at full speed. + +The statistics are stored in the file **timer.db** in the **timer** folder +inside your plugin data folder (see the +:ref:`homepath option <mame-commandline-homepath>`). The file is a SQLite3 +database. |