stingray.Pad4 namespace reference

Description

A global singleton that represents the fourth 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.

-- get button names
local button_id = 0
while button_id < stingray.Mouse.num_buttons() do
    print(stingray.Mouse.button_name(button_id))
    button_id = button_id +1
end
-- get axis names
local axis_id = 0
while axis_id < stingray.Mouse.num_axes() do
    print(stingray.Mouse.axis_name(axis_id))
    axis_id = axis_id +1
end

Other related reference items

	stingray.PS4Pad1 stingray.PS4Pad2 stingray.PS4Pad3 stingray.PS4Pad4
	User Input

Functions

active ( ) : boolean Indicates whether or not the controller is active: i.e. connected and working as expected.

Parameters

This function does not accept any parameters.

Returns

boolean

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

category ( ) : string Returns a string that describes the category of input device this controller falls into.

Parameters

This function does not accept any parameters.

Returns

string

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

connected ( ) : boolean Indicates whether or not the controller has been attached this frame.

Parameters

This function does not accept any parameters.

Returns

boolean

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

disconnected ( ) : boolean Indicates whether or not the controller has been disconnected this frame.

Parameters

This function does not accept any parameters.

Returns

boolean

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

name ( ) : string Returns a unique name for the controller: e.g. "Xbox Controller 1".

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.

type ( ) : string Returns a description of the hardware device used for this controller.

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.

Other related reference items

stingray.Pad4.name()

user_id ( ) : integer? Returns the user id of the user using the pad.

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.

any_pressed ( ) : integer? Indicates whether or not the player pressed any buttons at all in the current frame.

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.

any_released ( ) : integer? Indicates whether or not the player released any buttons at all in the current frame.

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.

axis ( id, dead_zone_mode, dead_zone_size ) : stingray.Vector3 Returns the input value for a single axis of the controller.

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.

axis_id ( name ) : integer Retrieves the id of the axis with the specified name in the controller, if any.

Parameters

name :

string

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

Returns

integer

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

Other related reference items

stingray.Pad4.axis_index()

axis_name ( id ) : string Retrieves the name of the axis with the specified id in the controller.

Parameters

id :

integer

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

Returns

string

The name of the axis.

button ( id ) : number Returns the current input value of the button with the specified id.

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.

button_id ( name ) : integer Retrieves the id of the button with the specified name in the controller, if any.

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.

Other related reference items

stingray.Pad4.button_index()

button_locale_name ( id ) : string Retrieves the name of the specified button, respecting the locale set for the device.

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.

button_name ( id ) : string Retrieves the name of the button with the specified id in the controller.

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.

num_axes ( ) : integer Returns the number of axes on the controller.

Parameters

This function does not accept any parameters.

Returns

integer

The number of axes on the controller.

num_buttons ( ) : integer Returns the number of buttons on the controller.

Parameters

This function does not accept any parameters.

Returns

integer

The number of buttons on the controller.

pressed ( id ) : boolean Indicates whether or not the player pressed the button with the specified id during this frame.

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.

released ( id ) : boolean Indicates whether or not the player released the button with the specified id during this frame.

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.

CIRCULAR : integer Specifies a dead zone whose size value is interpreted as the radius of a circle.

Input values that fall inside the circle are ignored.

INDEPENDENT : integer Specifies a dead zone whose size value is applied independently along each cooordinate axis, making the dead zone a square box.

Input values that fall inside the square are ignored.

RAW : integer Specifies no dead zone at all.

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

dead_zone ( id ) : integer, number Returns the current dead zone settings for the specified axis on this 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.

set_dead_zone ( id, dead_zone_mode, dead_zone_size ) Sets the default dead zone values for a single axis of 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

is_rumble_effect_playing ( motor_id, ID ) : boolean Indicates whether or not the specified rumble event is playing on the specified motor.

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.

num_rumble_motors ( ) : integer Retrieves the number of rumble controllers supported by this kind of controller.

Parameters

This function does not accept any parameters.

Returns

integer

The number of rumble motors in the controller.

rumble_effect ( motor_id, params ) : integer Starts a new rumble effect on the specified motor.

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.

Other related reference items

stingray.Pad4.is_rumble_effect_playing() stingray.Pad4.set_rumble() stingray.Pad4.stop_all_rumble_effects() stingray.Pad4.stop_rumble_effect()

rumble_motor_id ( motor_name ) : integer? Retrieves the id of the rumble motor with the specified name.

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.

Other related reference items

stingray.Pad4.rumble_motor_index()

rumble_motor_name ( motor_id ) : string Retrieves the name of the rumble motor with the specified id.

Parameters

motor_id :

integer

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

Returns

string

The name of the rumble motor.

set_rumble ( motor_id, value ) Starts a new rumble effect on the specified 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().

set_rumble_enabled ( do_rumble ) Determines whether or not the rumble engine should be enabled for this controller.

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.

stop_all_rumble_effects ( motor_id ) Stops all rumble effects previously created by calls to rumble_effect().

Parameters

motor_id :

integer

The id of the rumble motor you want to deactivate.

Returns

This function does not return any values.

stop_rumble_effect ( motor_id, ID ) Stops a rumble effect that was previously created by a call to rumble_effect().

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.

axis_index ( name ) : integer Deprecated.

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.

button_index ( name ) : integer Deprecated.

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.

rumble_motor_index ( motor_name ) : integer? Deprecated.

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.

set_light_bar_color ( color ) Sets the light bar on the controller to the specified color.

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.