Touch Input
Introduction
You can add interactivity to the Lenses you create in Lens Studio by handling user touch input events. Your Lens can play a sound, trigger a character animation, and more by listening for events when the user touches the screen of their device.
This guide provides an overview of the available touch events in Lens Studio, as well as instruction in handling user touch events in a Lens.
Scripting
This guide assumes you are familiar with the basics of scripting in Lens Studio. To learn more about scripting, please visit the Scripting Overview.
Touch Events Overview
Lenses can handle and respond to a number of user touch events, including when a touch starts or ends, when the user taps the screen, and when the user moves a held touch across the screen.
Touch Started
This event is triggered when the user starts a screen touch.
Touch Moved
This event is triggered when the user moves their finger while holding a screen touch (i.e. while dragging on the screen).
Touch Ended
This event is triggered when the user ends a screen touch (i.e. when the user lifts their finger off of the screen).
Tapped
This event is triggered when the user taps the screen (i.e. when they quickly start and stop a touch).
Requires Touch Blocking
To handle the Tapped event, your Lens needs to enable touch blocking.
Note
If your Lens does not use touch blocking, user touches will trigger default actions--such as double-tapping to switch the camera, and long-pressing to trigger Scan
Events
To learn more about events in Lens Studio, please visit the Script Events Guide.
Handling Touch Events
User touch input is handled by assigning scripts to the events described above. In Lens Studio, touch input events can come from touching the screen, or from touching a specific 3D object in the scene.
Touching the Screen
Lenses can respond to touch events that trigger when the user touches the screen. For example, your Lens can play a sound any time the user touches the screen.
The following guide will walk you through setting up a screen-based Touch Started event.
Set up the Script Component
Add a Script Component to a Scene Object.
On the new Script component, select Add Script
.

In the Script selection popup dialog, select + -> Create Empty
Bind the Script to the "Touch Started" event by selecting it from the Script Component's dropdown.

Select the new Script from the Resources panel. Open it in the Script Editor by double clicking it and the following lines and save the script:
// Set the object's scale to a random value.
var min = 0.1;
var max = 1.5;
var newScale = Math.random()*(max - min) + min;
script.getTransform().setWorldScale(new vec3(newScale, newScale, newScale));
Preview the Project
Preview the Lens on your device. You should see a sphere rendered on the screen. When you touch anywhere on the screen, the sphere will randomly change in scale.

Touching a 3D Object
Lenses can respond to touch events that trigger when the user touches a 3D object. This is useful for cases when the user should interact with a specific object in the scene. For example, when the user taps on a 3D character in your Lens, that character plays an animation. This type of interaction is implemented in the Interactive Tap Template.
Touch events on 3D Objects are enabled by adding a Touch Component. The Touch Component keeps references to Mesh Visual components in the scene. When any of these Mesh Visuals are touched or tapped by the user, a touch event will be triggered.
The following guide will walk you through setting up a Touch Started event on a 3D object.
Set up the Touch Component
Add a Touch
Component to a Scene Object.
On the new Touch
Component, select Choose Mesh Visual
.

Select the Mesh Visual component from your Scene Object.
Touch Component and Mesh Visuals
The Touch Component can only be used on Scene Objects that have a Mesh Visual component. If you do not explicitly add a Mesh Visual reference to the Touch Component, it will try to find one on the Scene Object.
Set the Camera property to the Camera component in your scene.

Default Camera
If you don't set the Camera property on a Touch Component, it will use the Scene's current main camera by default.
Set up the Script Component
Add a Script
Component to the Scene Object.
On the new Script
component, select Add Script
.

In the Script selection popup window, select + -> Create Empty
Bind the Script to the "Touch Started" event by selecting it from the Script Component's dropdown.

Select the new Script from the Resources panel. Open it in the Script Editor by double clicking it and the following lines and save the script:
// Set the object's scale to a random value.
var min = 0.1;
var max = 1.5;
var newScale = Math.random()*(max - min) + min;
script.getTransform().setWorldScale(new vec3(newScale, newScale, newScale));
Preview the Project
Preview the Lens on your device. You should see a sphere rendered on the screen. When you touch the sphere, it will randomly change in scale.

Touch Bounds
The Touch Component uses the Mesh Visual's bounding box to determine the touch target. Keep this in mind as you set up your touch interactions.
Touch Blocking
There may be times when you want your Lens to receive all touch events to prevent the user from unintentionally triggering other Snapchat actions while using your Lens. For example, if your Lens has a rapid tapping interaction you may want to override Snapchat's default behavior of switching cameras on double-tap.
In these instances, you can make use of Touch Blocking. With Touch Blocking, you can override some or all of Snapchat's default touch behaviors.
Basic Use
To override the Snapchat app's default touch events, add the following line to a script bound to the "Lens Turned On" event:
global.touchSystem.touchBlocking = true;
With this line included, your Lens will override all of the app's default screen touch events.
Touch System
The global property global.touchSystem
is a TouchDataProvider object used to manage touch blocking exceptions.
Touch Blocking Exceptions
You may not want to override all of the default Snapchat touch events. For example, you may want to override the double-tap event, but still allow the user to swipe to Stories or Chat. In this instance, you can make use of Touch Blocking Exceptions.
Usage
To make an exception for a specific type of touch, add the following code to a script bound to the "Lens Turned On" event:
global.touchSystem.touchBlocking = true;
global.touchSystem.enableTouchBlockingException("TouchTypeSwipe", true);
In the example above, the Lens overrides all of the default touch events, but makes an exception for screen swipes. Enabling this exception allows the user to still swipe into another view of Snapchat (like Stories or Chat) while the Lens is active.
You can replace the string TouchTypeSwipe
with any of the Touch Types listed in the section below.
Exception Types
You can enable or disable the following Touch Type Exceptions:
TouchTypeTap: Enabling this exception allows Snapchat to continue handling the tap gesture.
TouchTypeDoubleTap: Enabling this exception allows Snapchat to continue handling the double-tap gesture.
TouchTypeScale: Enabling this exception allows Snapchat to continue handling the two-finger pinch gesture.
TouchTypePan: Enabling this exception allows Snapchat to continue handling the two-finger pan gesture.
TouchTypeSwipe: Enabling this exception allows Snapchat to continue handling the swipe gesture.
Related Documentation
Please refer to the guides below for additional information:
Still Looking for help?
Visit Support