Input Polling System

Comprehensive input handling for keyboard, mouse, and gamepad devices.

Component: TGorillaInputController

Table of Contents

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

  1. Drop a TGorillaInputController component onto your form
  2. Set the Enabled property to True
  3. Configure Supported property to enable desired devices:
    • Keyboard - Enable keyboard input
    • Mouse - Enable mouse input
    • GamePad - 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

  1. Select your TGorillaInputController component
  2. Find the HotKeys property in Object Inspector
  3. Click [...] to open the collection editor
  4. Click Add to create a new HotKey
  5. Set the Name property (e.g., "Jump", "Fire", "Sprint")
  6. Expand the Combinations property
  7. Add input items for each key/button:
    • Set Kind to device type (Keyboard, Mouse, GamePad)
    • Set Code to the input code constant

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 True to 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

  1. First, create individual HotKeys for each input
  2. Select your TGorillaInputController component
  3. Find the Sequences property in Object Inspector
  4. Click [...] to open the collection editor
  5. Click Add to create a new Sequence
  6. Set the Name property (e.g., "Combo1", "CheatCode")
  7. Expand the HotKeys property
  8. Add sequence items linking to existing HotKeys:
    • Set HotKeyName to the name of an existing HotKey
  9. 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:

  1. Open RegEdit.exe (Windows)
  2. Move to the path: “HKEY_CURRENT_USER\Control Panel\Desktop\”
  3. Add a new value of type DWORD with the name “LowLevelHooksTimeout”
  4. Enter a value which stands for the timeout in milliseconds (f.e. 50ms)
  5. 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