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:

• Scripting Overview
• Scripting Events