The Camera
The Camera
Automatic and Custom Instructions

Automatic and Custom 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.

Some features in Spark AR Studio have automatic instructions that will always show in effects that include that feature.

You can choose custom instructions to show in your effect through the Inspector, Patch Editor or scripting.

All instructions are automatically translated into the right language.

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 in the Inspector

You can use the Inspector to add an instruction that will appear for 5 seconds after the effect has been opened. You can choose what the instruction will say from a list of preset options.

To add a custom instruction through the Inspector:

  • Select the Device in the Scene panel.
  • Go to the Inspector.
  • Under Custom Instruction, click the dropdown next to On Opening.
  • Select an instruction from the list, or select See All Instructions to browse for more options.

This will open the Patch Editor and create a patch graph that includes the Runtime and Less Than patches, and a yellow patch representing the Custom Instruction property of the Device scene object.

If you want to make the instruction visible for more or less than 5 seconds, edit the bottom value in the Less Than patch.

To show the instruction based on another trigger, for example an interaction or the movement of the camera, you can experiment with connecting different patches to the patch representing the Custom Instruction property of the Device.

Using the Patch Editor or Scripting

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

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.

Was this article helpful?