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.

Instructions are added via the Inspector, where you can select:

  • The instructions you want to use in your effect.
  • Timed or Conditional Instruction patches. When connected to additional patches, these patches tell Spark AR studio when and under what conditions to display the instructions.

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

Adding instructions to your project

When you add a custom instruction it's automatically available to select from the dropdown menu in the Timed or Conditional instruction patch.

To add a custom instruction:

  1. Select the Device in the Scene panel.
  2. In the Inspector, click + to the right of Instructions.
  3. Select one or more instructions from the list, for example Tap to Change.
The menu of instructions

Changing when and under what conditions to display the instructions

When you've selected an instruction, you’ll need to add a Timed or Conditional patch to use it in your project. To do so, click Create to the right of the option:

The Timed Instruction patch

The Timed Instruction patch displays instructions for a specific amount of time that you set in the patch.

In the example below:

  • The Pulse patch detects when the effect has been opened. Connected to the Timed Instruction patch, it causes the instructions Tap to change to display as soon as the effect is opened. This is because we selected Tap to change from the Option dropdown in the patch.
  • The Timed Instruction patch shows the instructions for 4 seconds before they disappear.
A patch graph containing two patches.

To make the instruction visible for more or less than 4 seconds, edit the Duration value in the Timed Instruction patch.

To add an instruction that appears 5 seconds after the effect has been opened, you’ll need to connect a Runtime patch and a Greater Than patch to your graph as in the example below:

To make the instruction appear after more or less than 5 seconds, edit the Second Input value in the Greater Than patch.

The Conditional Instruction patch

Conditional Instruction patches display instructions if a condition is true. In the example below the instructions Tap to change are shown provided that the number of seconds since the effect started running is Less Than 3.

To show the instruction based on another trigger, connect different patches to the Conditional or Timed Instruction patch.

For example, 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 Conditional Instruction through the Not patch means the Open your mouth instruction will show when the mouth is closed.

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

Using a 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.