Pad1 - stingray.Pad1 namespace reference - Stingray Lua API Reference

Description

A global singleton that represents the first connected game pad.

There is a separate pad object (Pad1, Pad2, ... PadN) for each game pad supported by the platform.

On Xbox One and PlayStation 4, the Pad interfaces represent the native gamepad controllers for the console.

On Windows, the Pad interfaces represent connected Xbox controllers. Any connected PlayStation 4 controllers are represented by the PS4Pad1 to PS4Pad4 interfaces instead.

Xbox One

The following button and axis names are available for Xbox One controllers on both Windows and Xbox One.

Xbox One button names

  • d_up, d_down, d_left, d_right: The directional pad.
  • start, back
  • left_thumb, right_thumb: Indicates when the thumbsticks are pressed in, not directional movements.
  • left_shoulder, right_shoulder
  • left_trigger, right_trigger
  • a, b, x, y

Xbox One axis names

  • left, right: the direction of the left and right thumbsticks.
  • dpad: the directional pad represented as an axis.

PlayStation 4

The following button and axis names are only available for PlayStation 4 controllers in a game running on Playstation 4.

PlayStation 4 button names

  • triangle, circle, cross, square
  • l1 and r1: the left and right trigger buttons.
  • l2 and r2: the left and right trigger buttons (analog).
  • l3 and r3: indicates when the left and right thumbsticks are pressed in, not directional movements.
  • up, right, down, left: the separate buttons on the directional pad.
  • options

PlayStation 4 axis names

  • dpad: the directional pad represented as an axis.
  • left and right: the direction of the left and right thumbsticks.
  • orientation_forward, orientation_right, orientation_up: the forward, right, and up directions of the orientation sensor.
  • acceleration, angular_velocity: The acceleration and angular velocity measured by the accelerometer.
  • touch_1, touch_2: the first two touch points on the touch pad. Returned as Vector3(x, y, id), where id is an integer that identifies this touch event. If nothing is touched, returns Vector3(0,0,-1).

Getting values from buttons and axes

All types of input controllers have built-in sets of named buttons and "axes" that represent the different ways users can provide input to the controller.

  • Each button can be pressed or released in any given frame. You can detect these events by calling pressed() and released(). The controller will also produce a value between 0 and 1 for that button, which you can retrieve by calling button().
  • Each axis can produce a Vector3 value. In some cases this value is normalized: typically when the axis indicates a variable value along some kind of scale, such as the direction a player is pushing a thumbstick. For example, a thumbstick on a game pad might be pushed fully to the left (1,0,0), fully up (0,1,0), diagonally left and up (0.707107, 0.707107, 0), etc. Alternatively, in some cases axes produce coordinate values in 3D space or in 2D screen space.

To check if the keyboard button k is pressed, you would use:

local k_key_id = stingray.Keyboard.button_id("k")      -- retrieve the button ID
local isPressed = stingray.Keyboard.button(k_key_id)   -- use the ID to access the value

Similarly, to get the current position of the Windows mouse cursor in 2D screen space, you would use:

local cursor_axis_id = stingray.Mouse.axis_id("cursor")    -- retrieve the axis ID
local value = stingray.Mouse.axis(cursor_axis_id)          -- use the ID to access to value

Or, to get the direction the player is pushing the right thumbstick on a game pad, you would use:

local right_axis_id = stingray.Pad1.axis_id("right")
local value = stingray.Pad1.axis(right_axis_id)

Getting all button and axis names

The names of the buttons and axes you can query are different for each kind of controller, and may be different on different platforms. If you need to check the available buttons for a device, you can retrieve a current list by running the following snippets of code in the Status Bar of the editor, or in your game project. Replace Mouse with the name of the controller whose values you want to check.

Functions

Parameters
This function does not accept any parameters.
Returns

boolean

Returns true if the controller is active, or false otherwise.

Parameters
This function does not accept any parameters.
Returns

string

One of the following values: gamepad, touch_panel, mouse or keyboard.

Parameters
This function does not accept any parameters.
Returns

boolean

Returns true if the controller was attached this frame, or false otherwise.

Parameters
This function does not accept any parameters.
Returns

boolean

