Add gamepad library and hooks for Lua scripting (!1871) · Merge requests · STJr / SRB2

Merged Lactozilla requested to merge Lactozilla/SRB2:gamepad-refactor-lua-features into next 2 years ago

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.

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

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)

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

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.

Add gamepad library and hooks for Lua scripting

Lua documentation

`gamepad` userdata fields:

`gamepad` userdata functions:

Button names:

Axis names:

Gamepad types:

Functions added:

Hooks added:

`gamepads` library:

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"`

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.

Add gamepad library and hooks for Lua scripting

Lua documentation

gamepad userdata fields:

gamepad userdata functions:

Button names:

Axis names:

Gamepad types:

Functions added:

Hooks added:

gamepads library:

Merge request reports

`gamepad` userdata fields:

`gamepad` userdata functions:

`gamepads` library: