Touch

The Touch object detects input from touchscreen devices like iPhones, iPads, Android and Windows 8 devices. Touchscreens for desktop computers are also available, but these are rare compared to mobiles, so generally the Touch object is used in anticipation of input on a mobile device.

The Touch object also provides input from the accelerometer (motion) and inclinometer (tilt/compass direction) if the device supports them.

It is best to support touch input wherever possible. On the modern web many users are now browsing 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 dialog.

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 set to Yes, 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(0)). 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, such as the iPhone 6S. 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.