The Camera
The Camera
Custom Instructions

Custom Instructions

Custom instructions being selected from a menu.

Instructions give hints to people using your effect. They'll appear at the bottom of the device screen.

While some features always show specific automatic instructions, you can also add different custom instructions to help people use your effect. There's a wide range to choose from.

You can add custom instructions by:

  • Using the Inspector — to show instructions when an effect has been open for a set time.
  • Using the Patch Editor or scripting — for more complex instructions involving logic and other interactions.

This article covers both methods.

All instructions are automatically translated into the right language on the user's device screen.

Showing instructions after a set time period

To add a custom instruction that appears 5 seconds after the effect has been opened:

  1. Select the Device in the Scene panel.
  2. In the Inspector, go to Custom Instruction.
  3. Next to On Opening, click the dropdown.
  4. Select an instruction from the list, or select See All Instructions to browse more options:
Custom instructions being selected from a menu.

Changing when the instructions appear

When you've selected a custom instruction, in the Patch Editor you'll see a patch graph that includes:

  • The Runtime and Less Than patches.
  • A yellow patch representing the Custom Instruction property of the Device scene object.
A patch graph containing three patches.

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, connect different patches to the patch representing the Custom Instruction property of the Device.

Using the Patch Editor or scripting

Start by adding custom instructions to your project's properties. If your project has a face, hand, body or target tracker, the instructions capability is added by default, which means you can skip steps 1 to 3:

  1. Click the gear icon in the toolbar.
  2. Select Capabilities, click + and select Instructions.
  3. Click Insert.
  4. Click the arrow to the left of Instructions.
  5. Select the box to the right of Custom Instructions.

The Custom Instructions capability being turned on in the project's properties.

To choose the instructions you want to add:

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

Custom instructions being selected from a menu.

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

You'll then see a Token for the instruction you've added. In the example below, we've selected the Open your mouth instruction from the menu. The instruction token is open_your_mouth.


A list of selected instructions and their tokens.

Then:

  • Copy the instruction token.

What to do next depends on whether you're using the Patch Editor or scripting.

Using the Patch Editor

Start by creating an Instruction patch:

  1. Select the 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:

A single yellow patch is seen in the Patch Editor.

Next add your instruction token to the patch:

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

 A single yellow patch is seen in the Patch Editor.

Connect other patches to the Instruction patch to tell Spark AR Studio when to show the instruction.

In the graph below, the face tracker and Mouth Open patches detect when the camera is pointed at an open mouth. Connecting these patches to the Instruction patch through the Not patch means the Open your mouth instruction will show when the mouth is not open.

A patch graph containing six patches.

You can also use the Javascript bridging patch to connect the Instruction patch to a script.

Using script

To start, include the Instruction module in your script:

const Instruction = require('Instruction'); 
        

Then use the bind method to show the instruction. The enabled parameter sets whether the instructions should be displayed, while the token parameter is the token of the instructions to show or hide.

Instruction.bind(true, 'open_mouth'); 
        

For example, we could show the instructions when an open mouth is not detected and hide them when a mouth is opened with the following code:

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

(async function() { // Enables async/await in JS [part 1]

    // Create a reference to a detected face
    const face = FaceTracking.face(0);

    // Create a signal to track when the mouth is open and return the opposite
    // boolean value
    // If the mouth is open, 'displayInstructions' will be false and vice versa 
    const displayInstructions = Reactive.not(FaceGestures.hasMouthOpen(face));

    // Use the above bool signal to set the instructions' visibility
    // If the mouth open boolean wasn't reversed, the instructions would
    // display even if the mouth is already open
    Instruction.bind(displayInstructions, 'open_mouth');

})(); // Enables async/await in JS [part 2]
        

The example above makes use of the Instruction, FaceTracking, FaceGestures and Reactive modules.

Was this article helpful?