summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/plugins/inputmacro.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/plugins/inputmacro.rst')
-rw-r--r--docs/source/plugins/inputmacro.rst230
1 files changed, 230 insertions, 0 deletions
diff --git a/docs/source/plugins/inputmacro.rst b/docs/source/plugins/inputmacro.rst
new file mode 100644
index 00000000000..99f8a3448fc
--- /dev/null
+++ b/docs/source/plugins/inputmacro.rst
@@ -0,0 +1,230 @@
+.. _plugins-inputmacro:
+
+Input Macro Plugin
+==================
+
+.. contents:: :local:
+
+
+.. _plugins-inputmacro-intro:
+
+Introduction
+------------
+
+The input macro plugin allows you to trigger a sequence of emulated input
+actions with a key or button combination. This can help people with
+disabilities or injuries that make some input sequences difficult. It can also
+be used as a way to cheat in games that require rapid sequences of inputs, like
+the running events in Track & Field, or the eating minigame in Daisu-Kiss.
+
+To configure the input macro plugin, activate the main menu (press **Tab**
+during emulation by default), select **Plugin Options**, and then select **Input
+Macros**. Configured input macros for the current system are listed, along with
+their activation sequences (initially there will be no input macros configured).
+Select a macro to edit it, or choose **Add macro** to set up a new input macro.
+See :ref:`plugins-inputmacro-settings` for details on editing input macros. You
+can delete an input macro by highlighting it in the menu and pressing the UI
+Clear key (Del/Delete/Forward Delete on the keyboard by default).
+
+Input macros are saved in the **inputmacro** folder in the plugin data folder
+(see the :ref:`homepath option <mame-commandline-homepath>`). A file is created
+for each system with input macros configured, named according to the system’s
+short name (or ROM set name), with the extension ``.cfg``. For example, input
+macros for Daisu-Kiss will be saved in the file **daiskiss.cfg** in the
+**inputmacro** folder in your plugin data folder. The input macros are stored
+in JSON format.
+
+
+.. _plugins-inputmacro-settings:
+
+Editing input macros
+--------------------
+
+The options for editing input macros are the same whether you’re creating a new
+macro or editing an existing macro. Input macros consist of a sequence of
+*steps*. Each step optionally waits for a configurable delay, then activates
+one or more emulated inputs for a specified duration. You can choose what
+should happen if the activation sequence is still held when the final step of
+the macro completes: the emulated inputs can be released, the final step can be
+prolonged, or the macro can loop back to any step in the sequence.
+
+The settings in first section of the macro editing menu apply to the macro as a
+whole:
+
+* The **Name** will be used in the list of input macros, so it helps to make it
+ descriptive. Press the UI Select key (Return/Enter on the keyboard or the
+ first button on the first joystick by default) to edit the current name, or
+ press the UI Clear key to type a new name. Press the UI Select key before
+ moving to another menu item to save the new name; press the UI Cancel key
+ (Escape/Esc on the keyboard by default) to change discard the new name.
+* Select **Activation sequence** to set the key or button combination you want
+ to use to activate the macro. Keep in mind that regular input settings still
+ apply, so you probably want to use a combination that isn’t being used for any
+ other emulated input in the system.
+* Set **On release** to specify what should happen if the activation sequence is
+ released before the macro completes. When set to *Stop immediately*, any
+ emulated inputs activated by the macro will be released immediately, and no
+ further steps will be processed; when set to *Complete macro*, the macro will
+ continue to be processed until the end of the final step.
+* Set **When held** to specify what should happen if the activation sequence is
+ held after the final step of the macro completes. When set to *Release*, any
+ inputs activated by the macro will be released, and the macro will not be
+ reactivated until the activation sequence is released and pressed again; when
+ set to *Prolong step <n>* where *<n>* is the number of the final step of the
+ macro, the emulated inputs activated by the final step of the macro will
+ remain active until the activation sequence is released; when set to *Loop to
+ step <n>* where *<n>* is a step number, macro processing will return to that
+ step, including its delay, if the activation sequence is held after the final
+ step completes.
+
+Each step has delay, duration and input settings:
+
+* Set the **Delay** to the number of emulated video frame intervals to wait
+ before activating the inputs for the step. During the delay, no emulated
+ inputs will be activated by the macro. You can reset the setting to zero by
+ pressing the UI Clear key.
+* Set the **Duration** to the number of emulated video frame intervals to hold
+ the emulated inputs for the step active before moving to the next step (or
+ completing the macro in the case of the final step). You can reset the
+ setting to one frame by pressing the UI Clear key.
+* Set the **Input** settings to the emulated inputs to activate for the step.
+ Only non-toggle digital inputs are supported. Select **Add input** to set
+ multiple inputs for a step (this option will only appear after you set the
+ first input for the initially created step when creating a new macro). If
+ the step has multiple inputs, you can highlight an input on the menu and press
+ the UI Clear key to delete it (all steps must have at least one input, so you
+ can’t delete the only input for a step).
+* If the macro has multiple steps, you can select **Delete step** to delete a
+ step (this options does not appear if the macro only has a single step).
+ Remember to check that the **On release** and **When held** settings are
+ correct after deleting steps.
+
+To add a step to the macro, highlight **Add step at position** (below the
+existing steps), use the UI Left/Right keys or click the arrows to set the
+position where you’d like to insert the new step, and then press the UI Select
+key (or double-click the menu item) to add the new step. You will be prompted
+to set the first input for the new step. Remember to check the **On release**
+and **When held** settings after adding steps. The **Add step at position**
+item will only appear after you set the first input for the initially created
+step when creating a new macro.
+
+When creating a new macro, there is a **Cancel** option that changes to
+**Create** after you set the activating sequence and the first input for the
+initially created step. Select **Create** to finish creating the macro and
+return to the list of input macros. The new macro will be added at the end of
+the list. Press the UI Cancel key, or select **Cancel** before setting the
+activation sequence/input, to return to the previous menu without creating the
+new macro.
+
+When editing an existing macro, select **Done** or press the UI Cancel key to
+return to the list of input macros. Changes take effect immediately.
+
+
+.. _plugins-inputmacro-examples:
+
+Example macros
+--------------
+
+Raiden autofire
+~~~~~~~~~~~~~~~
+
+This provides player 1 autofire functionality using the space bar. The same
+thing could be achieved using the :ref:`plugins-autofire`, but this demonstrates
+a simple looping macro:
+
+* **Name**: P1 Autofire
+* **Activation sequence**: Kbd Space
+* **On release**: Stop immediately
+* **When held**: Loop to step 2
+* **Step 1**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 2
+ * **Input 1**: P1 Button 1
+* **Step 2**:
+
+ * **Delay (frames)**: 4
+ * **Duration (frames)**: 2
+ * **Input 1**: P1 Button 1
+
+The first step has no delay so that firing begins as soon as the space bar is
+pressed. The second step has sufficient delay to ensure the game recognises the
+button being pressed and released again. The second step is repeated as long as
+the space bar is held down.
+
+Track & Field sprint cheat
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This allows you to run in Konami Track & Field by holding a single button. This
+takes most of the skill (and fun) out of the game:
+
+* **Name**: P1 Sprint
+* **Activation sequence**: Kbd Shift
+* **On release**: Stop immediately
+* **When held**: Loop to step 2
+* **Step 1**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Button 1
+* **Step 2**:
+
+ * **Delay (frames)**: 1
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Button 3
+* **Step 3**:
+
+ * **Delay (frames)**: 1
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Button 1
+
+This macro rapidly alternates pressing buttons 1 and 3 – the pattern required to
+run in the game.
+
+Street Fighter II Shoryuken
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This macro allows you to perform a right-facing Shōryūken (Dragon Punch) by
+pressing a single key:
+
+* **Name**: 1P Shoryuken LP
+* **Activation sequence**: Kbd M
+* **On release**: Complete macro
+* **When held**: Prolong step 6
+* **Step 1**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Right
+* **Step 2**:
+
+ * **Delay (frames)**: 1
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Down
+* **Step 3**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Down
+ * **Input 2**: P1 Right
+* **Step 4**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Right
+* **Step 5**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Right
+ * **Input 2**: P1 Jab Punch
+* **Step 6**:
+
+ * **Delay (frames)**: 0
+ * **Duration (frames)**: 1
+ * **Input 1**: P1 Jab Punch
+
+This macro has has involves steps that activate multiple inputs. The macro will
+complete if the activation sequence is released early, allowing you to tap the
+key momentarily to perform the move. Holding the activation sequence holds down
+the attack button.