Key Scripter Manual
AboutInstallationSetupUsageCreating scripts

About

Key Scripter listens to key press/release events from a keyboard or a mouse and allows to generate automated events. Supports gaming keypads, such as Nostromo SpeedPad. Allows the creation and usage of complicated key scripts for games and other applications.

Installation

On Windows:

If you downloaded the binary package of Key Scripter, simply extract the archive to your 'C:\Program Files' directory and append 'C:\Program Files\Key Scripter' to the PATH environment variable.

If you choose to compile the source files on Windows, you first need to install the latest release of MinGW (see mingw.org). After MinGW is installed on your system, append the path to the MinGW 'bin' directory to the PATH environment variable. For example, if your MinGW environment is installed in C:\MinGW, you need to append 'C:\MinGW\bin' to the PATH variable. Finally, unpack the Key Scripter source files to a directory of your choice and type the following command in the unpacked directory:

windows-build

After the program has been compiled, copy the key-scripter.exe and key-scripter.dll files to the 'C:\Program Files\Key Scripter' directory and append 'C:\Program Files\Key Scripter' to the PATH environment variable.

On Linux:

Unpack the files to a directory of your choice and type the following commands in the unpacked directory:

./configure
make

This will compile the package. After the program has been compiled, type the following command as root to install Key Scripter:

make install

To uninstall Key Scripter, type the following command:

make uninstall

Setup

Note: this chapter is for Linux users only. Windows users can skip it and go directly to Usage.

In order to listen to key events, Key Scripter reads raw data from one or more device files. You can use the following command to determine which device corresponds to your keyboard, mouse or keypad:

cat /proc/bus/input/devices

Key Scripter allows you to specify the value of the listed 'N: Name' or 'P: Phys' property instead of the actual device file name. However, it is easy to determine which device file to use by looking at the 'H: Handlers' property. For example, 'H: Handlers=kbd event2' means that you can specify /dev/input/event2 as the source file for Key Scripter:

key-scripter -i=/dev/input/event2

Because device files are dynamically created, they are not guaranteed to stay the same after a system reboot. Therefore, when starting Key Scripter from a script, it may be better to specify the input device by its name (using the value from the 'N: Name' property), instead of specifying the actual device file. Key Scripter will then automatically determine which device file it must use in order to read from the device. For example, the following line instructs Key Scripter to read from two devices with the specified names:

key-scripter -in="AT Set 2 keyboard" -in="PS/2 Logitech Mouse"

You should also be aware that normally only root can read /dev/input/event* files. This means that Key Scripter won't work if run by a regular user. You can avoid running Key Scripter as root by changing access permissions of the device file. Of course, you also need to make sure that you don't make your device file accessible to anyone.

One way to do that is to use the 'input' group, which is created during installation of Key Scripter. The install script also adds the key-scripter executable to the 'input' group and enables the 'set group ID on execution' file mode on it. All that is left for you to do after installing Key Scripter is to execute the following line, which will enable anyone in the 'input' group to read device files:

chown :input /dev/input/event* && chmod g+r /dev/input/event*

Of course, since device files are recreated each time the system is rebooted, you need to perform the above step on each system start-up. The easiest way to do that is to add the above line to one of your system start-up scripts.

Usage

Key Scripter supports the following command-line parameters:Any values specified on the command line, not equal to the supported parameters, are interpreted as configuration commands. This makes it possible to specify a configuration directly on the command line without using a file.

If no input is specified, Key Scripter will read from the standard input. This allows piping key press/release events from another program or script, instead of letting Key Scripter read directly from a device. Data read from the standard input is handled differently than raw data from a device. While a device file can only supply a press or a release event, data from the standard input may contain several more command types. Each command starts with a character identifying it, is usually followed by one or more parameters such as a positive number, and is terminated by a new-line character. The following types of commands are supported (values between {} represent a positive number):A t{scancode} command is handled exactly as the following three commands one after another: p{scancode}, s1, r{scancode}. Mouse button numbers start with 1, with 2 being the right mouse button and 3 the middle. An mc{number} command is handled exactly as the following three commands one after another: mp{number}, s1, mr{number}. Key and mouse event commands also support the following notation: p{scancode}/{milliseconds}, which is handled exactly as the following two commands one after another: s{milliseconds}, p{scancode}.

For example, the following line instructs Key Scripter to type 'hi!' on the current display:

echo t43 t31 tU0021 q | key-scripter -o

When no output is specified, Key Scripter will print key events that it would otherwise send to a display, to the standard output. Here again the same format is used as when reading from the standard input. However, only key and mouse event commands are generated.

For example, the following line instructs Key Scripter to listen to an input device and print received key events to the standard output:

On Linux:key-scripter -i=/dev/input/event2
On Windows:key-scripter -i

When no configuration file is specified, Key Scripter will pass each received key event as is, either to the specified display or, when no display is specified, to the standard output. With a configuration file available, Key Scripter will only react to those key events that are specified in the configuration. See Creating scripts to find out how to write configuration files.

Creating scripts

Many games support key scripting functionality, notably fist-person shooters. However, typically only key press events are supported while key release events are ignored. Key Scripter removes this limitation by providing support for both key event types.

When no configuration file is specified, Key Scripter simply sends a copy of each received key event to the target display or, when no display is specified, prints a command representing the event to the standard output. With a configuration however, Key Scripter checks whether an action is bound to the received key event. When a bound action is found, it is executed, otherwise the event is ignored. A configuration file can be specified using the -c command-line option (see Usage for a list of available command-line options).

