Patch Editor
Patch Editor Overview

Patch Editor Overview

Patches in Spark AR Studio let you add interaction, animation and logic to effects. You can also use them to create materials.

Patches act as visual building blocks, with each patch performing a different function. Connected together in what's known as a graph, patches pass and receive information to and from one another to make things happen in the effect.

Many capabilities available in scripting can be added to your effect as patches, so you can add complexity without knowing how to code.

Once you've learned the basics, it's worth taking a look at the different ways we've used patches to build full effects, in these tutorials.

Opening the Patch Editor

To open the Patch Editor:

  1. Select View in the menu bar.
  2. Select Show/Hide Patch Editor.

The Patch Editor will open at the bottom of the Spark AR Studio interface.

Patch types

Most scene objects and assets can be represented as patches. You can also create patches to represent object's and asset's properties in the Inspector.

Right-clicking in the Patch Editor will open a menu featuring a range of 'intermediary' patches.

These patches can be used to add all kinds of additional complexity to your project, including logic, animation and interactivity.

Scene objects

Patches representing scene objects produce signals that can be passed to other patches. Because of this, they're known as 'producer' patches.

Drag objects from the Scene panel into the Patch Editor to create a producer patch.

Try this out by adding a face tracker to your scene and dragging it into the Patch Editor.

For example, the face tracker patch produces a signal for the position and movement of the face.

Inspector properties (consumer patches)

The final patch in a graph will represent the property of the object in your scene that you want the graph to affect.

These patches are known as 'consumer' patches, because they consume signals created by other patches in the graph, changing the property as a result.

To create this type of patch, select the object in the Scene panel and click the arrow next to the property in the Inspector.

A yellow patch will be created:

Asset patches

To create patches representing assets in the Asset panel, for example textures and audio files, drag and drop the asset into the Patch Editor.

You can add multiple instances of asset patches to your projects.

Intermediary patches

Use the menu in the Patch Editor to create intermediary patches. To add a patch from this menu, right-click in the Patch Editor, find the patch you need and select Insert. If possible the patch will appear in a position that doesn’t overlap any other patches.

NameDescription

Animation

Add animations to effects, including adding procedural animation to 3D objects with bones and joints.

Audio

Add effects like distortion and pitch changing to audio sources and control how audio plays in your effects.

Face Landmarks

Capture the precise position of parts of the face, such as eyes and nose.

Interaction

Detect gestures from the person using your effect and make something happen as a result.

Logic

Define the conditions needed for something to happen in an effect, such as triggering an animation to play when the user interacts with the device in a certain way.

Math

Perform math operations on inputted patches.

Shaders - visual shaders

Change the appearance of a material.

Shaders - signed distance fields (SDFs)

Create procedural textures like shapes and patterns.

Time

Track the number of seconds an effect is running.

User Interface

Add UI functions to your effect.

Utility

Broad range of patches, from face trackers to random number generators.

Understanding and editing patches

Let's take a closer look at the labels and values you can see and edit. This is the Loop Animation patch:

Name

The name is at the top of the patch. In the example above, the patch is called Loop Animation.

You can rename some patches by double-clicking the name.

Input and output ports

The small circles with arrows in along each side of the patch are known as 'ports'. Ports along the right side of a patch are known as 'output ports'. The ports on the left are 'input ports'.

You'll link one patch to another by making a connection from an output port, to an input port.

Ports are labelled to indicate what they do. Loop Animation has 3 input ports:

  • Enable - this port enables the animation to play - turning it on or off.
  • Duration - you'd adjust the value of this port to edit the duration of an animation, in seconds.
  • Reset - you'd use this port to reset an animation.

It has 1 output port, Progress. This port creates a signal representing the progress of the animation.

Values

When a port has a box next to it, it means you can edit the value associated with the port.

In the Loop Animation patch, 2 values can be edited. Editing the Duration value will change how long the animation plays for.

Checking the box next to Mirrored will mean the animation plays in reverse, after it completes.

Data type

You'll choose different data types for some of the patches. For example, if you're manipulating the shape of a 2D object, you'd set the data type of certain patches to Vector 2. If you're applying a color to a material, you'd change the data type of certain patches to Color.

