Endurance Mode

This template allows you to run Endurance Mode in your lens.  Endurance Mode is a low power mode that extends the duration of your lens by turning the display off.  Endurance Mode also has a built-in Hint feature: tap or hold the touchpad to view a hint for what you are supposed to do next. 

NOTE: Endurance Mode runs on custom API for Spectacles 2021.  It will not run on your phone or in Lens Studio. 

Project Download

Our sample project is an extremely simple implementation of a timer and hint.  Please download the project here.

Use Cases

Endurance Mode is a new, experimental feature, and we are actively exploring new use cases.  Some ideas include:

• Scavenger Hunt: go into Endurance Mode while the player is searching for the next clue
• Cooking lens: go into Endurance Mode while the player is waiting for a timer to go off
• Monitor lens: go into Endurance Mode between player notifications
• Travel Guide: go into Endurance Mode while the player is traveling to the next location

Triggers

There are several ways you can trigger entering and exiting Endurance Mode.  We believe the following ideas will work.  However, many of them may defeat the purpose of going into a low power mode. 

Trigger	Does It Work in Endurance Mode?	Is it Low Power?
Device Tracking - World or Surface	Y	N
Location Trigger	Y	Y
Touch Event	Y	Y
Timer	Y	Y
Face Event	Y	N
Marker Tracking Event	Y	N
Object Tracking Event (e.g. hand tracking)	Y	N
Landmarker Event (e.g. Big Ben)	Y	N
Machine Learning Event (e.g. RGB cam, voice)	Case by case	Case by case

 

Notes on triggers:

• Touch Event
• During Endurance Mode, the tap/hold event is implemented on the system level to trigger turning the display on/off to show/hide a hint.  If you overload the tap/hold functionality, then both events will fire in parallel (see Endurance API -> Hint Functionality below).

Endurance API

Compatibility

Make sure you have updated to the latest version of the Snapchat App on your phone, the Spectacles firmware, and Lens Studio.

• Snapchat v11.51.x and above
• Spectacles v4.67.x and above
• Lens Studio v4.4.1 and above

Enable Experimental API in Lens Studio

The experimental features in this API require that you update to Lens Studio 4.4.1 or later.  In your Lens Studio project, you must enable experimental features:

1. Open Lens Studio -> Preferences and check “Allow Experimental API.”  Now the “Allow Experimental API” option will show in Project Info.  
2. Open File -> Project Info and check “Allow Experimental API.”

Endurance API Overview

In the project download above, the Endurance API is in the script, “Timer.”  

Display

Description

Used to turn on and off the display

Inherited Methods

Display.requestDisplayOff(function(success){}) : void

This will call the “function(success)” parameter immediately.  (“Success” will be true if the feature was enabled with no errors.  It will be false if the feature disabled or has an error.)  

Then it will show the “Entering Endurance Mode” notification over your lens for 3 seconds.  

Then it will turn the display off and call the “DisplayStatus ChangedEvent” (see below).

Tip: You can use the “success” boolean to check if your player has enabled Snapchat -> Spectacles Home -> Experimental Features -> Endurance mode (see “Previewing Your Lens” below). 

 

Display.requestDisplayOn(function(success){}) : void

This will call the “function(success)” parameter immediately.  (“Success” will be true if the feature was enabled with no errors.  It will be false if the feature disabled or has an error.)  

Then it will immediately turn the display on and call the "DisplayStatusChangedEvent".

Then it will immediately show the "Exiting Endurance Mode" notification over your lens for 3 seconds.

 

Sample Code

Display.requestDisplayOff(displayCallback);

function displayCallback(success){
   if(success == false){
       script.instructions.text = "failure";
   }
}

Display Status Changed Event

Description

The "DisplayStatusChangedEvent" will fire anytime the actual display turns off or on.  Meaning, when the display turns off/on upon entering/exiting Endurance Mode AND when the display turns on/off upon showing/hiding the hint.

In Endurance Mode, the Spectacles 2021 display is turned off to save power.

 

Inherited Methods

event.getDisplayStatus() : Boolean

Returns a boolean for whether the display was turned on (true) or off (false).  

Tip: Use the event.getDisplayStatus() boolean to turn the camera on and off to save more power. 

Tip: Store a callback to fire on the first frame that the display actually turns off once we are in Endurance Mode.  Use this callback to swap your lens content with your hint content.  

 

Hint Functionality

