diff options
Diffstat (limited to 'docs/source/plugins/inputmacro.rst')
-rw-r--r-- | docs/source/plugins/inputmacro.rst | 230 |
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. |