Skip to content

gamepad

This directory implements support for using a physical game controller (gamepad) as an alternative input mechanism for mouse movement, clicking, dragging, scrolling, and system commands within Talon. It also includes a robust graphical utility to visualize and test controller inputs.

Core Architecture and Gamepad Control

The core integration uses a combination of Python actions and Talon bindings to translate controller movements into fluid desktop actions.

  • gamepad.py defines the custom actions and logic for controller mapping. It uses non-linear (cubic) scaling x**3 and y**3 for mouse movements and scrolling, allowing for precise slow micro-adjustments when the sticks are moved slightly, and fast acceleration when pushed fully. It also features a "mouse jump" algorithm (gamepad_mouse_jump) that halves the distance between the cursor and the screen edge in a given D-pad direction, enabling quick traversal of multi-monitor setups.
  • gamepad.talon binds raw controller events to the actions defined in the Python module. It handles analog sticks (left and right XY), triggers (L2/R2), bumpers (L1/R1), D-pads, and standard action buttons (North, South, East, West).
  • gamepad_settings.talon acts as the activation switch. Users uncomment the user.gamepad tag here to enable general controller functionality.

Gamepad Input Visualization

To ensure controllers are calibrated and sending the correct signals, the directory features a graphical tester interface.

  • gamepad_tester.py constructs an interactive graphical overlay using Talon’s built-in Canvas APIs. It implements the canvas rendering logic, drawing stylized representations of joysticks, triggers, and buttons. When buttons are pressed or sticks are moved, the canvas visually fills, offsets, or highlights the corresponding UI elements.
  • gamepad_tester.talon maps the voice command "gamepad tester" to toggle the visualization overlay on or off.
  • gamepad_tester_open.talon contains bindings active only when the user.gamepad_tester tag is active. It intercepts raw gamepad inputs and routes them straight to the tester UI actions instead of performing mouse maneuvers.

Integration and State Safety

To prevent conflicts where testing a gamepad accidentally clicks or scrolls your active window, gamepad.talon is configured with the condition and not tag: user.gamepad_tester. This setup safely disables standard gamepad actions while the tester is open, funneling all hardware signals exclusively to gamepad_tester_open.talon.

For a complete walkthrough of setup and demo videos, refer to README.md.