Adding Instructions

Instructions give hints to people using your effect in the camera. For example, to hold up a hand or tap the screen.

Spark AR Studio comes with automatic instructions. You can also add your own custom instructions using the Patch Editor and scripting.

Both automatic and custom instructions will be automatically translated into the right language.

Learn about:

Automatic Instructions

Automatic instructions are shown if people aren't using your effect in the right way. For example, if you've added a face tracker to an effect but a face can't be found, a message saying 'find a face' will appear.

Spark AR Studio has automatic instructions for:

  1. The face tracker.
  2. The hand tracker.

They'll show until a hand or face is detected, and appear again if the hand or face disappears.

Automatic instructions will only show if they're enabled for the camera. For example, if you don't want the find a face instruction to show in the back camera, disable instructions for the face tracker in the back camera.

To turn automatic instructions off:

  1. Go to Project, and select Properties.
  2. Select Capabilities, click + and select Instructions.
  3. Uncheck the box next to Automatic Instructions.

Adding Custom Instructions

First add custom instructions to your project's properties:

  1. Go to Project, and select Properties.
  2. Select Capabilities, click + and select Instructions.

Next, add your custom instructions:

  1. Select Custom Instructions
  2. Click +.
  3. Add the instructions you need.

You'll see a token for each instruction you add. Copy your tokens.

Using the Patch Editor

Use the Instructions patch to add custom instructions to your effect. You can either connect this patch to a graph, or use the Javascript bridging patch to connect it to a script.

Then, in the Scene tab:

  1. Select Device.
  2. Click Actions in the Inspector panel.
  3. Select Instructions - the patch will appear in the Patch Editor, under the Viewport.
  4. Paste your token into the Instruction patch.

You can now build your graph.

Using script

First, include the Instruction module in your script:

 const Instruction = require('Instruction'); 

Then, use the bind method to show the instruction, using your token:

Instruction.bind(true, 'open_mouth'); 

Examples

Showing simple instructions

This example will make an instruction appear for 5 seconds, to tell people the effect includes sound.

Patch Editor


We've created the instruction token and then pasted it into the Instruction patch.

We then:

  1. Created a Runtime patch, and connected the Time port to the input port of the Less than patch.
  2. Set the count to 5 in the Less than patch - to control how long the instruction should appear for.
  3. Connected the output port of the Less than patch to Enabled in the Instruction patch - to enable the instructions and complete the graph.


Script

// Load in the required modules
const Instruction = require('Instruction');
const Time = require('Time');

// Define a boolean that will be true until 5 seconds has passed
var show = Time.ms.lt(5000);

// Use the boolean to show the instruction
Instruction.bind(show, 'effect_include_sound');

Time.ms returns the number of milliseconds elapsed since the effect started. We then use the lt method of the ScalarSignal class to return false once 5000 milliseconds (5 seconds) has passed.

When an effect needs 2 faces

This example will let people know the effect needs 2 faces to work properly.

Patch Editor


We've created the instruction token and then pasted it into the Instruction patch.

We then:

  1. Created a Face Finder Patch, and connected the Count port to the input port of the Less than patch.
  2. Set the count to 2 in the Less than patch - the number of faces needed for the effect to work.
  3. Connected the output port of the Less than patch to Enabled in the Instruction patch - to enable the instructions and complete the graph.


Script


Make sure Max Faces is set to 2 or more in the Capabilities tab of the Project Properties window to allow the detection of more than one face.

// Load in the required modules
const Instruction = require('Instruction');
const FaceTracking = require('FaceTracking');

// Define a boolean that will be true until 2 faces are detected
var show = FaceTracking.count.lt(2);

// Use the boolean to show the instruction
Instruction.bind(show, 'try_with_friends');

FaceTracking.count returns the number of faces tracked in the scene. We then use the lt method of the ScalarSignal class to return false once more than one face is detected.