Clear
Back

Adding Instructions

Instructions give hints to people using your effect in the camera. For example, to hold up a hand or tap the screen. It's a good idea to add instructions to interactive effects, to help people use them quickly and easily.

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 for all features in your project:

  1. Go to Project in the menu bar, and select Edit Properties.
  2. Select Capabilities, click + and select Instructions.
  3. Click Insert.
  4. 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 Edit Properties.
  2. Select Capabilities, click + and select Instructions.
  3. Click Insert.
  4. Check the box next to Custom Instructions.


Next, choose the instructions you want to add your your effect. To do this:

  1. Click the arrow next to Custom Instructions.
  2. Click + next to Select Instructions to use.


You'll see a menu, with a selection of different instructions. Select the instructions you need, and click Insert.

You'll see a Token for each instruction you add. In the example below, we've selected the Open your mouth instruction from the menu. The instruction token this created is listed as open_your_mouth.



Copy this instruction. What you need to do next will depend on whether you're using the Patch Editor or scripting.

If you're 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.

To create an Instruction patch and open the Patch Editor:

  1. Select Device in the Scene panel.
  2. In the Inspector, click the circle next to Custom Instruction.

The patch will appear in the Patch Editor, under the Viewport:



Next add your instruction token to the patch:

  1. Click the box next to the Token port.
  2. Paste the token into the box.


You can now build your graph. Take a look at the examples below to learn more about building a graph that triggers an instruction.

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

Showing instructions when an effect has been open a certain amount of time

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.

Join the Spark AR Creator's community

Find inspiration, see examples, get support, and share your work with a network of creators.

Join Community

Join the Spark AR Creator's community

Find inspiration, see examples, get support, and share your work with a network of creators.

Join Community

Frequently asked questions

Have a specific question? Maybe it's been answered.


Read FAQs
Was this document helpful?