To change the data type of a patch, select the patch. A box containing the current data type will appear at the bottom of the patch.

The data type of the Transition patch in the example is set to Vector3. That means the patch can be used, for example, to transition an object from one position to another in 3D space. To change this, you'd click the arrow next to Vector 3, and select an option from the list:

If you changed the data type to say, Color, it could be used to transition the color of an element in your scene.

Connecting patches and building graphs

Connect patches using their ports — the small dots on each patch.

Patches can only be connected from left to right. This means you'd always connect a port on right side of a patch - known as an output port - to a port on the left side of another patch - known as an input port.

Connecting patches

To connect patches together:

  1. Click and hold the first port.
  2. Drag the connector across to the second port.

You should see a gray line appear, which will turn blue once it has found a connection. Only the compatible ports will be visible, ports with incompatible data points will be grayed out.

If you let go, you should see a connection made between your patches.



Making multiple connections

An output can have more than one outgoing connection, but an input can only have one incoming connection. This means that the result of an output port can be applied to more than one patch.

Disconnecting patches

To disconnect patches, either:

  • Select one of the ports and press delete on your keypad.
  • Select the output port, drag the connection into an empty space and let go.

Example

Here's an example of a simple graph.

The graph uses:

  • A series of producer patches representing the face tracker.
  • An intermediary patch, Smile. This patch can detect when someone using the effect is smiling.
  • 3 consumer patches, each representing the Visible property 3 objects in our scene.

As a result of connecting these patches, when a face with an open mouth is detected, 3 objects will appear in the effect.

Let's take a closer look at how the patches in this graph makes this happen.

The Face output port in the the face tracker patch captures data on the face detected by the face tracker. It's connected to the the Smile patch, which narrows down this information to focus on gesture the face is making.

The Smile patch outputs a signal when a smile is detected. When we connect the output of the Smile patch to the input of the Visible patches, it means the objects will be visible when a smile is detected.

Organizing and managing your patch graph

Spark AR Studio offers different features to help you manage and organize your graph more easily.

Grouping patches

You can group patches to help organize your graph. You can also save patch groups to use again in other projects, and share with other creators. Find out more.

Copying and pasting patches

You can cut, duplicate, copy and paste patches across different projects and across windows within the same project. This makes it easier to reuse patch graphs from Spark AR templates and example projects from tutorials instead of rebuilding them yourself.

To perform these actions, either select the option from the Edit menu or use the standard shortcuts. For example, to copy and paste a patch graph:

  1. Open the Spark AR template or project.
  2. Select the patch graph.
  3. Select Copy from the Edit menu or ⌘C.
  4. Open a new project or window.
  5. Select Paste from the Edit window or ⌘V.

You can only copy and paste the intermediary patches and connections from your graph. Producer and consumer patches will not be pasted to the new project or window.

Wireless Sender and Receiver patches

Larger and more complicated patch graphs can quickly become untidy as cables begin to overlap. To declutter your graph, use wireless sender and receiver patches to transmit data between any patches across your graph without using cables. These type of patches are most valuable when working with large and complicated graphs containing different patch groups.

The Sender patch

The Sender patch sends data to one or many receiver patches set to receive this data. Double-click the sender patch title to rename it.

The Receiver patch

The receiver patch outputs the value received from the sender patch.

Click the dropdown menu to select the sender patch you want to receive data from. Once the sender patch is set, click Locate Sender in the dropdown to find the patch wherever it is on the graph.

Example

The example below shows a sender patch wirelessly transmitting the red color value to multiple receiver patches that are set to receive data from this sender.

The receiver patches are then outputting the red color value to patches representing the color properties of different lights in the scene.

Zoom levels

When you zoom out of your graph beyond a certain threshold the labels and features of your patches will no longer be visible. This improves Spark AR studio performance.

If you want to see a version of your graph where the details of all patches are visible regardless of zoom level:

  1. Click File in the navigation bar and then select Preferences.
  2. Select Show/Hide Patch Editor.
  3. Next to Patch Editor, deselect Hide details on max zoom levels.

Was this article helpful?