Difference between revisions of "Macros"

From GIMX
Jump to: navigation, search
(File format)
 

(36 intermediate revisions by 2 users not shown)

Line 2: Line 2:
 
<translate><!--T:1-->
 
<translate><!--T:1-->
 
It's possible to configure keyboard/mouse/joystick macros: a key or button press can trigger a series of keyboard/mouse/joystick events, with timing conditions.
 
It's possible to configure keyboard/mouse/joystick macros: a key or button press can trigger a series of keyboard/mouse/joystick events, with timing conditions.
 +
 +
==File format==
 +
 +
File format is plain text UTF-8. Recommended text editors are [https://notepad-plus-plus.org/ Notepad++] on Windows and gedit on Ubuntu.
  
 
==Directory== <!--T:2-->
 
==Directory== <!--T:2-->
Line 7: Line 11:
 
<!--T:3-->
 
<!--T:3-->
 
Macros have to be defined in files saved into:
 
Macros have to be defined in files saved into:
 +
* Ubuntu: the ~/.gimx/macros directory. ~ is the home directory, and .gimx folder is hidden (in the file manager, press ctrl+h to display hidden folders).
 +
* Windows: the C:\Users\<username>\AppData\Roaming\gimx\macros directory. AppData is an hidden folder.
 +
 +
<!--T:31-->
 +
GIMX 1.12 and older
 +
<div class="mw-collapsible mw-collapsed">
 
* Ubuntu: the ~/.emuclient/macros directory. ~ is the home directory, and .emuclient folder is hidden (in the file manager, press ctrl+h to display hidden folders).
 
* Ubuntu: the ~/.emuclient/macros directory. ~ is the home directory, and .emuclient folder is hidden (in the file manager, press ctrl+h to display hidden folders).
* Windows: the C:\Users\<username>\AppData\Roaming\emuclient\macros directory.
+
* Windows: the C:\Users\<username>\AppData\Roaming\emuclient\macros directory.</div>
  
 
<!--T:22-->
 
<!--T:22-->
GIMX 0.51 and older:
+
GIMX 0.51 and older
 +
<div class="mw-collapsible mw-collapsed">
 
* Windows 32bits: the C:\Program Files\GIMX\macros directory.
 
* Windows 32bits: the C:\Program Files\GIMX\macros directory.
* Windows 64bits: the C:\Program Files (x86)\GIMX\macros directory.
+
* Windows 64bits: the C:\Program Files (x86)\GIMX\macros directory.</div>
  
 
==Syntax== <!--T:4-->
 
==Syntax== <!--T:4-->
  
<!--T:5-->
+
<!--T:5-->
MACRO <DEVICE EVENT> <ID>
+
<pre>MACRO <DEVICE EVENT> <ID> <RANGE>
<DEVICE EVENT> <ID> <VALUE>
+
<DEVICE EVENT> <ID> <VALUE>
DELAY <MS>
+
DELAY <MS>
#<COMMENT>
+
#<COMMENT></pre>
  
<!--T:6-->
+
<!--T:6-->
<DEVICE EVENT>: KEY, KEYDOWN, KEYUP, MBUTTON, MBUTTONDOWN, MBUTTONUP, JBUTTON, JBUTTONDOWN, JBUTTONUP, MAXIS, JAXIS
+
*<DEVICE EVENT>: KEYDOWN, KEYUP, MBUTTON, MBUTTONDOWN, MBUTTONUP, JBUTTON, JBUTTONDOWN, JBUTTONUP, MAXIS, JAXIS
<ID>: the event id (case sensitive) as displayed in gimx-config
+
*<ID>: the event id (case sensitive) as displayed in gimx-config
<VALUE>: the axis value (only for MAXIS and JAXIS)
+
*<VALUE>: the axis value (only for MAXIS and JAXIS)
<MS>: integer value in milliseconds
+
*<RANGE>: the axis range (only for MAXIS and JAXIS); the syntax is [min,max] with min and max in [-32768,32767]; example: [8192,16384]
<COMMENT>: a comment, not interpreted
+
*<MS>: integer value in milliseconds
 +
*<COMMENT>: a comment, not interpreted ('#' is the first character of the line)
  
 
==Commands== <!--T:7-->
 
==Commands== <!--T:7-->
Line 51: Line 63:
  
 
<!--T:29-->
 
<!--T:29-->
* MAXIS: mouse axis moved
+
* MAXIS: mouse axis moved; ID: 0 for x axis, and 1 for y axis; VALUE: positive values for right and down
ID: 0 for x axis, and 1 for y axis<br />
 
VALUE: positive values for right and down
 
  
 
<!--T:30-->
 
<!--T:30-->
* JAXIS: joystick axis moved
+
* JAXIS: joystick axis moved; ID: the axis id as displayed in gimx-config; VALUE: in [-32768 .. 32767] for centered axes, and in [0 .. 32767] for non-centered axes
ID: the axis id as displayed in gimx-config<br />
 
VALUE: in [-32768 .. 32767] for centered axes, and in [0 .. 32767] for non-centered axes
 
 
 
==Example1: rapid_fire.txt== <!--T:12-->
 
 
 
<!--T:13-->
 
MACRO MBUTTONDOWN BUTTON_LEFT
 
KEYDOWN p
 
DELAY 50
 
KEYUP p
 
DELAY 50
 
MBUTTONDOWN BUTTON_LEFT
 
 
MACRO MBUTTONUP BUTTON_LEFT
 
KEYUP p
 
MBUTTONDOWN BUTTON_LEFT
 
 
 
<!--T:14-->
 
'p' is bind to r1 in both hip fire and ADS profiles.<br />
 
'BUTTON_LEFT' is NOT bind to r1 in both hip fire and ADS profiles.
 
 
 
==Example2: recoil.txt== <!--T:27-->
 
 
 
<!--T:28-->
 
MACRO KEYDOWN o
 
MAXIS 1 25
 
KEYDOWN o
 
 
MACRO MBUTTONDOWN BUTTON_LEFT
 
KEYDOWN o
 
 
MACRO MBUTTONUP BUTTON_LEFT
 
KEYDOWN o
 
 
 
Change '25' with the value in [0..128] that cancels the recoil.
 
  
 
==Macro activation== <!--T:23-->
 
==Macro activation== <!--T:23-->
Line 99: Line 74:
  
 
<!--T:25-->
 
<!--T:25-->
It is possible to specify the macro files to be read for each configuration file.<br />
+
* '''It is possible to specify the macro files to be read for each configuration file.'''
 
This can be configured in a file named "configs.txt", located in the macros directory.<br />
 
This can be configured in a file named "configs.txt", located in the macros directory.<br />
 
Example:
 
Example:
#If config1.xml is loaded, macro1.txt is read.
+
<pre>#If config1.xml is loaded, macro1.txt is read.
config1.xml macro1.txt
+
config1.xml/macro1.txt
#If config1.xml is loaded, macro2.txt is read.
+
#If config1.xml is loaded, macro2.txt is read.
config1.xml macro2.txt
+
config1.xml/macro2.txt
#If config2.xml is loaded, macro2.txt is read.
+
#If config2.xml is loaded, macro2.txt is read.
config2.xml macro2.txt
+
config2.xml/macro2.txt</pre>
 
Lines beginning with a # are not interpreted.<br />
 
Lines beginning with a # are not interpreted.<br />
 +
Since GIMX 4.0 the separator is a slash so as to allow using file names containing spaces.<br />
  
 
<!--T:26-->
 
<!--T:26-->
It is also possible to define activation triggers within the macro definition.<br />
+
* '''It is also possible to define activation triggers within the macro definition.'''
 
The syntax is:
 
The syntax is:
TRIGGER <event>
+
<pre>TRIGGER <event></pre>
 
Example:
 
Example:
MACRO F1
+
<pre>MACRO F1
#content
+
#content
+
 
MACRO F2
+
<!--T:33-->
TRIGGER F5
+
MACRO F2
#content
+
TRIGGER F5
+
#content
MACRO F3
+
 
TRIGGER F6
+
<!--T:34-->
#content
+
MACRO F3
+
TRIGGER F6
MACRO F4
+
#content
TRIGGER F5
+
 
#content
+
<!--T:35-->
 +
MACRO F4
 +
TRIGGER F5
 +
#content</pre>
 
With GIMX 1.12 and earlier, the above example works the following way:<br />
 
With GIMX 1.12 and earlier, the above example works the following way:<br />
 
F1 remains active all the time as there is no trigger specified.<br />
 
F1 remains active all the time as there is no trigger specified.<br />
Line 134: Line 113:
 
With GIMX 2.00:<br />
 
With GIMX 2.00:<br />
 
Macros with a trigger are default inactive. To make a macro with trigger default active, add a line containing "INIT ON" after the "TRIGGER <event>" line.<br />
 
Macros with a trigger are default inactive. To make a macro with trigger default active, add a line containing "INIT ON" after the "TRIGGER <event>" line.<br />
Macros with a trigger can work with a toggle mode. This can be configured adding a line containing "TOGGLE ON" after the "TRIGGER <event>" line.<br />
+
Macros with a trigger can work with a toggle mode, which allows to activate and deactivate a macro autonomously: activating a togglable macro has no impact on other macros, and activating another macro has no impact on a togglable macro. This can be configured adding a line containing "TOGGLE YES" after the "TRIGGER <event>" line.<br />
 +
Example:
 +
<pre>MACRO F1
 +
TRIGGER 1
 +
INIT ON
 +
TOGGLE YES
 +
#content</pre>
  
 
==Notes== <!--T:15-->
 
==Notes== <!--T:15-->
Line 142: Line 127:
 
<!--T:21-->
 
<!--T:21-->
 
The delay precision depends on the controller update period:
 
The delay precision depends on the controller update period:
* sixaxis/bluetooth = 11.25ms
+
* ds3/bluetooth = 11.25ms
* sixaxis/usb      = 10ms
+
* ds3/usb      = 10ms
* 360 pad           = 8ms
+
* ds4/bluetooth = 10ms
 +
* ds4/usb      = 10ms
 +
* 360 pad       = 8ms
 +
* XOne pad      = 4ms
 
If you specify a delay that is not a multiple of the precision, the resulting delay will be the lowest multiple of the precision higher than the specified delay.<br />
 
If you specify a delay that is not a multiple of the precision, the resulting delay will be the lowest multiple of the precision higher than the specified delay.<br />
 
For example, if the precision is 11.25ms and the delay is 12ms, the resulting delay will be 22.50ms (=2*11.25ms).
 
For example, if the precision is 11.25ms and the delay is 12ms, the resulting delay will be 22.50ms (=2*11.25ms).
Line 151: Line 139:
  
 
<!--T:17-->
 
<!--T:17-->
To make a macro loop, just add a KEYDOWN or MBUTTONDOWN or JBUTTONDOWN command at the end of the macro definition.<br />
+
To make a macro loop, just add a matching KEYDOWN, MBUTTONDOWN or JBUTTONDOWN command at the end of the macro.<br />
 
Example:
 
Example:
MACRO MBUTTONDOWN BUTTON_LEFT
+
<pre>MACRO MBUTTONDOWN BUTTON_LEFT
KEYDOWN p
+
#content
DELAY 50
+
MBUTTONDOWN BUTTON_LEFT</pre>
KEYUP p
+
 
DELAY 50
+
<!--T:36-->
MBUTTONDOWN BUTTON_LEFT
 
 
The macro is triggered by pressing 'BUTTON_LEFT'.<br />
 
The macro is triggered by pressing 'BUTTON_LEFT'.<br />
 
The last command of the macro restarts the macro, creating a loop.<br />
 
The last command of the macro restarts the macro, creating a loop.<br />
Line 168: Line 155:
 
In case multiple keyboards or mice or joysticks are used, it's not possible to specify the device for which events are generated.<br />
 
In case multiple keyboards or mice or joysticks are used, it's not possible to specify the device for which events are generated.<br />
 
Events are generated for the first keyboard/mouse/joystick found in the configuration.
 
Events are generated for the first keyboard/mouse/joystick found in the configuration.
 +
 +
==Examples== <!--T:37-->
 +
 +
===Rapid fire macro=== <!--T:38-->
 +
 +
<!--T:13-->
 +
<pre>MACRO MBUTTONDOWN BUTTON_LEFT
 +
KEYDOWN p
 +
#Set delay no less than the maximum rate of fire
 +
#10 rounds per second (600 rpm)
 +
DELAY 100
 +
KEYUP p
 +
#~Do not set delay after keyup or it will negatively impact automatic weapons
 +
MBUTTONDOWN BUTTON_LEFT
 +
 +
MACRO MBUTTONUP BUTTON_LEFT
 +
MBUTTONDOWN BUTTON_LEFT
 +
#Sometimes the fire key can be stuck down after the macro ends this releases it after the macro has been terminated
 +
KEYUP p</pre>
 +
 +
<!--T:14-->
 +
In gimx-config, bind 'p' to r1 in both hip fire and ADS profiles (profiles 1 and 2).<br />
 +
DO NOT bind 'BUTTON_LEFT' to r1 in both hip fire and ADS profiles.
 +
 +
<!--T:39-->
 +
The macro is triggered by pressing the left mouse button.<br />
 +
The last command of the first macro restarts the macro, creating a loop.<br />
 +
Upon the release of the left mouse button the second macro ends the loop of the first macro.
 +
 +
===Recoil macro=== <!--T:40-->
 +
 +
<!--T:28-->
 +
<pre>MACRO KEYDOWN o
 +
MAXIS 1 25
 +
KEYDOWN o
 +
 +
<!--T:41-->
 +
MACRO MBUTTONDOWN BUTTON_LEFT
 +
KEYDOWN o
 +
 +
<!--T:42-->
 +
MACRO MBUTTONUP BUTTON_LEFT
 +
KEYDOWN o</pre>
 +
 +
<!--T:32-->
 +
Change '25' with the value that cancels the recoil.
 +
 +
===Custom button press duration===
 +
 +
Using gimx-config, replace your current binding with an unused key, for example 'p', and define the following macro:
 +
<pre>MACRO JBUTTONDOWN X
 +
KEYDOWN p
 +
DELAY Y
 +
KEYUP p</pre>
 +
Replace X with the button id, and Y with the delay value in ms (should be at least 1 report period = 1 / frequency).
 +
 
</translate>
 
</translate>

Latest revision as of 13:36, 19 January 2019

Other languages:
English • ‎français

It's possible to configure keyboard/mouse/joystick macros: a key or button press can trigger a series of keyboard/mouse/joystick events, with timing conditions.

File format

File format is plain text UTF-8. Recommended text editors are Notepad++ on Windows and gedit on Ubuntu.

Directory

Macros have to be defined in files saved into:

  • Ubuntu: the ~/.gimx/macros directory. ~ is the home directory, and .gimx folder is hidden (in the file manager, press ctrl+h to display hidden folders).
  • Windows: the C:\Users\<username>\AppData\Roaming\gimx\macros directory. AppData is an hidden folder.

GIMX 1.12 and older

  • Ubuntu: the ~/.emuclient/macros directory. ~ is the home directory, and .emuclient folder is hidden (in the file manager, press ctrl+h to display hidden folders).
  • Windows: the C:\Users\<username>\AppData\Roaming\emuclient\macros directory.

GIMX 0.51 and older

  • Windows 32bits: the C:\Program Files\GIMX\macros directory.
  • Windows 64bits: the C:\Program Files (x86)\GIMX\macros directory.

Syntax

MACRO <DEVICE EVENT> <ID> <RANGE>
<DEVICE EVENT> <ID> <VALUE>
DELAY <MS>
#<COMMENT>
  • <DEVICE EVENT>: KEYDOWN, KEYUP, MBUTTON, MBUTTONDOWN, MBUTTONUP, JBUTTON, JBUTTONDOWN, JBUTTONUP, MAXIS, JAXIS
  • <ID>: the event id (case sensitive) as displayed in gimx-config
  • <VALUE>: the axis value (only for MAXIS and JAXIS)
  • <RANGE>: the axis range (only for MAXIS and JAXIS); the syntax is [min,max] with min and max in [-32768,32767]; example: [8192,16384]
  • <MS>: integer value in milliseconds
  • <COMMENT>: a comment, not interpreted ('#' is the first character of the line)

Commands

  • KEYDOWN: keyboard key pressed
  • KEYUP: keyboard key released
  • KEY: KEYDOWN + DELAY 50 + KEYUP
  • MBUTTONDOWN: mouse button pressed
  • MBUTTONUP: mouse button released
  • MBUTTON: MBUTTONDOWN + DELAY 50 + MBUTTONUP
  • JBUTTONDOWN: joystick button pressed
  • JBUTTONUP: joystick button released
  • JBUTTON: JBUTTONDOWN + DELAY 50 + JBUTTONUP
  • DELAY: delay in milliseconds
  • MAXIS: mouse axis moved; ID: 0 for x axis, and 1 for y axis; VALUE: positive values for right and down
  • JAXIS: joystick axis moved; ID: the axis id as displayed in gimx-config; VALUE: in [-32768 .. 32767] for centered axes, and in [0 .. 32767] for non-centered axes

Macro activation

This section is only applicable since GIMX 1.00.

  • It is possible to specify the macro files to be read for each configuration file.

This can be configured in a file named "configs.txt", located in the macros directory.
Example:

#If config1.xml is loaded, macro1.txt is read.
config1.xml/macro1.txt
#If config1.xml is loaded, macro2.txt is read.
config1.xml/macro2.txt
#If config2.xml is loaded, macro2.txt is read.
config2.xml/macro2.txt

Lines beginning with a # are not interpreted.
Since GIMX 4.0 the separator is a slash so as to allow using file names containing spaces.

  • It is also possible to define activation triggers within the macro definition.

The syntax is:

TRIGGER <event>

Example:

MACRO F1
#content

MACRO F2
TRIGGER F5
#content

MACRO F3
TRIGGER F6
#content

MACRO F4
TRIGGER F5
#content

With GIMX 1.12 and earlier, the above example works the following way:
F1 remains active all the time as there is no trigger specified.
F2 and F4 are default active. If F6 is pressed, F3 becomes active, F2 and F4 become inactive.
With GIMX 2.00:
Macros with a trigger are default inactive. To make a macro with trigger default active, add a line containing "INIT ON" after the "TRIGGER <event>" line.
Macros with a trigger can work with a toggle mode, which allows to activate and deactivate a macro autonomously: activating a togglable macro has no impact on other macros, and activating another macro has no impact on a togglable macro. This can be configured adding a line containing "TOGGLE YES" after the "TRIGGER <event>" line.
Example:

MACRO F1
TRIGGER 1
INIT ON
TOGGLE YES
#content

Notes

Delay precision

The delay precision depends on the controller update period:

  • ds3/bluetooth = 11.25ms
  • ds3/usb = 10ms
  • ds4/bluetooth = 10ms
  • ds4/usb = 10ms
  • 360 pad = 8ms
  • XOne pad = 4ms

If you specify a delay that is not a multiple of the precision, the resulting delay will be the lowest multiple of the precision higher than the specified delay.
For example, if the precision is 11.25ms and the delay is 12ms, the resulting delay will be 22.50ms (=2*11.25ms).

Macro loop

To make a macro loop, just add a matching KEYDOWN, MBUTTONDOWN or JBUTTONDOWN command at the end of the macro.
Example:

MACRO MBUTTONDOWN BUTTON_LEFT
#content
MBUTTONDOWN BUTTON_LEFT

The macro is triggered by pressing 'BUTTON_LEFT'.
The last command of the macro restarts the macro, creating a loop.
To stop a macro loop, just press the trigger again. The macro is stopped immediately, and the state of the controller is unchanged.

Multiple keyboards/mice/joysticks

In case multiple keyboards or mice or joysticks are used, it's not possible to specify the device for which events are generated.
Events are generated for the first keyboard/mouse/joystick found in the configuration.

Examples

Rapid fire macro

MACRO MBUTTONDOWN BUTTON_LEFT
KEYDOWN p
#Set delay no less than the maximum rate of fire
#10 rounds per second (600 rpm)
DELAY 100
KEYUP p
#~Do not set delay after keyup or it will negatively impact automatic weapons
MBUTTONDOWN BUTTON_LEFT
 
MACRO MBUTTONUP BUTTON_LEFT
MBUTTONDOWN BUTTON_LEFT
#Sometimes the fire key can be stuck down after the macro ends this releases it after the macro has been terminated
KEYUP p

In gimx-config, bind 'p' to r1 in both hip fire and ADS profiles (profiles 1 and 2).
DO NOT bind 'BUTTON_LEFT' to r1 in both hip fire and ADS profiles.

The macro is triggered by pressing the left mouse button.
The last command of the first macro restarts the macro, creating a loop.
Upon the release of the left mouse button the second macro ends the loop of the first macro.

Recoil macro

MACRO KEYDOWN o
MAXIS 1 25
KEYDOWN o

MACRO MBUTTONDOWN BUTTON_LEFT
KEYDOWN o

MACRO MBUTTONUP BUTTON_LEFT
KEYDOWN o

Change '25' with the value that cancels the recoil.

Custom button press duration

Using gimx-config, replace your current binding with an unused key, for example 'p', and define the following macro:

MACRO JBUTTONDOWN X
KEYDOWN p
DELAY Y
KEYUP p

Replace X with the button id, and Y with the delay value in ms (should be at least 1 report period = 1 / frequency).