Returns true if the controller was disconnected this frame, or false otherwise.

Parameters
This function does not accept any parameters.
Returns

string

A string that contains a unique name for the controller.

In most cases this name will be a variant of the string returned by type(), with an additional counter added.

Parameters
This function does not accept any parameters.
Returns

string

A string that describes the type of the controller device.

This identifier will be the same for all controllers of the same model (with some exceptions): e.g. xbox_controller, logitech_mx518_mouse or generic_105_key_keyboard. Note that this value may be the same regardless of the input device model on some platforms.

Parameters
This function does not accept any parameters.
Returns

integer?

The Xbox Live or PSN ID of the user using the pad, or nil if there is no user connected to the pad.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

Only available in games running on PlayStation 4 and Xbox One, not on Windows.

Buttons and axes

The functions in this group relate to getting values from the buttons and axes tracked by this controller.

Parameters
This function does not accept any parameters.
Returns

integer?

The id of the first button that the player pressed this frame, or nil if the player did not press any buttons.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

If so, returns the id of the first button the player pressed.

Parameters
This function does not accept any parameters.
Returns

integer?

The id of the first button that the player released this frame, or nil if the player did not release any buttons.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

If so, returns the id of the first button the player released.

Parameters

id :

integer

The id of the axis whose value will be retrieved.

dead_zone_mode :

integer?

Specifies the kind of dead zone to be applied before returning the value read from the controller. This value may be any of the dead zone mode constants. If you specify this parameter, you must also specify the dead_zone_size. If omitted, the default dead zone values you set using [InputController.set_dead_zone()] are used.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

dead_zone_size :

number?

The size of the dead zone to apply to the value read from the controller.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Returns

stingray.Vector3

The input value of the controller for the axis with the specified id.

Note that the dead zone configuration controls are only available for non-touch interfaces.

Parameters

id :

integer

The id of the axis whose name you want to retrieve.

Returns

string

The name of the axis.

Parameters

id :

integer

The id of the button whose value you want to retrieve.

Returns

number

The current value of the button, expressed as a value between 0 and 1.

Parameters

name :

string

The name of the button whose id you want to retrieve.

Returns

integer

The id of the button, or nil if no button is found with a matching name.

Parameters

id :

integer

The id of the button whose name you want to retrieve.

Returns

string

The name of the button in the locale set for the controller.

This is typically useful only for keyboard controllers.

Parameters

id :

integer

The id of the button whose name you want to retrieve.

Returns

string

The name of the button, or an empty string if no button is found with a matching id.

Parameters
This function does not accept any parameters.
Returns

integer

The number of axes on the controller.

Parameters
This function does not accept any parameters.
Returns

integer

The number of buttons on the controller.

Parameters

id :

integer

The id of the button you want to test.

Returns

boolean

Returns true if the player pressed the button during this frame, of false otherwise.

Parameters

id :

integer

The id of the button you want to test.

Returns

boolean

Returns true if the player released the button during this frame, of false otherwise.

Dead zones

A "dead zone" is a region in which the input values read by the controller are clamped to zero.

When a controller such as a thumbstick becomes old or loose, its "at-rest" position may cause a small input value to be sent to the game engine, even though the player is not actively pressing on the controller. This can cause visual artifacts such as characters or cameras that continually rotate or slide.

The dead zone mitigates this problem by applying minimum thresholds to the input values, below which the values are assumed to be noise rather than intentional input from the player.

Input values that fall inside the circle are ignored.

Input values that fall inside the square are ignored.

The engine provides the raw input values read from the controller.

Parameters

id :

integer

The id of the axis whose dead zone value will be retrieved.

Returns

integer

Specifies the kind of dead zone that will be applied when accessing the value read from the controller for the specified axis. This value may be any of the dead zone mode constants.

number

The size of the dead zone to apply to the value read from the controller.

Parameters

id :

integer

The id of the axis whose default dead zone will be set.

dead_zone_mode :

integer

Specifies the kind of dead zone to be applied before returning the values read from the controller. This value may be any of the dead zone mode constants.

dead_zone_size :

number

The size of the dead zone to apply to the values read from the controller.

Returns
This function does not return any values.

