The Camera
The Camera
Custom Instructions

Custom Instructions

On this page

Showing instructions after a set time period
Using the Patch Editor or scripting

Have a question?

Go to Forum

On this page

Showing instructions after a set time period
Using the Patch Editor or scripting

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

While some features always show specific 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 how to do both.

All instructions are automatically translated into the right language.

Showing instructions after a set time period

To add an 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:

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.

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:

  1. In the Menu, 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.

To choose the instructions you want to add:

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


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:

Next add your instruction token to the patch:

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

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.

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

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

    // Store 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, 'shouldDisplay' will be false and vice versa
    const shouldDisplay = Reactive.not(FaceGestures.hasMouthOpen(face));

    // Use the 'shouldDisplay' bool signal to set when the instructions should be enabled
    // If the mouth openness boolean wasn't reversed, the instructions would display when the mouth is already open
    Instruction.bind(shouldDisplay, 'open_your_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?