Description

A global singleton that represents the third connected PS4 game pad on Windows.

There is a separate pad object (PS4Pad1, PS4Pad2, ... PS4PadN) for each PS4 game pad supported on Windows.

Note: the PS4Pad interfaces are only used for games running on Windows. For games running on PlayStation 4, the native console game pads are represented using the Pad1 to Pad4 interfaces instead.

New PS4 controllers connected to the PC after startup are not automatically detected. Use stingray.Application.scan_for_windows_ps4_controllers() to detect if controllers have been connected.

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
options, share, ps
touch: indicates when the touchpad is touched.

Axis names

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

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

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

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

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

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

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

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.

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

Description

Button names

Axis names

Getting values from buttons and axes

Getting all button and axis names

Functions

active ( ) : boolean

category ( ) : string

connected ( ) : boolean

disconnected ( ) : boolean

name ( ) : string

type ( ) : string

user_id ( ) : integer?

Buttons and axes

any_pressed ( ) : integer?

any_released ( ) : integer?

axis ( id, dead_zone_mode, dead_zone_size ) : stingray.Vector3

axis_id ( name ) : integer

axis_name ( id ) : string

button ( id ) : number

button_id ( name ) : integer

button_locale_name ( id ) : string

button_name ( id ) : string

num_axes ( ) : integer

num_buttons ( ) : integer

pressed ( id ) : boolean

released ( id ) : boolean

Dead zones

CIRCULAR : integer

INDEPENDENT : integer

RAW : integer

dead_zone ( id ) : integer, number

set_dead_zone ( id, dead_zone_mode, dead_zone_size )

Rumble

Rumble motor names

Xbox One controllers:

PlayStation 4 controllers:

is_rumble_effect_playing ( motor_id, ID ) : boolean

num_rumble_motors ( ) : integer

rumble_effect ( motor_id, params ) : integer

rumble_motor_id ( motor_name ) : integer?

rumble_motor_name ( motor_id ) : string

set_rumble ( motor_id, value )

set_rumble_enabled ( do_rumble )

stop_all_rumble_effects ( motor_id )

stop_rumble_effect ( motor_id, ID )

Deprecated functions

axis_index ( name ) : integer

button_index ( name ) : integer

rumble_motor_index ( motor_name ) : integer?

PlayStation 4 pads

set_light_bar_color ( color )