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

stingray.SimulatedTouchPanel1 namespace reference
Functions | Buttons and axes | Contacts | Gestures | Deprecated functions
expand all | collapse all

Description

Represents a mouse-simulated touch panel, available only on Windows platforms.

In order to read values from this controller, you need to enable it in your game at runtime by calling [set_enabled()] or by triggering the Input/Touch/Set Simulated Touch Enabled Flow node.

When enabled, the simulated touch panel responds to mouse input as follows:

  • Pressing the left mouse button creates a simulated contact at the current cursor location, staying active with the same ID and following the cursor until the button is released.

  • Pressing the right mouse button while the left button is down creates a "ghost" contact. The location of this ghost contact is determined by reflecting the location of the main contact around the coordinates at which the right mouse button was initially pressed. So, at first, the two contacts will be at the same location. As you move the mouse pointer away from that initial location, the location of the ghost contact will diverge from the position of the main contact point in the opposite direction.

  • Pressing the middle mouse button and/or the second extra mouse button (if any) will record a value that you can retrieve from the back button.

  • Pressing the first extra button while the left button is down simulates a sideways tilt based on the current touch location, which you can retrieve from the accelerometer axis.

Button names

  • back

Axis names

  • accelerometer

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

Getting values from touch contacts

In addition to the buttons and axes offered by all types of controllers, touch panels maintain a set of "contacts" that represent the places where the player is touching the screen. These contacts are identified by numeric IDs, which you can retrieve by calling contacts(). You can then query for details about each contact by passing its ID to the other functions listed under Contacts below.

Touch interface location values are provided as screen-space coordinates, measured in pixels.

For example, you can get the (X,Y) screen coordinates of a contact position by calling location():

local contacts = {stingray.TouchPanel1.contacts()} -- the {} puts the return values into a table
for _, id in ipairs(contacts) do
    if stingray.TouchPanel1.is_touch_down(id) then       -- when the screen is touched
        local pos = stingray.TouchPanel1.location(id)    -- get the position
    end
end

Functions

Parameters
This function does not accept any parameters.
Returns

stingray.Vector3

The accelerator resolution for the controller.

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

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.

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

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.

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, 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.

Contacts

The functions in this group are used to get finger touch data from the touch controller.

Parameters
This function does not accept any parameters.
Returns

integer*

Returns the indices of all current contacts.

The * notation indicates that there may be zero or more instances of the specified type.
Parameters

contact_id :

integer

The id of the contact to test.

Returns

string?

If this contact originated on an edge of the touch panel, this string will be one of the following values: TOP, BOTTOM, RIGHT, or LEFT. If this contact did not originate at an edge, or if edge detection is unsupported by this device, this function returns nil.

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

Available on Android platforms only.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact exists, or false otherwise.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact is the primary contact.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact was initiated in this frame.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

boolean

Returns true if the contact was released in this frame.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

stingray.Vector3

The X,Y coordinates of the contact's current position.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

stingray.Vector3

The change in the contact's X,Y coordinates in this frame.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The size of the specified contact on the major axis, in pixels.

Available on Android platforms only.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The size of the specified contact on the minor axis, in pixels.

Available on Android platforms only.

Parameters
This function does not accept any parameters.
Returns

integer

The number of currently active touch contacts.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The pressure of the specified contact on the touch panel.

Available on Android platforms only.

Parameters
This function does not accept any parameters.
Returns

stingray.Vector3

The resolution of the input coordinates for the controller.

This usually maps 1:1 to pixels on the X and Y axes. The Z-axis coordinate contains the maximal pressure value for contacts.

Parameters

contact_id :

integer

The id of the contact to test.

Returns

number

The size of the specified contact.

This is a normalized value relative to the largest possible touch contact that the device can sense. The smallest possible normalized size is 0.0 (no contact, or it is unmeasurable), and the largest possible normalized size is 1.0 (the sensor area is saturated). Available on Android platforms only.

Gestures

The functions in this group are used gesture data from the touch controller.

Parameters
This function does not accept any parameters.
Returns

stingray.Vector2?

Returns the location of where the long press gesture began.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Parameters
This function does not accept any parameters.
Returns

boolean?

Returns whether the gesture began during the last frame.

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

boolean?

Returns whether the gesture ended during the last frame.

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

stingray.Vector2?

Returns the center-location of where the gesture began.

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

number?

Returns the current scale value of the pinch gesture.

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

number?

Returns the current scale_per_second value of the pinch gesture.

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

While in low frame-rate, begin and ended might both return true in the same call.

Parameters
This function does not accept any parameters.
Returns

boolean?

Returns whether the gesture began during the last frame.

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

boolean?

Returns whether the gesture ended during the last frame.

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

stingray.Vector2?

Returns the center-location of where the gesture began.

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

number?

Returns the total accumulated rotation value of the gesture displayed in radians.

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

number?

Returns the current rotation per second value of the gesture.

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

While in low frame-rate, begin and ended might both return true in the same call.

Parameters
This function does not accept any parameters.
Returns

stingray.SwipeDirection?

Returns the direction of the swipe.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Parameters
This function does not accept any parameters.
Returns

stingray.Vector2?

Returns the location of the most recent non-sequence tap.

The ? notation indicates that this type is optional: there may be zero or one instances of it.
Parameters
This function does not accept any parameters.
Returns

number?

Returns the number of subsequent taps. (2-5 on iOS, unlimited on Android)

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

stingray.Vector2?

Returns the location of the most recent tap.

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

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.

Please send us your comment about this page