docs/source/plugins/inputmacro.rst
.. _plugins-inputmacro:
.. contents:: :local:
.. _plugins-inputmacro-intro:
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 combinations (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). You can also delete a macro by selecting the macro to edit it and
then selecting Delete macro from the menu.
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:
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 combination 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:
Each step has delay, duration and input settings:
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 activation combination 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 Back key, or select Cancel before setting the activation combination/input, to return to the previous menu without creating the new macro.
When editing an existing macro, select Done or press the UI Back key to return to the list of input macros. Changes take effect immediately.
When editing an existing macro, select Delete macro to delete the macro. The macro will be deleted immediately when you select Delete macro without requiring additional confirmation. You can also delete a macro by highlighting it in the list of macros and pressing the UI Clear key (Del/Delete/Forward Delete on the keyboard by default).
.. _plugins-inputmacro-examples:
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 combination**: 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 combination: Kbd Shift
On release: Stop immediately
When held: Loop to step 2
Step 1:
Step 2:
Step 3:
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 combination**: 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 involves steps that activate multiple inputs. The macro will
complete if the activation combination is released early, allowing you to tap
the key momentarily to perform the move. Holding the activation sequence holds
down the attack button.
Virtua Cop Aim Off-Screen
~~~~~~~~~~~~~~~~~~~~~~~~~
This macro allows you to hold a key to simulate pointing the lightgun away from
the screen:
* **Name**: 1P Aim Off-Screen
* **Activation combination**: Kbd Alt
* **On release**: Stop immediately
* **When held**: Prolong step 1
* **Step 1**:
* **Delay (frames)**: 0
* **Duration (frames)**: 1
* **Input 1**: Lightgun X
* **Value (131-630)**: 131
* **Input 2**: Lightgun Y
* **Value (36-425)**: 36
This macro involves setting analog input values.
Invasion: The Abductors Reload
In order to reload, this game requires the lightgun to be pointed away from the
screen for about a tenth of a second before pulling the trigger, and it requires
the trigger to be held for a similar duration. This makes it unsuitable for use
with the :ref:Off-Screen Reload Helper plugin <plugins-offscreenreload>.
However, you can use a two-step macro to produce the required actions when
pressing a key or button:
Name: 1P Reload
Activation combination: Kbd Shift
On release: Complete macro
When held: Prolong step 2
Step 1:
Step 2:
This macro involves multiple steps, setting analog input values, activating multiple inputs simultaneously, and completing the macro even if the activation combination is only pressed momentarily.