Script Events
Introduction
This guide provides a breakdown of Lens Events available. Scripts are triggered by binding them to these events. By default, all scripts are bound to the On Awake
Event.
Lens Events
We've broken down the events into four categories: Scene, Camera, Touch and Other.
For a technical reference of all Lens Events, please visit the Events API Reference.
Scene Events
These events are tied to the timing and execution of the Lens Scene. The ordering in which the scene objects are placed in the scene hierarchy will determine the execution time.
On Awake
Scripts bound to this event will trigger before any other event in the Lens (including OnStart
and Update
). It also fires immediately on a newly instantiated or copied object, for instance before returning from createComponent. OnAwake
should be used for a script to configure itself or define its API but not to access other ScriptComponents since they may not have yet received OnAwake
themselves.
Scripting API
On Start
Scripts bound to this event will trigger before Update
on the first frame a Component is enabled. This will be after all OnAwake
events have triggered on the first frame and after a createComponent caller has had an opportunity to configure the Component. OnStart
should be used to do initialization that depends on inputs or to access other Components which will have defined their inputs and methods during OnAwake
.
Scripting API
On Destroy
Scripts bound to this event will trigger once the Script Component associated with the script has been destroyed while the Lens is running.
Scripting API
On Enable
Scripts bound to this event will trigger once the associated Script Component is enabled.
Scripting API
On Disable
Scripts bound to this event will trigger once the associated Script Component is disabled.
Scripting API
Update
Scripts bound to this event will trigger once on every frame update. This is handy for running code that changes things over time.
Multiple update events can cause slow performance.
Scripting API
Late Update
This event is triggered at the end of every frame, after normal UpdateEvents
such as Physics Events
or Animation Events
but before rendering occurs.
Scripting API
Face Events
These events are triggered based on user face actions (e.g. opening or closing the mouth, raising eyebrows).
Brows Frowned
Scripts bound to this event will trigger when a face's eyebrows are lowered.
Scripting API
Brows Raised
Scripts bound to this event will trigger when a face's eyebrows are raised.
Scripting API
Brows Returned To Normal
Scripts bound to this event will trigger when a face's eyebrows are returned to a neutral pose.
Scripting API
Face Found
Scripts bound to this event will trigger when a face enters the video frame.
Scripting API
Face Lost
Scripts bound to this event will trigger when a face leaves the video frame.
Scripting API
Mouth Closed
Scripts bound to this event will trigger when a face's mouth closes.
Scripting API
Mouth Opened
Scripts bound to this event will trigger when a face's mouth opens.
Scripting API
Camera Events
These events are triggered when a change is made to the current device camera.
Switched To Front Camera
Scripts bound to this event will trigger once when the camera is switched to the front (selfie) camera.
Scripting API
Switched To Rear Camera
Scripts bound to this event will trigger once when the camera is switched to the rear (world) camera.
Scripting API
Touch Events
These events are triggered by user touch gestures. To use these events, you'll need a Scene Object with a Touch
Component. To learn more about using the Touch
Component, refer to the Touch Input guide.
Touch Started
Scripts bound to this event will trigger once when the user starts a Touch gesture.
Scripting API
Touch Moved
Scripts bound to this event will trigger once every frame while the user is moving their finger during a Touch gesture (i.e. dragging their finger).
Scripting API
Touch Ended
Scripts bound to this event will trigger once when the user ends a Touch gesture (i.e. lifts their finger).
Scripting API
SnapRecordStartEvent
Scripts Bound to this event will be triggered when the user starts long pressing the capture button to record a Snap.
Scripting API
SnapRecordStopEvent
Scripts Bound to this event will be triggered when the user stops long pressing the Snap button to end recording of a Snap.
Scripting API
SnapImageCaptureEvent
Scripts Bound to this event will be triggered when the user taps on the capture button to record an image.
Scripting API
Other Events
In addition to the selectable events described above, there are many other events that can be bound in script. To learn more about binding events in script, please visit the section below.
Lens Turned Off
Scripts bound to this event will trigger once when the Lens is exited (if the user switches to another Lens, or closes the Lens carousel).
Scripting API
Delayed Callback
Scripts bound to this event will trigger after a specified amount of time. This event can be used as a countdown timer.
Scripting API
Manipulate Start
Scripts bound to this event will trigger when the user starts a Manipulate gesture.
Scripting API
Manipulate End
Scripts bound to this event will trigger when the user ends a Manipulate gesture.
Scripting API
Binding Events In Script
You can bind a function to a Lens Event as follows:
- JavaScript
- TypeScript
function printTime(eventData) {
// Print the elapsed Lens time
print(getTime().toString());
}
// Bind the function printTime to the event UpdateEvent
var event = script.createEvent('UpdateEvent');
event.bind(printTime);
@component
export class NewScript extends BaseScriptComponent {
onAwake() {
let event = this.createEvent('UpdateEvent');
// Bind the function printTime to the event UpdateEvent
event.bind(this.printTime.bind(this));
}
printTime(eventData: UpdateEvent) {
// Print the elapsed Lens time
print(getTime().toString());
}
}
In this example, the function printTime
is bound to the UpdateEvent using a SceneEvent.
To learn more about what the Script Component can do with events, visit the Script Component API Documentation.