cl gamepad

3.0.0

Portability library for gamepad and joystick access.

About cl-gamepad

This is a library to provide cross-platform access to gamepads, joysticks, and other such HID devices.

How To

For this tutorial we assume the nickname gamepad exists for org.shirakumo.fraf.gamepad. Before you can start, you must initialise the library.

(gamepad:init)

If successful, it will return a list of currently connected gamepads. You can query the device properties with name, vendor, product, version, and driver. Once you are ready to process device input, you can do so with poll-events.

(gamepad:poll-events device
  (lambda (event)
    (format T "~& ~a ~a~%"
      (etypecase event
        (gamepad:button-down "Pressed")
        (gamepad:button-up "Released")
        (gamepad:axis-move "Moved"))
      (or (gamepad:event-label event) (gamepad:event-code event)))))

You can access the event properties with event-device, event-time, event-code, event-label, and for axis events event-value. Do note that the event instance is only valid within the dynamic extent of your supplied function. You cannot store the event elsewhere or process it out of band.

If the device gets disconnected or some other problem occurs during event polling, an error of type gamepad-error will be signalled. You should handle this error and unhook the device from your own system, then either invoke the restart drop-device, or call poll-devices to automatically refresh the current device list.

If the label in the event is NIL, the feature may not be properly mapped to a standardised label. Please see the following section.

Whenever you want to listen for new device connections or ensure current devices still exist, you should run poll-devices. Both poll-events and poll-devices accept a timeout argument to allow you to efficiently poll if you need a dedicated thread. The default behaviour is to return immediately if there are no pending changes, allowing you to use the calls synchronously.

Most gamepads also support haptic or force feedback. You can activate the rumble feature and modulate it over time using the rumble function. Do note that sadly the capability of the devices, and especially the capability of the underlying drivers varies wildly and the feature may thus sometimes just not be available.

You can query the last known state of a gamepad feature through button and axis. Only standardised labels can be given for these functions however, so unmapped features cannot be queried.

Finally you can configure common axis features such as the dead-zone and the ramp per device. Do note however that these settings are not persistent, so you must apply them whenever the device is connected anew. The axis values are rezoned after the dead-zone clamp has applied, meaning that if the value exceeds the dead-zone, it will be remapped to fit into the [0,1] range again. Also note that if you apply the dead-zone to the two axes of a single joystick separately, the zone you set will be square, rather than the expected circular dead zone. You can set a circular dead zone by setting the dead zone on the virtual labels :L for the :L-H and :L-V axes, or :R for the :R-H and :R-V axes. The ramp function is applied after the dead zone. By default no dead zone or ramp is applied.

Standardised Button Maps

In order to make portable interaction with gamepads possible, their features (buttons and axes) must be mapped to standardised purposes (see +labels+). Cl-gamepad will try to determine such a mapping automatically if possible. On Evdev and XInput this is typically the case. On DirectInput and IOKit not so much. In any case, when the automated mapping fails, manual mappings from the device's internal feature IDs to the standardised labels must be provided.

To this end cl-gamepad includes a database of mappings in default-device-mappings.lisp. These mappings are automatically loaded for any matching controller and should thus apply immediately, making the listed controllers compatible. If your controller is not listed and auto-detection fails, please use configure-device from a terminal. It will guide you through the process of mapping the device features to the proper labels, and will then save the mapping to the aforementioned file to make it persistent.

If you do configure a new device, please submit the updated mapping file to the upstream repository so that it can be included in the main distribution.

Supported Platforms

Currently the following platforms are supported:

Linux evdev (via libevdev)
macOS/iOS IOKit
Windows DirectInput
Windows XInput

On Windows DirectInput and XInput are used at the same time.

System Information

Version: 3.0.0

Dependencies:

Author: Nicolas Hafner

License: zlib

Homepage: https://Shirakumo.github.io/cl-gamepad/

Definition Index

ORG.SHIRAKUMO.FRAF.GAMEPAD

No documentation provided.

EXTERNAL SPECIAL-VARIABLE
*DEFAULT-MAPPINGS-FILE*
No documentation provided.

EXTERNAL GLOBAL

+LABELS+

Vector of standardised button and axis labels.

Modifying this value results in undefined behaviour.

The labels are intended to have the following semantic meanings:

  A        --- The A B C buttons are laid out on the bottom diagonal
  B            named button row, with A being the bottom-most.
  C            This follows the "Xbox" convention.
  X        --- The X Y Z buttons are laid out on the top diagonal
  Y            named button row, with X being the bottom-most.
  Z            This follows the "Xbox" convention.
  L1       --- The left hand upper trigger button.
  L2       --- The left hand lower trigger button/axis.
  L3       --- The left hand stick press-in button.
  R1       --- The right hand upper trigger button.
  R2       --- The right hand lower trigger button/axis.
  R3       --- The right hand stick press-in button.
  DPAD-L   --- The left dpad button.
  DPAD-R   --- The right dpad button.
  DPAD-U   --- The upper dpad button.
  DPAD-D   --- The lower dpad button.
  SELECT   --- The left central button. Often named select, back, or share.
  HOME     --- The middle central button. Usually a logo.
  START    --- The right central button. Often named start, or options.
  L-H      --- The left stick horizontal axis.
  L-V      --- The left stick vertical axis.
  R-H      --- The right stick horizontal axis.
  R-V      --- The right stick vertical axis.
  DPAD-H   --- The dpad horizontal axis.
  DPAD-V   --- The dpad vertical axis.
  TILT-X   --- The tilt degree around the X (along the length) axis.
  TILT-Y   --- The tilt degree around the Y (along the height) axis.
  TILT-Z   --- The tilt degree around the Z (along the depth) axis.
  MOVE-X   --- The relative motion over the X axis.
  MOVE-Y   --- The relative motion over the Y axis.
  MOVE-Z   --- The relative motion over the Z axis.
  WHEEL    --- The steering wheel direction.
  GAS      --- The gas pedal.
  BRAKE    --- The brake pedal.
  THROTTLE --- The throttle strength.
  RUDDER   --- The rudder direction.

EXTERNAL CLASS