These default dead zone values will be called when you retrieve the controller's input value for an axis by calling axis() without specifying any dead zone settings in your function call.

Rumble

The engine has a built-in rumble effect system that lets you play rumble pulses with specific strength and duration on supporting devices.

When you use the rumble effect system, you only need to call rumble_effect() once to start a rumble effect. The engine will take care of modulating the rumble and fade it out at the end of its duration. If there are multiple rumble effects in play, their effects are added.

A rumble effect works analogously to a synthesizer note: it is a sine wave played within an ADSR-envelope (see http://en.wikipedia.org/wiki/Synthesizer#ADSR_envelope).

If you need more detailed control over the rumbling, you can use the set_rumble() method instead. That method allows you to directly set the rumble strength of each motor. Note that if you use this method, you are responsible for fading out the rumbles, and for applying any changes you want.

If you use both rumble_effect() and set_rumble(), the values are added.

The functions in this category are only useful for input controllers that contain rumble motors, like console gamepads.

Rumble motor names

The names of the rumble motors are:

Xbox One controllers:

  • left
  • right
  • left_trigger (only available when running on Xbox One, not on Windows.)
  • right_trigger (only available when running on Xbox One, not on Windows.)

PlayStation 4 controllers:

Rumble settings are only available for PlayStation 4 when running on a PlayStation 4, not when using a PlayStation 4 controller on Windows.

  • small
  • large
Parameters

motor_id :

integer

The id of the rumble motor you want to test.

ID :

integer

The ID of the rumble effect.

Returns

boolean

Returns true if a rumble event with the specified ID was created by a call to rumble_effect() and that effect is still playing, or false otherwise.

Parameters
This function does not accept any parameters.
Returns

integer

The number of rumble motors in the controller.

Parameters

motor_id :

integer

The id of the rumble motor you want to activate.

params :

input_rumble_params

A table that provides detailed settings for the new rumble effect.

Returns

integer

An ID for the newly created rumble effect.

Parameters

motor_name :

string

The name of the rumble motor whose id you want to retrieve.

Returns

integer?

The id of the rumble motor, or nil if no such motor exists.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Parameters

motor_id :

integer

The id of the rumble motor whose name you want to retrieve.

Returns

string

The name of the rumble motor.

Parameters

motor_id :

integer

The id of the rumble motor you want to activate.

value :

number

The strength of the rumble to set, expressed as a value between 0 (no rumble) and 1 (full strength).

Returns
This function does not return any values.

The rumble continues at the same strength until you change it either by calling set_rumble() again, or by calling rumble_effect().

Parameters

do_rumble :

boolean

Use true to enable the rumble engine for this controller, or false to disable rumbling.

Returns
This function does not return any values.
Parameters

motor_id :

integer

The id of the rumble motor you want to deactivate.

Returns
This function does not return any values.
Parameters

motor_id :

integer

The id of the rumble motor you want to deactivate.

ID :

integer

The ID of the rumble effect.

Returns
This function does not return any values.

Deprecated functions

Use the _id versions of these functions instead.

Parameters

name :

string

The name of the axis whose id you want to retrieve.

Returns

integer

The index of the axis, or nil if no axis is found with a matching name.

Axes must be referred to by IDs, not indices. Please use axis_id() instead.

Parameters

name :

string

The name of the button whose id you want to retrieve.

Returns

integer

The index of the button, or nil if no button is found with a matching name.

Buttons must be referred to by IDs, not indices. Please use button_id() instead.

Parameters

motor_name :

string

The name of the rumble motor whose id you want to retrieve.

Returns

integer?

The index of the rumble motor, or nil if no such motor exists.

The ? notation indicates that this type is optional: there may be zero or one instances of it.

Rumble motors must be referred to by IDs, not indices. Please use rumble_motor_id() instead.

PlayStation 4 pads

The functions in this category are only available for PlayStation 4 pads.

Note that PlayStation 4, users can be logged in on pads. Unless your game is specified as a single player game, users can log in and log out at any time. Therefore you need to call user_id() in your main loop to poll for changes.

Parameters

color :

color

The new color for the light bar.

Returns
This function does not return any values.

Only available for PlayStation 4 pads in games running on the PlayStation 4.