Paddle Documenation

For download links and more information, visit the Paddle homepage.

Contents

Overview
 ▸ Features
Main Menu
The Editor
Gamepad Profiles Format
 ▸ Gamepad Inputs
 ▸ Outputs
 ▸ Keyboard Outputs
 ▸ Mouse Outputs
 ▸ Window Message (WM) Outputs
 ▸ Repeat Intervals
 ▸ Parameters
Game List Format
Miscellaneous
Credits
Version History

Overview

Paddle is a gamepad-to-keyboard/mouse mapper for Windows.

Its primary function is to add gamepad control to PC games that only support keyboard or mouse input. You can also use it to control web browsers, media players, and many other programs.

Features

Main Menu

While Paddle is running, a P icon is placed in your Windows taskbar. (It may be hidden sometimes. You can configure Windows to always display Paddle's icon.)

Icon

The icon is red when no recognized gamepads are connected, gray when gamepads are detected but no outputs are active, and green when outputs are active. The icon will flash when the number of gamepads or the active profile changes.

Red Icon Gray Icon Green Icon

Most features of the software are accessible from the main menu (right-click or double-click on Paddle's tray icon).

Main Menu

The Paddle sub-menu contains basic software information, a shortcut to Paddle's webpage, a shortcut to this documentation, and an option to check online for updates.

The Connected Players sub-menu will show a list of recognized gamepads and their currently assigned "Player" numbers. Choosing a gamepad will identify it (by briefly rumbling the controller, if possible).

The Gamepad Profile sub-menu lets you activate various mapping profiles. At startup, Automatic is selected. This mode will switch the active profile automatically if it detects a game configured in your Game List. You can also choose None, which is always available and acts as a profile with no outputs. (Choosing any profile besides Automatic will lock it and disable auto-switching, until you choose Automatic again from this menu.)
The Edit Profiles option will open the Profiles editor.

The Launch Game sub-menu offers quick access to any of the games you've configured with a valid executable in the Game List.
The Edit Games option will open the Game List editor.

The Exit option will deactivate all output and close the program.

The Editor

Paddle includes a simple, built-in text editor which provides useful syntax-highlighting and auto-completion for both the Gamepad Profiles and Game List files.

Profiles Editor

When editing Gamepad Profiles, the text will automatically be checked for errors each time you stop typing. Detected errors will be described in the status bar at the bottom of the window.

While typing, the auto-complete list will pop up a list of valid inputs or outputs, depending on the position in the text file. While the list is displayed, you can press the Enter or Tab keys to complete the selected word, Up and Down to change the selected word, or Escape to hide the list.

Game List Editor

When editing the Game List, auto-completion behaves in the same way, but with a shorter list of relevant keywords. The following special hotkeys are available:
Ctrl+E : browse for (and automatically insert) an executable file
Ctrl+P : select from a list (and automatically insert) a Gamepad Profile

In both editor modes, the following hotkeys are available:
Ctrl+S : save changes and close
Escape : cancel changes and close
Ctrl+W : close (prompt to save any changes)
Ctrl+D : duplicate selection (or current line)
Ctrl+L : delete current line
Ctrl+F : basic 'Find' dialog
F3 : next 'Find' result (forward)
Shift+F3 : previous 'Find' result (backward)
F1 : launch this documentation

The editor can only be open in one mode at a time. Profile output is disabled while the Gamepad Profiles editor is open.

Gamepad Profiles Format

All gamepad profiles are stored in one combined text file (Paddle_Profiles.txt) which contains profile names and mappings in this general format:

[ProfileName]
; A comment
GamepadInputs > Outputs
GamepadInputs > Outputs
...

[ProfileName]
/Parameter:Value, Parameter:Value
GamepadInputs > Outputs (RepeatInterval)
GamepadInputs > Outputs
...

A profile begins with a name between square brackets ([]).
After that, each line should contain exactly one mapping.
A mapping consists of one or more inputs, and one or more outputs, separated by a > character.

This file format is not case-sensitive.
There is no special header at the start of the file.
Blank lines and comments (text following a ; character) are ignored by the parser.

Gamepad Inputs

All input names are based on the standard Xbox 360 controller. For example, if you are using a PlayStation controller, the Cross, Circle, Square, and Triangle buttons would be called A, B, X, and Y in Paddle. See this Xbox 360 controller diagram for reference (but be aware the Guide and Connect buttons are not supported).

Button Inputs

Input buttons are always in an active or inactive state. They have no directional value.
The supported buttons are:
A, B, X, Y
Start, Back
LB, RB (the shoulder "bumpers", similar to L1 and R1 on PlayStation)
LT, RT (the back "triggers", similar to L2 and R2 on PlayStation)
LStick.Click, RStick.Click

Trigger Inputs

The left and right triggers can also be used as two analog axes:
LTrigger, RTrigger
These always have values from 0.0 (not pressed) to 1.0 (fully pressed).
They can also be treated as one combined axis:
Triggers
This combines the two triggers and has a range of -1.0 to 1.0 (negative is left, positive is right).
These are all considered "single" axes, meaning they only have one component.

Analog Stick Inputs

The left and right analog sticks have two components (horizontal and vertical).
These are considered "double" axes by Paddle:
LStick, RStick
They can be broken into individual "single" axes:
LStick.X, LStick.Y
RStick.X, RStick.Y
They can also be treated like directional buttons:
LStick.Up, LStick.Down, LStick.Left, LStick.Right
RStick.Up, RStick.Down, RStick.Left, RStick.Right

D-Pad Input

The D-Pad (directional pad) is also considered a "double" axis:
DPad
It can be broken into two "single" axes:
DPad.X, DPad.Y
It can also be treated as four separate buttons:
DPad.Up, DPad.Down, DPad.Left, DPad.Right

Other Inputs

There are also two special "double" axes:
Sticks, Axes
Sticks gets its values from LStick or RStick, whichever is currently being pressed more.
Axes gets its values from LStick, RStick, or DPad, whichever is currently being pressed most.

Inverting Inputs

All inputs can be inverted by placing a - symbol (minus) before it.
For button inputs, this means the output is activated when the input is not pressed.
Examples: -A, -Start, -RT
For axis inputs, this means the direction is inverted.
Examples: -LStick, -DPad.Y, -Triggers

Combining Inputs

You can combine inputs using the + symbol (or - symbol to combine with an inverted input).
A combination of buttons (such as A+LB or Start+Back) is considered active when all of the buttons are pressed.
If any buttons are inverted (such as LB in A-LB), they must not be pressed to activate the output.
You can combine one axis ("single" or "double") with some buttons.
For example, LB-A+LStick will map the LStick to the specified output, but only when LB is pressed and A is not pressed.
You cannot directly combine axes, such as LStick+DPad.

Listing Inputs

Finally, you can list multiple inputs (or combinations of inputs) on a single mapping line, separated by the , (comma) character. If any of the listed inputs are active, then the output will be activated.
Example: A, B+X-Y, LB+Start, RStick.Up-RT
All inputs in one list must have the same dimension (all buttons, all "single" axes, or all "double" axes).
For example, DPad.X, RStick.Y+A is valid, but DPad.X, RStick+A is not.
The built-in editor will inform you if any dimensions are mismatched.

Outputs

Outputs are specified on the right-hand side of the > symbol on a mapping line.

Like inputs, you can list multiple outputs on one mapping line using the , character.
If any of the listed inputs are active, then all of the outputs will be activated.

Output list example:

Start, LB+RB > Space, Enter

If Start is pressed or LB and RB are both pressed, then both the Space and Enter keys will be activated (see Keyboard Outputs below).

Unlike inputs, outputs generally can't be inverted (with -) or combined (with + and -), except as noted in the following sections.

Keyboard Outputs

The most basic form of output is simulated keyboard presses.
Keys are specified by name, which generally correspond to Windows Virtual Key (VK) constants.

Common keyboard outputs:
A-Z
0-9
Pad.0-Pad.9
Pad.Add, Pad.Subtract, Pad.Multiply, Pad.Divide, Pad.Decimal
F1-F24
Up, Down, Left, Right (the arrow keys)
Enter, Space, Escape
Tab, Backspace, CapsLock
Ctrl (also LCtrl and RCtrl)
Alt (also LAlt and RAlt)
Shift (also LShift and RShift)
Home, End
Insert, Delete
PageUp, PageDown
PrintScreen

Punctuation keys:
Period, Comma
Plus, Minus
Colon, Apostrophe
Slash, Backslash
OpenBracket, CloseBracket
Tilde (~)

Other valid keys:
Menu (the context menu key, "VK_APPS")
Win (the "Windows" key, also LWin and RWin)
ScrollLock, NumLock

There is a pair of "Volume" control keys:
Volume.Up, Volume.Down

There is a set of "Media" action keys:
Media.PlayPause (Play/Pause)
Media.Stop
Media.Prev, Media.Next

There is a set of "Browser" action keys:
Browser.Home
Browser.Back, Browser.Forward
Browser.Refresh, Browser.Stop
Browser.Favorites, Browser.Search

Finally, there are some special keyboard outputs which act as axes rather than buttons.
Arrows allows you to map a "double" axis to the arrow keys
Arrows.X and Arrows.Y allow you to map "single" axes to the arrow keys
WASD, WASD.X, WASD.Y allow you to map axes to the W, A, S, D keys
ESDF and IJKL can be mapped like WASD
Volume allows you to map a "single" axis to Volume.Up and Volume.Down

Keyboard axes example:

DPad > Arrows
LStick > WASD
RStick.Y > Volume

A single mapping can specify one or more keyboard outputs, but be aware that they will be activated as long as the input is active.
For example: Start > Ctrl, F could be used to toggle fullscreen in a game by triggering Ctrl and F. However, you probably don't want to hold this key combination longer than necessary. It might be better to use a key sequence output.

A key sequence is a group of keyboard outputs that are guaranteed to be pressed together and are activated briefly when you first trigger the input (even if you hold the input longer). This is useful for common hotkeys, such as "Ctrl+S" to save a file or "Alt+Enter" to toggle fullscreen.
You specify a key sequence by key names combined with + and surrounded by double quote (") characters.

Key sequence example:

Start > "Ctrl+F"
Y > "Alt+Enter"
RB+A > "Ctrl+Shift+S"

Mouse Outputs

You can map a gamepad input (typically an analog stick) to mouse movement by using the "double" axis output:
Mouse
You can also map to the individual "single" component axes:
Mouse.X, Mouse.Y
You can map to four mouse directions independently as buttons:
Mouse.Up, Mouse.Down, Mouse.Left, Mouse.Right
The mouse speed and acceleration can be adjusted (see Parameters below).

Mouse movement example:

LStick > Mouse
Triggers > Mouse.X
A > Mouse.Up

The left, right, and middle mouse buttons are mapped just like keys:
LClick, RClick, MClick

Mouse button example:

A > LClick
RStick.Click > RClick

The mouse wheel can be mapped as a "single" axis:
MouseWheel
It can also be mapped as up/down buttons, to scroll in discrete steps.
MouseWheel.Up, MouseWheel.Down

Mouse wheel example:

RStick.Y > MouseWheel
Y > MouseWheel.Up
A > MouseWheel.Down

Window Message (WM) Outputs

You can assign button inputs to post Windows API messages as outputs (see WM message list).

Currently only a small number of WM messages are supported:
WM_CLOSE
WM_LBUTTONDOWN (WM_LBUTTONUP will automatically follow)
WM_RBUTTONDOWN (WM_RBUTTONUP will automatically follow)
WM_MBUTTONDOWN (WM_MBUTTONUP will automatically follow)

Window message example:

A > WM_LBUTTONDOWN
LB + RB > WM_CLOSE

Repeat Intervals

You can configure mapped outputs to auto-repeat (as long as the inputs are held) by specifying a time interval in () parentheses at the end of a mapping line.

The time is specified in milliseconds, as a positive integer. For example, (500) will cause an output to auto-repeat twice per second, and (100) will auto-repeat ten times per second.

This can be used to auto-hit a key or auto-click the mouse rapidly, auto-scroll the mouse wheel at a desired rate, etc.

Note: The repeat interval applies to all of the listed outputs on a mapping line, not just the last one preceding the parentheses.

Auto-repeat example:

A > Enter (500)
Start > X, C (100) ; Both X and C are repeated
RStick.Up > MouseWheel.Up (750)

Parameters

In addition to regular mapping lines, a profile can contain optional parameter lines. These are extra settings which can be used to configure the profile in more detail.

A parameter line begins with a forward slash (/) and contains one or more parameters, separated by the comma (,) character. Most parameters require a numeric value, specified as a ParameterName:Value pair.

Player (also P1, P2, P3, ...)
This parameter is used for multi-player (multi-gamepad) profiles. All subsequent mappings will only apply to the specified player. The default player number is 1, and the max is 16. You can also use the valueless parameters P1, P2, etc. to achieve the same effect.
Multi-player example:

/Player:1
A > X
/P2
A > Enter

Mouse.Speed, Mouse.Accel
These parameters are used to adjust the maximum speed and acceleration of mouse movement. Both are specified as positive scaling factors, based on the default speed and acceleration (meaning a value of 1.0 is the default, 2.0 is twice as fast). These parameters apply to the entire profile and all gamepads, not just the mappings which follow.
Mouse speed/acceleration example:

/Mouse.Speed:2.0, Mouse.Accel:0.5
LStick > Mouse

Mouse.WheelSpeed This parameter affects the speed of axis inputs mapped to mousewheel scrolling output. Similar to Mouse.Speed, the value must be a positive scaling factor, with a default of 1.0.
Mousewheel speed example:

/Mouse.WheelSpeed:5.0
;/Mouse.WheelSpeed:0.25 ; Try this for comparison
RStick.Y > MouseWheel

LStick.Thresh, RStick.Thresh, Triggers.Thresh
These parameters set the axis thresholds to be used when mapping axis inputs to button (pressed or unpressed) outputs, for example LStick.Up or RT. Thresholds must be between 0.0 and 1.0, with a default of 0.75.
Axis threshold example:

/LStick.Thresh:0.9, RStick.Thresh:0.25
LStick.Up, RStick.Up > A

LStick.Dead, RStick.Dead, Triggers.Dead These parameters set the axis deadzones to be used when mapping axis inputs to axis outputs. Deadzones are the areas around the value 0.0 (axis idle position) in which slight axis movement does not register as output movement. For example, if your analog stick causes slight mouse movement when you aren't touching it, you might want to increase its deadzone above 0.20 (the default value).
Axis deadzone example:

/LStick.Dead:0.8
;/LStick.Dead:0.01 ; Try this for comparison
LStick > Mouse

Game List Format

Paddle stores a list of games in an editable text file (Paddle_Games.ini). Usage of this file is completely optional, but it provides two extra features:
(1) automatic profile activation if Paddle detects a game you have properly configured
(2) ability to quickly launch games from the Paddle tray icon menu
Paddle does not scan your filesystem for games. You must manually add them using the built-in editor or any other text editor.

The Game List follows the common ".ini" text format:

[GameName]
Exe       = C:\Path\To\Game.exe
ExeParams = -Param1 -Param2
Pattern   = *\G*e.exe | *\G?me.exe
Profile   = MyGameProfile
...

Similar to the Gamepad Profiles file, blank lines and comments (starting with ;) are ignored, and the keywords are case-insensitive.

A game entry begins with its name in [] brackets, on its own line.

This is followed by various properties, one per line. A property consists of a keyword, followed by the equals (=) character, followed by a text value. All properties are optional. You can specify any combination of relevant properties for each game you add.

Exe is the path of the game executable. If specified, the game will appear in the tray icon's Launch Game sub-menu for quick access.

ExeParams are commandline parameters that you want to pass to the executable (when launched from the tray icon menu).

Pattern is one or more file path patterns, in Windows wildcard format (* matches any characters; ? matches any single character). This is used (in addition to the Exe property) for detecting a game and automatically activating the appropriate gamepad profile. Multiple patterns can be specified, separated by the | character.

Profile is the name of the gamepad profile which should be used for this game (assuming you are running Paddle in Automatic mode).

Miscellaneous

Aborting a profile: You can deactivate the current profile by holding the special "abort" combination LB + RB + Start for 5 seconds. (This is very useful in fullscreen games, in case the wrong profile is configured, or the game already has built-in gamepad support.)

Note: This "abort" action simply activates the None profile. Paddle will not automatically switch to any other profiles unless you select Automatic from the Gamepad Profile menu again.

Saved file locations: Paddle tries to save the Gamepad Profiles and Game List to the same directory as the program itself. If it cannot save there (lacks write privileges), the files will be saved in a Paddle sub-folder within your %APPDATA% directory.

Unrecognized gamepads: Many common gamepads are recognized by Paddle (via SDL). If your gamepad is not recognized, you can specify additional mappings in a SDL2-format text file called gamecontrollerdb.txt, placed in the same folder as Paddle.

Credits

Paddle is developed by Ryan Touk (email)
SDL 2.0 is used for gamepad input (license)
Scintilla is used for the text editor component (license)

Version History

Version 1.1 (11 Feb 2016)

Version 1.0 (8 Feb 2015)

 

▲ Top · Back