Construct 3 icon

Construct 3

Documentation

Touch

Published 23 Aug, 2017
1,489 words
~6-10 mins

The Touch object detects input from touchscreen devices like phones and tablets, as well as desktops or laptops with touch-sensitive displays.

The Touch object also provides input from the accelerometer (motion) and inclinometer (tilt/compass direction) if the device supports them. Note some low-end devices lack the necessary hardware to measure these values.

It is best to support touch input wherever possible. On the web many users browse on mobile devices with touch input only and no mouse or keyboard. If your game does not support touch controls, many users will be unable to play your game at all. For a guide on how to implement on-screen touch controls, see the tutorial on Touch controls.

For a number of examples of using Touch input, search for Touch in the Start Page.

Multi-touch

The Touch object supports multi-touch. This is most useful with the On touched object and Is touching object conditions, which can for example detect if multiple on-screen touch controls are being used. This is sufficient for many games.

For more advanced uses, the TouchID, XForID and YForID expressions can be used to track individual touches for different purposes. Each touch has a unique ID (which is an arbitrary number), and can be accessed using the TouchID expression in an event like On any touch start. The touch ID can then be stored in a variable and tracked using the XForID and YForID expressions. Finally comparing the TouchID in On any touch end indicates when that touch has been released.

Touch properties

Use mouse input

If enabled, mouse clicks will simulate touch events. Clicking and dragging the left mouse button will simulate a touch along where mouse dragged, and single clicks will simulate taps. This can be very useful for testing touch events work properly on a desktop computer with no touch input supported. However, only single-touch input can be simulated with a mouse, and a mouse is much more precise than a touch, so it is still best to test on a real touchscreen device.

Touch conditions

On double-tap

On double-tap object

Triggered when two tap gestures are performed in quick succession in the same location. The On double-tap object variant triggers when this gesture is performed over an object.

On hold

On hold over object

Triggered when a touch is held (pressed and not moved) for a short time period. The On hold over object variant triggers when this gesture is performed over an object.

On tap

On tap object

Triggered when a tap gesture is performed, which is defined as a touch and release in quick succession in the same location. The On tap object variant triggers when this gesture is performed over an object.

Compare acceleration

Compare the current device's motion as its acceleration on each axis in m/s^2 (meters per second per second). The effect of gravity can be included or excluded, but note that some devices only support accelerometer values including the effect of gravity and will always return 0 for acceleration excluding gravity.

Compare orientation

Compare the device's current orientation, if the device has a supported inclinometer. Alpha is the compass direction in degrees. Beta is the device front-to-back tilt in degrees (i.e. tilting forwards away from you if holding in front of you). A positive value indicates front tilt and a negative value indicates back tilt. Gamma is the device left-to-right tilt in degrees (i.e. twisting if holding in front of you). A positive value indicates right tilt and a negative value indicates left tilt.

Compare touch speed

Compare the speed of a specific touch (given by its zero-based index). Touch speed is measured in canvas pixels per second, so is not affected by scaling the display.

Has Nth touch

True if a given touch number is currently in contact with the screen. For example, Has touch 1 will be true if there are two or more touches currently in contact with the screen (given that it is a zero-based index).

Is in touch

True if any touch is currently in contact with the screen.

Is touching object

True if any touch is currently touching a given object.

On any touch end

Triggered when any touch releases from the screen.

On any touch start

Triggered upon any touch on the screen.

On Nth touch end

Triggered when a given touch number releases from the screen. For example, On touch 1 end will trigger when releasing the second simultaneous touch (given that it is a zero-based index).

On Nth touch start

Triggered when a given touch number touches the screen. For example, On touch 1 start will trigger upon the second simultaneous touch (given that it is a zero-based index).

On touched object

Triggered when a given object is touched.

Touch actions

The Touch object has no actions.

Touch expressions

AccelerationX

AccelerationY

AccelerationZ

Get the current device's motion as its acceleration on each axis in m/s^2 (meters per second per second) excluding the effect of gravity. The expressions which include gravity (below) are more widely supported; these will return 0 at all times on devices which do not support them.

AccelerationXWithG

AccelerationYWithG

AccelerationZWithG

Get the current device's motion as its acceleration on each axis in m/s^2 (meters per second per second) including the acceleration caused by gravity, which is about 9.8 m/s^2 down at all times. For example, at rest, the device will report an acceleration downwards corresponding to the force of gravity. These expressions are more commonly supported than the expressions returning acceleration without G (above). However, devices are still not guaranteed to support motion detection, in which case these will return 0 at all times.

Alpha

Beta

Gamma

Return the device's orientation if supported, or 0 at all times if not supported. Alpha is the compass direction in degrees. Beta is the device front-to-back tilt in degrees (i.e. tilting forwards away from you if holding in front of you). A positive value indicates front tilt and a negative value indicates back tilt. Gamma is the device left-to-right tilt in degrees (i.e. twisting if holding in front of you). A positive value indicates right tilt and a negative value indicates left tilt.

AbsoluteX

AbsoluteY

AbsoluteXAt(index)

AbsoluteYAt(index)

AbsoluteXForID(id)

AbsoluteYForID(id)

Return the current position of a touch over the canvas area. This is (0, 0) at the top left of the canvas and goes up to the window size. It is not affected by any scrolling or scaling in the game. The At expressions can return the absolute position of any touch given its zero-based index, and the ForID expressions return the position of a touch with a specific ID.

X

Y

XAt(index)

YAt(index)

XForID(id)

YForID(id)

Return the current position of a touch in layout co-ordinates. It changes to reflect scrolling and scaling. However, if an individual layer has been scrolled, scaled or rotated, these expressions do not take that in to account - for that case, use the layer versions below. The At expressions can return the position of any touch given its zero-based index, and the ForID expressions return the position of a touch with a specific ID.

X(layer)

Y(layer)

XAt(index, layer)

YAt(index, layer)

XForID(id, layer)

YForID(id, layer)

Return the current position of a touch in layout co-ordinates, with scrolling, scaling and rotation taken in to account for the given layer. The layer can be identified either by a string of its name or its zero-based index (e.g. Touch.X("HUD")). The At expressions can return the position of any touch on a layer given its zero-based index, and the ForID expressions return the position of a touch with a specific ID.

TouchCount

Number of touches currently in contact with the device's screen.

TouchID

Return the unique ID of a touch (which is an arbitrary number) in an event like On any touch start or On any touch end.

TouchIndex

Return the zero-based index of the touch in an event like On any touch start or On any touch end.

AngleAt(index)

AngleForID(id)

Get the angle of motion of a specific touch in degrees by its zero-based index or unique ID. A touch must be moving across the device screen for this expression to contain a useful value.

WidthForID(id)

HeightForID(id)

Return the width and height of a touch with a given ID in pixels. This allows the app to determine the approximate size of the touch area. Note some platforms do not support this and will always return 0 for the touch size.

PressureForID(id)

Return the pressure of a touch with a given ID, as a number from 0 (least detectable pressure) to 1 (most detectable pressure). This is useful for devices with pressure-sensitive displays. Note however not all devices have pressure-sensitive displays, and so will always return 0 for the pressure.

SpeedAt(index)

SpeedForID(id)

Get the speed of a specific touch by its zero-based index or unique ID. Touch speed is measured in canvas pixels per second, so is not affected by scaling the display.