summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/plugins
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2021-10-24 05:48:05 +1100
committer Vas Crabb <vas@vastheman.com>2021-10-24 05:48:05 +1100
commit669b1f6adecfd940d5ae8b97150dc73db04894c5 (patch)
tree3b32a4f2d55f558be04294ebe818c8f35135ef8b /docs/source/plugins
parent3a11f9168703f33f2f066c3e9d0f6905f2c95453 (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.rst109
-rw-r--r--docs/source/plugins/console.rst9
-rw-r--r--docs/source/plugins/data.rst54
-rw-r--r--docs/source/plugins/discord.rst10
-rw-r--r--docs/source/plugins/dummy.rst9
-rw-r--r--docs/source/plugins/gdbstub.rst13
-rw-r--r--docs/source/plugins/hiscore.rst19
-rw-r--r--docs/source/plugins/index.rst72
-rw-r--r--docs/source/plugins/layout.rst9
-rw-r--r--docs/source/plugins/timer.rst20
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.