Description

Endurance Mode has a built-in “Hint” functionality.  After you call Display.requestDisplayOff(), you are in Endurance Mode.  While in Endurance Mode, if the player taps or holds the trackpad, the display will briefly turn on without showing the “Entering/Exiting Endurance Mode” notifications for the purpose of showing the player a hint.  

• Display is Off (player is in Endurance Mode
• Tap trackpad => display turns on for 3 seconds
• Hold trackpad for >3 seconds => display turns on for duration of hold

Note that if you register an active touch event to run while in Endurance Mode, this touch event will fire in parallel to Endurance Mode.  If you bind a touch event to exit Endurance Mode, both the hint and the exit will fire, but to the player, it will just look like you exited Endurance Mode with no hint. 

Handling Endurance API

Endurance API is handled by placing the code in a script, and attaching the script to a scene object in your scene.  

 

Create a new DisplayStatusChangedEvent as follows.  Bind the DisplayStatusChangedEvent to call a function (“onDisplayStatusChanged”) when the event fires.  

script.createEvent("DisplayStatusChangedEvent").bind(onDisplayStatusChanged)

Note: In the sample code (below), we place the DisplayStatusChangedEvent creation in a try catch statement so that it does not throw an error when run in Lens Studio.  

In your script, call the following when you want the display to turn on or off:

• Display.requestDisplayOn(function(success){}) 
• Display.requestDisplayOff(function(success){})

Sample Code

This code is taken from the Timer script in the downloadable sample project above.  Here I’ve highlighted the important parts for how to implement the Endurance API.  To fully study the commented code with the timer logic, download the project. 

 

var inEnduranceMode = false;

var firstFrameDisplayOffCallback = undefined;

/* --- ENDURANCE API --- */
function setupEndurance(){
   script.hint_BG_image.enabled = false;

   try{
       script.createEvent("DisplayStatusChangedEvent").bind(onDisplayStatusChanged);
       return true;
   }catch(error){
       return false;
   }
}

function turnDisplayOff(onFirstFrameDisplayOff){
   if(inEnduranceMode){
       return;
   }else{
       inEnduranceMode = true;
   }

   Display.requestDisplayOff(displayCallback);
   firstFrameDisplayOffCallback = onFirstFrameDisplayOff;
}

function turnDisplayOn(){
   if(!inEnduranceMode){
       return;
   }else{
       inEnduranceMode = false;
   }

   Display.requestDisplayOn(displayCallback);
   script.hint_BG_image.enabled = false;
}

function displayCallback(success){
   if(success == false){
       script.instructions.text = "failure";
   }
}

function onDisplayStatusChanged(event){
   var displayIsOn = event.getDisplayStatus();
   script.camera.enabled = displayIsOn;

   if(firstFrameDisplayOffCallback && !displayIsOn){
       firstFrameDisplayOffCallback();
       firstFrameDisplayOffCallback = undefined;
   }
}

function firstFrameDisplayOff(){
   script.hint_BG_image.enabled = true;
}

/* --- TIMER LOGIC --- */
function startTimer() {
   turnDisplayOff(firstFrameDisplayOff);
}

function onTimerComplete() {
   turnDisplayOn();
}

function onTap(event) {
   if (isTimerRunning == false) {
       startTimer();
   } else if (getTimer() <= 0) {
       resetTimer();
   }
}

function onUpdate(event) {
   if (timerTargetTime > 0) {
      var remainingTime = getTimer();
      script.timer.text = timeToString(remainingTime);
      if (remainingTime <= 0) {
         timerTargetTime = 0;
         onTimerComplete();
      }
   }
}
/* --- INIT --- */
var enduranceReady = setupEndurance();

if (enduranceReady) {
   script.createEvent("TapEvent").bind(onTap);
   script.createEvent("UpdateEvent").bind(onUpdate);
}

Previewing Your Lens

You’re now ready to preview your lens on Spectacles 2021.  To pair your lens with your Spectacles 2021, follow the Preview Your Lens On Device section on the Creating Lenses guide.

 

To enable Endurance Mode on your Spectacles 2021:

• Update Snapchat on your phone
• Go to Spectacles Home in Snapchat
• Tap “Experimental Features”  
• Enable “Endurance mode”

Tip: For an implementation of how to notify your player in lens to enable this experimental feature, please visit the onLensStarted() function of the LensController script in the Doggie Detective project.