Note that when Key Scripter is reading from a device, it does not consume events produced by the device. They are still processed by the system, as is the case when Key Scripter is not running. Any fake key events generated by Key Scripter will be processed by the system in addition to the real key events.

A configuration may contain bind commands, named action declarations, comments and include statements. A semicolon may be used to separate commands for better readability. A single-line comment is text starting with a '#' character or double slash '//', while a multi-line comment is a section of text starting with '/*' and ending with '*/' characters.

A bind command is specified by the word 'bind' followed by either a key event or a mouse event specification, and ends with a specification of an action. A key event starts with either a 'p' or an 'r' character, depending on whether it represents a press or a release event respectively, and ends with the scan code of the key. Similarly, a mouse event starts with either 'mp' or 'mr' characters, representing a press or a release event respectively, and ends with the button number. Mouse button numbers start with 1, with 2 being the right mouse button and 3 the middle. Mouse wheel events are specified with either mwf or mwb, representing a forward or a backward rotation event respectively. The following example instructs Key Scripter to press the 'p' key for 1 second when the 'q' key is released:

bind p24 { /* ignored */ }
bind r24 { p33; s1000; r33 } // press 'p' for 1 second when 'q' is released

Bind commands also support a wildcard notation, such as bind p* or bind r*. Such binds will catch events not currently bound to an action.

An action may either contain a single command, contain multiple commands to be executed one after another, or be empty. An empty action or an action containing multiple commands must be surrounded by curly brackets. The brackets may be omitted for an action with a single command, such as shown in the following example:

bind p24 p33 // press 'p' when 'q' is pressed
bind r24 r33 // release 'p' when 'q' is released

Named actions are declared with the set command. A set command is specified by the word 'set' followed by the name of a new or an existing action and ends with a specification of an action. The name of an action may contain the following characters: a-z, A-Z, 0-9, _, -, +. A named action can be executed from within another action by specifying its name with a '$' character prepended to it:

bind r24 $press_p // execute the 'press_p' action when 'q' is released
set press_p { p33; s1000; r33; $something_else } // press 'p' for 1 second and then execute the 'something_else' action
set something_else { /* does nothing */ } // executed by the 'press_p' action

Actions may span multiple lines and include an arbitrary number of spaces:

set example_action
{
p24 // press 'q'
s50 // wait for 50 milliseconds
r24 // release 'q'

set example_action // modifies itself
{
p33 // press 'p'
s50 // wait for 50 milliseconds
r33 // release 'p'
}
}

Both the set and the bind commands can be used to dynamically declare an action or bind an action to a key during execution of Key Scripter. This allows creation of complicated scripts that can modify current key bindings or action declarations while processing received events.

When a set command is followed by the word 'true' or 'false' instead of an action, it sets a boolean variable with the specified name to either a true or a false value:

bind p37 { set left_ctrl_is_pressed true }
bind r37 { set left_ctrl_is_pressed false }
bind p50 { set left_shift_is_pressed true }
bind r50 { set left_shift_is_pressed false }

Such boolean variables may then be used in an if command:

bind p33 { if left_ctrl_is_pressed and left_shift_is_pressed { /* do something on ctrl+shift+p */ } }

The initial value of a boolean variable is false. Boolean variables may be chained together with an 'and' or an 'or' word to create a condition containing multiple variables. If a boolean variable is preceded by an '!' character, its value is inverted. An if statement may optionally be followed by an else statement.

The set {name} {true|false} command also support the following notation: set {name} {true|false}/{milliseconds}. When this notation is used, the value of the boolean variable will be automatically inverted after the specified number of milliseconds. This notation is useful for detecting keystrokes pressed one after another:

bind r37 set ctrl_released_within_last_second true/1000 // when 'ctrl' is released, set the flag to true for one second
bind p38 if ctrl_released_within_last_second $process-ctrl-a // when 'a' is pressed after ctrl, execute the specified action

More command types are supported when specified within an action. The following is a list of all supported commands:A t{scancode} command is handled exactly as the following three commands one after another: p{scancode}, s1, r{scancode}. An mc{number} command is handled exactly as the following three commands one after another: mp{number}, s1, mr{number}. Key and mouse event commands also support the following notation: p{scancode}/{milliseconds}, which is handled exactly as the following two commands one after another: s{milliseconds}, p{scancode}.

If a configuration file becomes too long, it may be better to split it into several smaller files. These smaller files can then be combined into a single configuration by specifying all or some of them in a master configuration file using include statements. Creating a special configuration per application becomes easier this way, because such a configuration doesn't need to contain a full copy of each script, it can simply point to the file the script is defined in.

An include statement is specified by the word 'include' followed by the name of the configuration file surrounded by double quotes. If the file name contains a relative path or doesn't specify any path at all, it is considered relative to the parent configuration file. The following is an example of an include statement:

include "file name"

When loading a configuration file, Key Scripter stops if a syntax error is encountered. The line and column number of the invalid content is printed to the standard error output. However, even when loaded successfully, a complex configuration file may still contain errors that are only visible during execution of Key Scripter. In order to simplify searching for such hard-to-find errors, Key Scripter provides the -d command-line option (see Usage for a list of available command-line options). When this option is enabled, Key Scripter prints debug messages to the standard error output, describing each executed command and informing when each executed named action begins or ends.

Copyright (c) 2020 Crolix Software