Input Polling System
Comprehensive input handling for keyboard, mouse, and gamepad devices.
Component: TGorillaInputController
Table of Contents
- Introduction
- Getting Started
- HotKeys
- Sequences
- Input Devices
- Persistent Messages
- Raw Input Events
- Linux SDL Installation
- Platform Support
- Performance
- Best Practices
- See Also
Introduction
The Gorilla Input Polling System provides high-performance, asynchronous input handling for games and interactive applications. Unlike traditional event-driven input, this system continuously monitors input devices and allows you to define complex input combinations (HotKeys) and sequences.
Key Features:
- HotKeys - Combine up to 12 simultaneous inputs from any device
- Sequences - Chain up to 16 HotKeys in specific order
- Multi-Device - Mix keyboard, mouse, and gamepad inputs
- Persistent Messages - Continuous feedback for mouse position, gamepad triggers/thumbsticks
- Lock Time - Prevent accidental repeated activation
- Actions - Integrate with FMX Action system
- Thread-Safe - All operations are synchronized automatically
- Platform-Optimized - Uses low-level hooks on Windows, SDL2 on Linux
Getting Started
Design-Time Setup
- Drop a
TGorillaInputControllercomponent onto your form - Set the
Enabledproperty toTrue - Configure
Supportedproperty to enable desired devices:Keyboard- Enable keyboard inputMouse- Enable mouse inputGamePad- Enable gamepad input
Example:
// Enable all devices
GorillaInputController1.Supported := [Keyboard, Mouse, GamePad];
GorillaInputController1.Enabled := True;
Runtime Setup
var
LController: TGorillaInputController;
begin
LController := TGorillaInputController.Create(Self);
LController.Supported := [Keyboard, Mouse, GamePad];
LController.Enabled := True;
end;
HotKeys
A HotKey is a combination of inputs that triggers an action when activated or deactivated. You can combine up to 4 inputs per device (keyboard, mouse, gamepad) in a single HotKey.
Creating HotKeys
HotKeys consist of:
- Name - Unique identifier
- Combinations - List of input codes from different devices
- TriggerOnActivate - Fire when all inputs are pressed
- TriggerOnDeactivate - Fire when all inputs are released
- LockTime - Milliseconds before HotKey can trigger again
- Action - Optional FMX TAction to execute
- OnTriggered - Event handler
Design-Time HotKeys
- Select your
TGorillaInputControllercomponent - Find the
HotKeysproperty in Object Inspector - Click
[...]to open the collection editor - Click Add to create a new HotKey
- Set the
Nameproperty (e.g., "Jump", "Fire", "Sprint") - Expand the
Combinationsproperty - Add input items for each key/button:
- Set
Kindto device type (Keyboard, Mouse, GamePad) - Set
Codeto the input code constant
- Set
Example: Jump HotKey (Spacebar)
HotKey: "Jump"
Combinations:
Item[0]:
Kind: Keyboard
Code: GORILLA_INPUT_KEY_SPACE
TriggerOnActivate: True
Example: Aim + Shoot HotKey (Right Mouse + Left Mouse)
HotKey: "AimAndShoot"
Combinations:
Item[0]:
Kind: Mouse
Code: GORILLA_INPUT_MOUSE_RBUTTON
Item[1]:
Kind: Mouse
Code: GORILLA_INPUT_MOUSE_LBUTTON
TriggerOnActivate: True
LockTime: 100
Runtime HotKeys
var
LHotKey: TGorillaHotKeyItem;
begin
// Add HotKey
LHotKey := GorillaInputController1.AddHotKey('Jump');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_SPACE);
LHotKey.TriggerOnActivate := True;
LHotKey.OnTriggered := OnJumpTriggered;
end;
procedure TForm1.OnJumpTriggered(const AItem: TGorillaHotKeyItem;
const ACurrentInput: TGorillaHotKeyRaw; const AMode: TGorillaInputMode);
begin
if AMode = Activated then
Player.Jump();
end;
Multi-Device HotKey Example:
// Ctrl + E + Left Mouse Click for special attack
LHotKey := GorillaInputController1.AddHotKey('SpecialAttack');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_CTRL_LEFT);
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_E);
LHotKey.AddInput(Mouse, GORILLA_INPUT_MOUSE_LBUTTON);
LHotKey.TriggerOnActivate := True;
LHotKey.LockTime := 500; // Half-second cooldown
Trigger Modes
TriggerOnActivate:
- Fires when all inputs in the HotKey are pressed simultaneously
- Use for actions like jumping, shooting, sprinting
TriggerOnDeactivate:
- Fires when all inputs in the HotKey are released simultaneously
- Use for charge-up abilities, hold-to-aim mechanics
Both Modes:
- Set both to
Trueto trigger on press AND release - Use for toggle actions (crouch, flashlight on/off)
// Charge shot: Hold to charge, release to fire
LHotKey := GorillaInputController1.AddHotKey('ChargeShot');
LHotKey.AddInput(Mouse, GORILLA_INPUT_MOUSE_LBUTTON);
LHotKey.TriggerOnActivate := True; // Start charging
LHotKey.TriggerOnDeactivate := True; // Release shot
LHotKey.OnTriggered := OnChargeShotTriggered;
procedure TForm1.OnChargeShotTriggered(const AItem: TGorillaHotKeyItem;
const ACurrentInput: TGorillaHotKeyRaw; const AMode: TGorillaInputMode);
begin
if AMode = Activated then
Player.StartCharge()
else if AMode = Deactivated then
Player.ReleaseShot();
end;
Lock Time
Lock Time prevents rapid re-triggering of HotKeys:
LHotKey := GorillaInputController1.AddHotKey('Attack');
LHotKey.AddInput(Mouse, GORILLA_INPUT_MOUSE_LBUTTON);
LHotKey.LockTime := 250; // 250ms cooldown between attacks
Use Cases:
- Attack cooldowns
- Preventing accidental double-triggers
- Rate-limiting abilities
- Animation timing
Sequences
Sequences detect ordered combinations of HotKeys (like fighting game combos). You can chain up to 16 HotKeys in a sequence.
Creating Sequences
Sequences consist of:
- Name - Unique identifier
- HotKeys - Ordered list of HotKey items
- Sensitivity - Maximum time (ms) between HotKeys
- Action - Optional FMX TAction
- OnTriggered - Event handler
Design-Time Sequences
- First, create individual HotKeys for each input
- Select your
TGorillaInputControllercomponent - Find the
Sequencesproperty in Object Inspector - Click
[...]to open the collection editor - Click Add to create a new Sequence
- Set the
Nameproperty (e.g., "Combo1", "CheatCode") - Expand the
HotKeysproperty - Add sequence items linking to existing HotKeys:
- Set
HotKeyNameto the name of an existing HotKey
- Set
- Set
Sensitivity(default: 500ms)
Example: Konami Code
Sequence: "KonamiCode"
Sensitivity: 500
HotKeys:
Item[0]: HotKeyName = "ArrowUp"
Item[1]: HotKeyName = "ArrowUp"
Item[2]: HotKeyName = "ArrowDown"
Item[3]: HotKeyName = "ArrowDown"
Item[4]: HotKeyName = "ArrowLeft"
Item[5]: HotKeyName = "ArrowRight"
Item[6]: HotKeyName = "ArrowLeft"
Item[7]: HotKeyName = "ArrowRight"
Item[8]: HotKeyName = "KeyB"
Item[9]: HotKeyName = "KeyA"
Runtime Sequences
var
LHK1, LHK2, LHK3: TGorillaHotKeyItem;
LSeq: TGorillaInputSequenceItem;
begin
// Create individual HotKeys
LHK1 := GorillaInputController1.AddHotKey('Punch');
LHK1.AddInput(Keyboard, GORILLA_INPUT_KEY_P);
LHK1.TriggerOnActivate := True;
LHK2 := GorillaInputController1.AddHotKey('Punch');
LHK2.AddInput(Keyboard, GORILLA_INPUT_KEY_P);
LHK2.TriggerOnActivate := True;
LHK3 := GorillaInputController1.AddHotKey('Kick');
LHK3.AddInput(Keyboard, GORILLA_INPUT_KEY_K);
LHK3.TriggerOnActivate := True;
// Create Sequence: Punch-Punch-Kick
LSeq := GorillaInputController1.AddSequence('Combo1', [LHK1, LHK2, LHK3]);
LSeq.Sensitivity := 500;
LSeq.OnTriggered := OnCombo1Triggered;
end;
procedure TForm1.OnCombo1Triggered(const ASequence: TGorillaInputSequenceItem);
begin
Player.PerformCombo('Triple Strike');
end;
Sensitivity
Sensitivity defines the maximum time between HotKey activations in a sequence:
| Sensitivity | Description | Use Case |
|---|---|---|
| 100-300ms | Very strict | Fast-paced fighting combos |
| 300-500ms | Normal | General combo inputs |
| 500-1000ms | Relaxed | Cheat codes, accessibility |
| 1000ms+ | Very relaxed | Discovery mechanics |
Default: 500ms (defined by GORILLA_INPUT_SEQUENCE_SENSITIVITY)
Input Devices
Keyboard
Available Keys:
// Letters
GORILLA_INPUT_KEY_A to GORILLA_INPUT_KEY_Z
// Numbers
GORILLA_INPUT_KEY_0 to GORILLA_INPUT_KEY_9
// Arrows
GORILLA_INPUT_KEY_ARROW_LEFT
GORILLA_INPUT_KEY_ARROW_UP
GORILLA_INPUT_KEY_ARROW_RIGHT
GORILLA_INPUT_KEY_ARROW_DOWN
// Special keys
GORILLA_INPUT_KEY_SPACE
GORILLA_INPUT_KEY_RETURN
GORILLA_INPUT_KEY_ESCAPE
GORILLA_INPUT_KEY_BACKSPACE
GORILLA_INPUT_KEY_DELETE
GORILLA_INPUT_KEY_TAB
GORILLA_INPUT_KEY_PAUSE
// Modifiers
GORILLA_INPUT_KEY_SHIFT_LEFT
GORILLA_INPUT_KEY_SHIFT_RIGHT
GORILLA_INPUT_KEY_CTRL_LEFT
GORILLA_INPUT_KEY_CTRL_RIGHT
GORILLA_INPUT_KEY_ALT
GORILLA_INPUT_KEY_ALTGR
// Symbols
GORILLA_INPUT_KEY_PLUS
GORILLA_INPUT_KEY_MINUS
GORILLA_INPUT_KEY_DOT
GORILLA_INPUT_KEY_COMMA
// ... and many more
| Constant | Char | Decimal |
|---|---|---|
| GORILLA_INPUT_KEY_A | 'A' | 65 |
| GORILLA_INPUT_KEY_B | 'B' | 66 |
| GORILLA_INPUT_KEY_C | 'C' | 67 |
| GORILLA_INPUT_KEY_D | 'D' | 68 |
| GORILLA_INPUT_KEY_E | 'E' | 69 |
| GORILLA_INPUT_KEY_F | 'F' | 70 |
| GORILLA_INPUT_KEY_G | 'G' | 71 |
| GORILLA_INPUT_KEY_H | 'H' | 72 |
| GORILLA_INPUT_KEY_I | 'I' | 73 |
| GORILLA_INPUT_KEY_J | 'J' | 74 |
| GORILLA_INPUT_KEY_K | 'K' | 75 |
| GORILLA_INPUT_KEY_L | 'L' | 76 |
| GORILLA_INPUT_KEY_M | 'M' | 77 |
| GORILLA_INPUT_KEY_N | 'N' | 78 |
| GORILLA_INPUT_KEY_O | 'O' | 79 |
| GORILLA_INPUT_KEY_P | 'P' | 80 |
| GORILLA_INPUT_KEY_Q | 'Q' | 81 |
| GORILLA_INPUT_KEY_R | 'R' | 82 |
| GORILLA_INPUT_KEY_S | 'S' | 83 |
| GORILLA_INPUT_KEY_T | 'T' | 84 |
| GORILLA_INPUT_KEY_U | 'U' | 85 |
| GORILLA_INPUT_KEY_V | 'V' | 86 |
| GORILLA_INPUT_KEY_W | 'W' | 87 |
| GORILLA_INPUT_KEY_X | 'X' | 88 |
| GORILLA_INPUT_KEY_Y | 'Y' | 89 |
| GORILLA_INPUT_KEY_Z | 'Z' | 90 |
| GORILLA_INPUT_KEY_0 | '0' | 48 |
| GORILLA_INPUT_KEY_1 | '1' | 49 |
| GORILLA_INPUT_KEY_2 | '2' | 50 |
| GORILLA_INPUT_KEY_3 | '3' | 51 |
| GORILLA_INPUT_KEY_4 | '4' | 52 |
| GORILLA_INPUT_KEY_5 | '5' | 53 |
| GORILLA_INPUT_KEY_6 | '6' | 54 |
| GORILLA_INPUT_KEY_7 | '7' | 55 |
| GORILLA_INPUT_KEY_8 | '8' | 56 |
| GORILLA_INPUT_KEY_9 | '9' | 57 |
| GORILLA_INPUT_KEY_ARROW_LEFT | #37 | 75 |
| GORILLA_INPUT_KEY_ARROW_UP | #38 | 72 |
| GORILLA_INPUT_KEY_ARROW_RIGHT | #39 | 77 |
| GORILLA_INPUT_KEY_ARROW_DOWN | #40 | 80 |
| GORILLA_INPUT_KEY_SPACE | ' ' | 32 |
| GORILLA_INPUT_KEY_EXCL | '!' | 33 |
| GORILLA_INPUT_KEY_QUOTE | '“' | 34 |
| GORILLA_INPUT_KEY_HASH | '#' | 35 |
| GORILLA_INPUT_KEY_PERCENT | '%' | 37 |
| GORILLA_INPUT_KEY_STAR | '*' | 42 |
| GORILLA_INPUT_KEY_PLUS | '+' | 43 |
| GORILLA_INPUT_KEY_COMMA | ',' | 44 |
| GORILLA_INPUT_KEY_MINUS | '-' | 45 |
| GORILLA_INPUT_KEY_DOT | '.' | 46 |
| GORILLA_INPUT_KEY_DIV | '/' | 47 |
| GORILLA_INPUT_KEY_PARA | '§' | 167 |
| GORILLA_INPUT_KEY_DOLLAR | '$' | 36 |
| GORILLA_INPUT_KEY_EURO | '€' | 128 |
| GORILLA_INPUT_KEY_AT | '@' | 64 |
| GORILLA_INPUT_KEY_AND | '&' | 38 |
| GORILLA_INPUT_KEY_BACKSLASH | '\' | 92 |
| GORILLA_INPUT_KEY_BRACKETOPEN | '(' | 40 |
| GORILLA_INPUT_KEY_BRACKETCLOSE | ')' | 41 |
| GORILLA_INPUT_KEY_EQUAL | '=' | 61 |
| GORILLA_INPUT_KEY_QUESTION | '?' | 63 |
| GORILLA_INPUT_KEY_TILDE | '~' | 126 |
| GORILLA_INPUT_KEY_UNDERSCORE | '_' | 95 |
| GORILLA_INPUT_KEY_COLON | ':' | 58 |
| GORILLA_INPUT_KEY_SEMICOLON | ';' | 59 |
| GORILLA_INPUT_KEY_BAR | | | 124 |
| GORILLA_INPUT_KEY_TAGOPEN | '<' | 60 |
| GORILLA_INPUT_KEY_TAGCLOSE | '>' | 62 |
| GORILLA_INPUT_KEY_SHIFT_BACKSPACE | #8 | 8 |
| GORILLA_INPUT_KEY_SHIFT_TAB | #9 | 9 |
| GORILLA_INPUT_KEY_LINEFEED | #$0A | 10 |
| GORILLA_INPUT_KEY_RETURN | #$0D | 13 |
| GORILLA_INPUT_KEY_ESCAPE | #$1B | 27 |
| GORILLA_INPUT_KEY_DELETE | #$7F | 127 |
| GORILLA_INPUT_KEY_SHIFT_CAPS | #20 | 20 |
| GORILLA_INPUT_KEY_SHIFT_LEFT | #160 | 160 |
| GORILLA_INPUT_KEY_SHIFT_RIGHT | #161 | 161 |
| GORILLA_INPUT_KEY_CTRL_LEFT | #162 | 162 |
| GORILLA_INPUT_KEY_CTRL_RIGHT | #163 | 163 |
| GORILLA_INPUT_KEY_ALT | #164 | 164 |
| GORILLA_INPUT_KEY_ALTGR | #165 | 165 |
WASD Movement Example:
// Forward
LHotKey := GorillaInputController1.AddHotKey('MoveForward');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_W);
LHotKey.TriggerOnActivate := True;
LHotKey.TriggerOnDeactivate := True;
LHotKey.OnTriggered := OnMoveForward;
// Sprint (Shift + W)
LHotKey := GorillaInputController1.AddHotKey('Sprint');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_SHIFT_LEFT);
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_W);
LHotKey.TriggerOnActivate := True;
LHotKey.TriggerOnDeactivate := True;
Mouse
Available Buttons:
// Buttons
GORILLA_INPUT_MOUSE_LBUTTON // Left button
GORILLA_INPUT_MOUSE_RBUTTON // Right button
GORILLA_INPUT_MOUSE_MBUTTON // Middle button (wheel click)
GORILLA_INPUT_MOUSE_X1BUTTON // Extra button 1
GORILLA_INPUT_MOUSE_X2BUTTON // Extra button 2
// Double-clicks
GORILLA_INPUT_MOUSE_LBUTTON_DBLCLK
GORILLA_INPUT_MOUSE_RBUTTON_DBLCLK
GORILLA_INPUT_MOUSE_MBUTTON_DBLCLK
GORILLA_INPUT_MOUSE_X1BUTTON_DBLCLK
GORILLA_INPUT_MOUSE_X2BUTTON_DBLCLK
// Events
GORILLA_INPUT_MOUSE_WHEEL // Mouse wheel
GORILLA_INPUT_MOUSE_POSITION // Mouse position (persistent)
| Constant | Index | Value |
|---|---|---|
| GORILLA_INPUT_MOUSE_POSITION | 0 | $100001 |
| GORILLA_INPUT_MOUSE_LBUTTON | 1 | $100002 |
| GORILLA_INPUT_MOUSE_LBUTTON_DBLCLK | 2 | $100003 |
| GORILLA_INPUT_MOUSE_RBUTTON | 3 | $100004 |
| GORILLA_INPUT_MOUSE_RBUTTON_DBLCLK | 4 | $100005 |
| GORILLA_INPUT_MOUSE_MBUTTON | 5 | $100006 |
| GORILLA_INPUT_MOUSE_MBUTTON_DBLCLK | 6 | $100007 |
| GORILLA_INPUT_MOUSE_X1BUTTON | 7 | $100008 |
| GORILLA_INPUT_MOUSE_X1BUTTON_DBLCLK | 8 | $100009 |
| GORILLA_INPUT_MOUSE_X2BUTTON | 9 | $10000A |
| GORILLA_INPUT_MOUSE_X2BUTTON_DBLCLK | 10 | $10000B |
| GORILLA_INPUT_MOUSE_WHEEL | 11 | $10000C |
Shoot and Reload Example:
// Left click to shoot
LHotKey := GorillaInputController1.AddHotKey('Shoot');
LHotKey.AddInput(Mouse, GORILLA_INPUT_MOUSE_LBUTTON);
LHotKey.TriggerOnActivate := True;
// Right click to aim
LHotKey := GorillaInputController1.AddHotKey('Aim');
LHotKey.AddInput(Mouse, GORILLA_INPUT_MOUSE_RBUTTON);
LHotKey.TriggerOnActivate := True;
LHotKey.TriggerOnDeactivate := True;
// R key to reload
LHotKey := GorillaInputController1.AddHotKey('Reload');
LHotKey.AddInput(Keyboard, GORILLA_INPUT_KEY_R);
LHotKey.TriggerOnActivate := True;
GamePad
Supported Controllers:
- Xbox 360 Controller
- Xbox One Controller
- Xbox Series X|S Controller
- Generic XInput-compatible controllers (Windows)
- Generic SDL2-compatible controllers (Linux)
Maximum GamePads:
- Windows: 4 controllers (XInput limitation)
- Linux/Android/macOS: Platform-dependent
Available Buttons:
// D-Pad
GORILLA_INPUT_GAMEPAD_DPAD_UP
GORILLA_INPUT_GAMEPAD_DPAD_DOWN
GORILLA_INPUT_GAMEPAD_DPAD_LEFT
GORILLA_INPUT_GAMEPAD_DPAD_RIGHT
// Face buttons
GORILLA_INPUT_GAMEPAD_BUTTON_A
GORILLA_INPUT_GAMEPAD_BUTTON_B
GORILLA_INPUT_GAMEPAD_BUTTON_X
GORILLA_INPUT_GAMEPAD_BUTTON_Y
// Shoulder buttons
GORILLA_INPUT_GAMEPAD_SHOULDER_LEFT // LB
GORILLA_INPUT_GAMEPAD_SHOULDER_RIGHT // RB
// System buttons
GORILLA_INPUT_GAMEPAD_STARTBUTTON // Start/Menu
GORILLA_INPUT_GAMEPAD_MODEBUTTON // Xbox/Guide button
GORILLA_INPUT_GAMEPAD_BACKBUTTON // Back/View
// Thumbsticks (press)
GORILLA_INPUT_GAMEPAD_THUMBSTICK_LEFT
GORILLA_INPUT_GAMEPAD_THUMBSTICK_RIGHT
// Triggers (persistent, 0-255)
GORILLA_INPUT_GAMEPAD_TRIGGER_LEFT // LT
GORILLA_INPUT_GAMEPAD_TRIGGER_RIGHT // RT
// Thumbstick positions (persistent, -32768 to +32767)
GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_LEFT
GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_RIGHT
// Connection events
GORILLA_INPUT_GAMEPAD_CONNECTED
GORILLA_INPUT_GAMEPAD_DISCONNECTED
| Constant | Index | Value |
|---|---|---|
| GORILLA_INPUT_GAMEPAD_CONNECTED | $1000 | $200001 |
| GORILLA_INPUT_GAMEPAD_DISCONNECTED | $1001 | $200002 |
| GORILLA_INPUT_GAMEPAD_DPAD_UP | 0 | $200003 |
| GORILLA_INPUT_GAMEPAD_DPAD_DOWN | 1 | $200004 |
| GORILLA_INPUT_GAMEPAD_DPAD_LEFT | 2 | $200005 |
| GORILLA_INPUT_GAMEPAD_DPAD_RIGHT | 3 | $200006 |
| GORILLA_INPUT_GAMEPAD_START_BUTTON | 4 | $200007 |
| GORILLA_INPUT_GAMEPAD_MODEBUTTON | 5 | $200008 |
| GORILLA_INPUT_GAMEPAD_BACKBUTTON | 6 | $200009 |
| GORILLA_INPUT_GAMEPAD_THUMBSTICK_LEFT | 7 | $20000A |
| GORILLA_INPUT_GAMEPAD_THUMBSTICK_RIGHT | 8 | $20000B |
| GORILLA_INPUT_GAMEPAD_SHOULDER_LEFT | 9 | $20000C |
| GORILLA_INPUT_GAMEPAD_SHOULDER_RIGHT | 10 | $20000D |
| GORILLA_INPUT_GAMEPAD_BUTTON_A | 11 | $20000E |
| GORILLA_INPUT_GAMEPAD_BUTTON_B | 12 | $20000F |
| GORILLA_INPUT_GAMEPAD_BUTTON_X | 13 | $200011 |
| GORILLA_INPUT_GAMEPAD_BUTTON_Y | 14 | $200012 |
| GORILLA_INPUT_GAMEPAD_TRIGGER_LEFT | $100 | $200020 |
| GORILLA_INPUT_GAMEPAD_TRIGGER_RIGHT | $101 | $200021 |
| GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_LEFT | $200 | $200030 |
| GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_RIGHT | $201 | $200031 |
GamePad HotKeys Example:
// Jump with A button
LHotKey := GorillaInputController1.AddHotKey('GamePadJump');
LHotKey.AddInput(GamePad, GORILLA_INPUT_GAMEPAD_BUTTON_A);
LHotKey.TriggerOnActivate := True;
// Sprint with left thumbstick press + forward movement
LHotKey := GorillaInputController1.AddHotKey('GamePadSprint');
LHotKey.AddInput(GamePad, GORILLA_INPUT_GAMEPAD_THUMBSTICK_LEFT);
LHotKey.TriggerOnActivate := True;
// Aim with LT, shoot with RT
LHotKey := GorillaInputController1.AddHotKey('GamePadAimShoot');
LHotKey.AddInput(GamePad, GORILLA_INPUT_GAMEPAD_TRIGGER_LEFT);
LHotKey.AddInput(GamePad, GORILLA_INPUT_GAMEPAD_TRIGGER_RIGHT);
LHotKey.TriggerOnActivate := True;
Persistent Messages
Persistent messages provide continuous feedback for analog inputs like mouse position, gamepad triggers, and thumbsticks.
| Message-Code | Description | DataType |
|---|---|---|
| GORILLA_INPUT_MOUSE_POSITION | $100001 | latest mouse position |
| GORILLA_INPUT_GAMEPAD_TRIGGER_LEFT | $200020 | gamepad left trigger value |
| GORILLA_INPUT_GAMEPAD_TRIGGER_RIGHT | $200021 | gamepad right trigger value |
| GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_LEFT | $200030 | gamepad left thumbstick position |
| GORILLA_INPUT_GAMEPAD_THUMBSTICK_POS_RIGHT | $200031 | gamepad right thumbstick position |
Mouse Position
var
LMessage: TGorillaInputMessage;
LPos: TPoint;
begin
// Get last mouse position
if GorillaInputController1.GetLastMousePosition(LPos) then
begin
// LPos.X, LPos.Y contain screen coordinates
Camera.RotateBy(LPos.X * 0.01, LPos.Y * 0.01);
end;
// Alternative: Get raw message
if GorillaInputController1.GetPersistentMessage(Mouse,
GORILLA_INPUT_MOUSE_POSITION, LMessage) then
begin
LPos := LMessage.Data.AsType<TPoint>;
end;
end;
GamePad Triggers
var
LTriggers: TPoint;
begin
// Get both trigger values (0-255 each)
if GorillaInputController1.GetLastGamePadTriggers(LTriggers) then
begin
// LTriggers.X = Left trigger (0-255)
// LTriggers.Y = Right trigger (0-255)
Car.SetAcceleration(LTriggers.Y / 255.0);
Car.SetBraking(LTriggers.X / 255.0);
end;
end;
GamePad Thumbsticks
var
LThumbstick: TPointF;
begin
// Get left thumbstick position (-1.0 to +1.0)
if GorillaInputController1.GetLastGamePadThumbstickPosLeft(LThumbstick) then
begin
// LThumbstick.X = Horizontal (-1.0 to +1.0)
// LThumbstick.Y = Vertical (-1.0 to +1.0)
Player.Move(LThumbstick.X, LThumbstick.Y);
end;
// Get right thumbstick for camera
if GorillaInputController1.GetLastGamePadThumbstickPosRight(LThumbstick) then
begin
Camera.Rotate(LThumbstick.X * 2.0, LThumbstick.Y * 2.0);
end;
end;
Raw Input Events
For direct input handling without HotKeys:
procedure TForm1.FormCreate(Sender: TObject);
begin
GorillaInputController1.OnKeyDown := OnKeyDown;
GorillaInputController1.OnKeyUp := OnKeyUp;
GorillaInputController1.OnMouseDown := OnMouseDown;
GorillaInputController1.OnMouseUp := OnMouseUp;
GorillaInputController1.OnMouseMove := OnMouseMove;
GorillaInputController1.OnGamePadButtonDown := OnGamePadButtonDown;
GorillaInputController1.OnGamePadButtonUp := OnGamePadButtonUp;
end;
procedure TForm1.OnKeyDown(ASender: TObject; AKeyCode: Integer);
begin
if AKeyCode = GORILLA_INPUT_KEY_ESCAPE then
ShowMenu();
end;
procedure TForm1.OnMouseMove(ASender: TObject;
AStates: TGorillaMouseStates; APos: TPointF);
begin
// Handle mouse movement
Cursor.Position := APos;
end;
procedure TForm1.OnGamePadButtonDown(ASender: TObject;
AState: TGorillaInputCode; AButtons: TGorillaGamePadButtons);
begin
if TGorillaGamePadButton.ButtonA in AButtons then
Player.Jump();
end;
Platform Support
| Platform | Keyboard | Mouse | GamePad | Notes |
|---|---|---|---|---|
| Windows | ✓ | ✓ | ✓ (XInput) | Low-level hooks for keyboard/mouse |
| Linux | ✓ | ✓ | ✓ (SDL2) | Requires SDL2 library |
| Android | ✓ | ✓ | ✓ | Touch events mapped to mouse |
High-Performance Hooks (Windows)
By default, the input controller uses low-level hooks on Windows for better performance:
// Enabled by default
GorillaInputController1.HighPerformanceHooks := True;
// Disable during debugging (makes debugging faster)
{$IFDEF DEBUG}
GorillaInputController1.HighPerformanceHooks := False;
{$ENDIF}
When to disable:
- During debugging sessions (slow debugging)
- Testing/development
- Running in virtual machines
WARNING: On Windows platform in many cases high performance hooks debugging is getting very slow, because low level hooks have a 1000ms timeout by default and hooks not getting paused during debugging.
This leads to lagging mouse and keyboard input. Of course you can deactivate HighPerformanceHooks meanwhile, but you could also edit the registry lik this:
- Open RegEdit.exe (Windows)
- Move to the path: “HKEY_CURRENT_USER\Control Panel\Desktop\”
- Add a new value of type DWORD with the name “LowLevelHooksTimeout”
- Enter a value which stands for the timeout in milliseconds (f.e. 50ms)
- A system restart is required!
Linux SDL Installation
Since v1.1.16.+ Linux support is available for input polling. Gamepad/joystick handling is solved by using SDL2.
Install SDL2 on your system
Debian/Ubuntu:
sudo apt-get install libsdl2-2.0-0
Fedora/RHEL:
sudo dnf install SDL2
You can expose Windows USB devices to WSL2, but it's complicated: https://learn.microsoft.com/windows/wsl/connect-usb#attach-a-usb-device
On Windows PowerShell as Admin
winget install usbipd
Restart PowerShell with admin-rights!
List devices and get the busid of your gamepad/joystick:
usbipd list
Attach gamepad to WSL2:
usbipd attach --wsl --busid <busid>
Check USB devices on WSL2:
lsusb
NOTICE: USBUtils needed:
sudo apt install usbutils
Remove gamepad from WSL2:
usbipd detach --busid <busid>
This requires WSL2 and is experimental for gamepads.
Performance
Sensitivity
Control how often input handlers poll for new inputs:
var
LHandler: TGorillaInputHandler;
begin
// Get keyboard handler
LHandler := GorillaInputController1.GetHandler(Keyboard);
if Assigned(LHandler) then
LHandler.Sensitivity := 5; // Poll every 5ms (faster)
end;
Default: 10ms (GORILLA_INPUT_HANDLER_SENSITIVITY)
Guidelines:
- 5ms - High-precision gaming (fighting games, rhythm games)
- 10ms - Default, balanced performance
- 16ms - Standard gaming (60 FPS)
- 33ms - Low CPU usage
Thread Safety
All operations are thread-safe:
- HotKey detection runs on background thread
- Event callbacks are synchronized to main thread
- No manual locking required
Memory Usage
- Each HotKey: ~100 bytes
- Each Sequence: ~200 bytes + (HotKeys × 50 bytes)
- Input buffers: Minimal (cleared after processing)
Best Practices
1. Use Descriptive Names
// Good
AddHotKey('PlayerJump');
AddHotKey('WeaponReload');
AddSequence('SuperCombo');
// Bad
AddHotKey('HK1');
AddHotKey('Input2');
AddSequence('Seq1');
2. Set Lock Times for Actions
// Prevent spam
LHotKey := AddHotKey('Attack');
LHotKey.LockTime := 250; // Match animation duration
3. Enable Only Needed Devices
// Desktop game - keyboard + mouse only
GorillaInputController1.Supported := [Keyboard, Mouse];
// Console game - gamepad only
GorillaInputController1.Supported := [GamePad];
4. Disable Debug Hooks
{$IFDEF DEBUG}
GorillaInputController1.HighPerformanceHooks := False;
{$ENDIF}
5. Use TriggerOnDeactivate for Hold Actions
// Charge shot
LHotKey.TriggerOnActivate := True; // Start charge
LHotKey.TriggerOnDeactivate := True; // Release
6. Keep Sequences Short
- Recommended: 3-8 HotKeys
- Maximum: 16 HotKeys
- Longer sequences are harder to execute
7. Test Cross-Platform
{$IFDEF MSWINDOWS}
// Windows-specific code
{$ENDIF}
{$IFDEF LINUX}
// Linux-specific code
{$ENDIF}
See Also
- Input Controller Unit - Full API documentation
- Camera & Character Controllers - Pre-configured first/third-person input
- Speech-to-Text - Binding push-to-talk to a key or gamepad button