Skip to content

Add gamepad library and hooks for Lua scripting

Lactozilla requested to merge Lactozilla/SRB2:gamepad-refactor-lua-features into next

Merge !1870 (merged) first.

Example script: gamepad-lib-test.lua

Lua documentation

gamepad userdata fields:

Field Accepts Returns Description
#gamepad integer This returns the gamepad number. Gamepad numbers are 1-indexed.
gamepad.connected boolean This field returns true if the gamepad is connected, and false otherwise.
gamepad.type string This field returns the type of the gamepad.
gamepad.isXbox boolean true if the gamepad is an Xbox controller; false if otherwise.
gamepad.isPlayStation boolean true if the gamepad is a PlayStation controller; false if otherwise.
gamepad.isNintendoSwitch boolean true if the gamepad is a Nintendo Switch Pro Controller, a Joy-Con L, a Joy-Con R, or Joy-Con in the Joy-Con Grip; false if otherwise.
gamepad.isJoyCon boolean true if the gamepad is a Joy-Con L, or a Joy-Con R; false if otherwise.
gamepad.hasRumble boolean true if the gamepad has haptic feedback capabilities; false if otherwise.
gamepad.isRumbling boolean true if rumble is active in the gamepad; false if otherwise.
gamepad.isRumblePaused boolean boolean This field will return true if the current haptic effect on the gamepad is paused, and false if it isn't. It can be set to pause the effect.
gamepad.largeMotorFrequency fixed point value fixed point value The frequency of the large motor. This is usually physically located on the left side of a gamepad.
gamepad.smallMotorFrequency fixed point value fixed point value The frequency of the small motor. This is usually physically located on the right side of a gamepad.

gamepad userdata functions:

Function Parameters Description Returns
gamepad:isButtonDown string button Checks if a gamepad button is down. boolean
gamepad:getAxis string axis, [fixed_t applyDeadzone] Returns the value of an axis, from -FRACUNIT to FRACUNIT. For triggers, this always returns a value from 0 to FRACUNIT. applyDeadzone is true by default. fixed point value
gamepad:getStick "left" or "right", [fixed_t applyDeadzone] Returns the X and Y values of a stick, from -FRACUNIT to FRACUNIT. applyDeadzone is true by default. two fixed point values
gamepad:getTrigger "left" or "right", [fixed_t applyDeadzone] Returns the value of a stick, from 0 to FRACUNIT. applyDeadzone is true by default. fixed point value
gamepad:getButtonName string button Returns the name of a button. This may vary depending on the gamepad type. This is useful for displaying in e.g. menus. string
gamepad:getAxisName string axis Returns the name of an axis. This may vary depending on the gamepad type. This is useful for displaying in e.g. menus. string
gamepad:getTriggerName "left" or "right" Returns the name of a trigger. This may vary depending on the gamepad type. This is useful for displaying in e.g. menus. string
gamepad:rumble fixed_t large_motor_frequency, [fixed_t small_motor_frequency, [tic_t duration]] Changes the frequency of the gamepad's motors. If the small motor's frequency is nil, it'll be set to the large motor's frequency. If duration is nil or 0, the motors rotate forever, until they're stopped or their frequency changes. true is succeeded, false if not
gamepad:stopRumble Stops the motors on the gamepad from rotating. string

Button names:

Name Description
"a" Bottom face button
"b" Right face button
"x" Left face button
"y" Top face button
"back" Back button
"guide" Guide button
"start" Start
"left-stick" Left stick click
"right-stick" Right stick click
"left-shoulder" Left shoulder
"right-shoulder" Right shoulder
"dpad-up" D-Pad Up
"dpad-down" D-Pad Down
"dpad-left" D-Pad Left
"dpad-right" D-Pad Right
"misc1" Depends on the type of the controller; if you want to know, check the controller type, or try using gamepad:getButtonName("misc1")
"paddle1" P1 Paddle (Xbox Elite controllers)
"paddle2" P2 Paddle (Xbox Elite controllers)
"paddle3" P3 Paddle (Xbox Elite controllers)
"paddle4" P4 Paddle (Xbox Elite controllers)
"touchpad" Touchpad button (PlayStation 4 and 5 controllers)

Axis names:

Name Description
"left-x" Left stick X
"left-y" Left stick Y
"right-x" Right stick X
"right-y" Right stick Y
"trigger-left" Left trigger
"trigger-right" Right trigger

Gamepad types:

Type
"xbox-360"
"xbox-one"
"xbox-series-xs"
"xbox-elite"
"ps3"
"ps4"
"ps5"
"switch-pro"
"switch-joy-con-grip"
"switch-joy-con-left"
"switch-joy-con-right"
"stadia"
"amazon-luna"
"steam-controller"
"virtual"
"unknown"

Functions added:

Function Parameters Description Returns
input.getPlayerGamepad player_t player Returns a gamepad for a specific player. If the specified player isn't "local" to the system running the game, this returns nil. gamepad

Hooks added:

Function Parameters Description
GamepadButtonDown gamepad gamepad, string button Called when a button in the gamepad is pressed. button is the button name. Works just like KeyDown.
GamepadButtonUp gamepad gamepad, string button Called when a button in the gamepad is no longer being pressed. button is the button name. Works just like KeyUp.
GamepadAdded gamepad gamepad Called when a gamepad is added.
GamepadRemoved gamepad gamepad Called when a gamepad is removed.

gamepads library:

Field Description
#gamepads Returns how many gamepads may be connected at once. Always returns 2.
gamepads[n] Returns the n-th gamepad. This is 1-indexed.
gamepads.iterate Iterates through all connected gamepads.
Edited by Lactozilla

Merge request reports