Link search Menu Expand Document



Syntax Description
gamepad.button(b,val) User script callback for non-directional button presses : function
gamepad.dpad(axis,val) User script callback for directional pad presses : function
gamepad.axis(sensor_axis, sign) User script callback for sensor axis changes : function
gamepad.analog(sensor_axis, val, half_reso) User script callback for analog sensor changes (analog direction pad, joystick, trigger buttons) : function


gamepad’s states are all held in the gamepad.state table:

gamepad.state = {
  DPDOWN = false,
  DPUP = false,
  LDOWN = false,
  LUP = false,
  LLEFT = false,
  LRIGHT = false,
  RDOWN = false,
  RUP = false,
  RLEFT = false,
  RRIGHT = false,
  TLEFT = false,
  TRIGHT = false,
  -- aggregated
  DOWN = false,
  UP = false,
  LEFT = false,
  RIGHT = false,


gamepad.button(button_name, state)

  • triggered when a button is pressed or released

  • dpad arrows don’t count as buttons and one should use gamepad.dpad for this use-case

  • button_name can take the value: ABXYL1L2R1R2STARTSELECT

  • state is either true (pressed) or false (released)

gamepad.dpad(axis, sign)

  • triggered when a dpad arrow is pressed or released

  • axis can take the value X or Y

  • sign is either -1 or 1 (for each side of an axis) or 0 (released).

gamepad.axis(sensor_axis, sign)

  • similar to gamepad.dpad, but triggered by a sensor axis change

  • sensor_axis can take the value: dpadydpadxleftyleftxrightyrightxtriggerlefttriggerright (same naming convention as SDL)

  • sign is either -1 or 1 for each half-travel or 0 (centered)

  • please note that for triggerleft and triggerright, the resting (released) position is usually -1 instead of 0

gamepad.analog(sensor_axis, val, half_reso)

  • triggered by change of value from an analog sensor (analog direction pad, joystick, trigger buttons)

  • sensor_axis can take the value: leftyleftxrightyrightxtriggerlefttriggerright (same naming convention as SDL)

  • sends the raw sensor value (val) normalized around 0 as well as half_reso, the min/max value attainable on each side of the travel; val can only go between -half_reso and half_reso


digital A button is pressed

  • gamepad.state.A is set to true
  • gamepad.button('A', true)

digital dpad down is pressed

  • gamepad.state.DPDOWN is set to true
  • gamepad.axis('dpady', -1)
  • gamepad.dpad('Y', -1)

analog dpad down is pressed

  • gamepad.state.DPDOWN is set to true
  • gamepad.analog('dpady', -100, 128) (example values)
  • gamepad.axis('dpady', -1)
  • gamepad.dpad('Y', -1)

analog left stick down is pressed

  • gamepad.state.LDOWN is set to true
  • gamepad.analog('lefty', -100, 128) (example values)
  • gamepad.axis('lefty', -1)

analog left shoulder button is pressed

  • gamepad.state.TLEFT is set to true
  • gamepad.analog('triggerleft', 230, 255) (example values)
  • gamepad.axis('triggerleft', 1)
  • gamepad.trigger_button('L2', true)


Deciphers gamepad input and executes user-assignable callbacks. Since many gamepads do not adhere to standard HID event codes, this library relies uses SDL sensor_axiscodes (eg. dpadxleftx…) with controller mapping profiles to create a more predicable experience.

Plug + play models:

  • iBUFFALO Classic USB Gamepad
  • Xbox 360
  • Retrolink B00GWKL3Y4 ((S)NES-style, also sold by under other brands: iNNext, Elecom…)

Contributed and maintained by @p3r7