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 five categories: Scene, Camera, Touch, Keyboard 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

OnAwakeEvent

---

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

OnStartEvent

---

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

OnDestroyEvent

---

On Enable

Scripts bound to this event will trigger once the associated Script Component is enabled.

Scripting API

OnEnableEvent

---

On Disable

Scripts bound to this event will trigger once the associated Script Component is disabled.

Scripting API

OnDisableEvent

---

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

UpdateEvent

---

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

LateUpdateEvent

---

Face Events

These events are triggered based on user face actions (for example, 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

BrowsLoweredEvent

---

Brows Raised

Scripts bound to this event will trigger when a face's eyebrows are raised.

Scripting API

BrowsRaisedEvent

---

Brows Returned To Normal

Scripts bound to this event will trigger when a face's eyebrows are returned to a neutral pose.

Scripting API

BrowsReturnedToNormalEvent

---

Face Found

Scripts bound to this event will trigger when a face enters the video frame.

Scripting API

FaceFoundevent

---

Face Lost

Scripts bound to this event will trigger when a face leaves the video frame.

Scripting API

FaceLostEvent

---

Mouth Closed

Scripts bound to this event will trigger when a face's mouth closes.

Scripting API

MouthClosedEvent

---

Mouth Opened

Scripts bound to this event will trigger when a face's mouth opens.

Scripting API

MouthOpenedEvent

---

---

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

CameraFrontEvent

---

Switched To Rear Camera

Scripts bound to this event will trigger once when the camera is switched to the rear (world) camera.

Scripting API

CameraBackEvent

---

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

TouchStartEvent

---

Touch Moved

Scripts bound to this event will trigger once every frame while the user is moving their finger during a Touch gesture (that is, dragging their finger).

Scripting API

TouchMoveEvent

---

Touch Ended

Scripts bound to this event will trigger once when the user ends a Touch gesture (that is, lifts their finger).

Scripting API

TouchEndEvent

---

SnapRecordStartEvent

Scripts Bound to this event will be triggered when the user starts long pressing the capture button to record a Snap.

Scripting API

SnapRecordStartEvent

---

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

SnapRecordStopEvent

---

SnapImageCaptureEvent

Scripts Bound to this event will be triggered when the user taps on the capture button to record an image.

Scripting API

SnapImageCaptureEvent

---

Keyboard Events

These events are triggered by keyboard input. Use KeyPressEvent and KeyReleaseEvent to react when keys are pressed or released. Event data includes the key (via the Keys enum) and modifiers such as Shift, Control, Alt, and Meta (via the KeyModifiers enum). To check whether a key is currently held down—for example, for movement or game controls—use KeyboardManager.isKeyPressed in your script.

---

Key Pressed

Scripts bound to this event will trigger when a key is pressed.

Scripting API

KeyPressEvent

---

Key Released

Scripts bound to this event will trigger when a key is released.

Scripting API

KeyReleaseEvent

---

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

TurnOffEvent

---

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

DelayedCallBackEvent

---

Manipulate Start

Scripts bound to this event will trigger when the user starts a Manipulate gesture.

Scripting API

ManipulateStartEvent

---

Manipulate End

Scripts bound to this event will trigger when the user ends a Manipulate gesture.

Scripting API

ManipulateEndEvent

---

Binding Events In Script

You can bind a function to a Lens Event as follows:

JavaScript

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);

TypeScript

@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.