Introduction to Blocks

In Spark AR Studio, blocks allow you to save and export pieces of a project. You can then reuse them over and over again, and share them with other creators.

This can reduce repetition when working on AR effects. Simply create a block that includes the components you want to reuse, and add the block whenever you need it.

You can create a block for most things you need to repeat or reuse in Spark AR Studio. Combinations of scene objects, assets, patches, materials and texture settings are all supported.

Learn about:

• Creating blocks.
• Building and editing blocks.
• Adding a block to your project.
• Creating inputs and outputs - to pass information to and from blocks in your projects.
• Using inputs and ouputs.
• Adding descriptions to blocks.
• Exporting blocks, to use in other projects and share with other creators.
• The difference between patch groups and blocks.
• Restrictions on blocks - it's a good idea to check these before you get started.

We’ve also put together a step-by-step tutorial. You'll create a block that can be used to add a snowy effect to your scene.

Creating a block

To create a block:

1. Click Add Asset in the Assets panel.
2. Select Block.

The block will be listed in the Assets panel. When it's selected you can rename it if you want to:

Building and editing blocks

To build and edit a block:

1. Select the block in the Assets panel.
2. Right-click and select Edit, or click Edit in the Inspector.

This will open the block in a new window, so you can make changes to it:

In the new window, the block will be listed in the Scene panel as Block Root. Simply add the objects and assets you want to include in the block as a child of Block Root.

When you save a block, it will automatically update in all projects that use the block. You'll see this message in Spark AR Studio to remind you:

Adding a block to your project

The quickest way to add a block to your scene is to simply click and drag it from the Assets panel to the Scene panel. Alternatively:

1. Select the block in the Assets panel.
2. Right-click, and select Instantiate.

The block will be listed in both the Scene panel and the Assets panel:

• The version of the block in the Assets panel is the master block.
• The block in the Scene panel is an instance of the master block.

Below, we've added a block to the Scene panel. We've used it to create an effect with a particle system that looks like snow:

In the Scene panel, Snow is the instance of the Block. You'd use the options under Inputs in the Inspector to customize how the block behaves in the effect. In the Assets panel, Snow is the master block.

You can instantiate the same block more than once.

Learn how we made this block.

Creating inputs and outputs

Inputs and outputs pass information to and from blocks, into your projects. You'll use them to set default values for the block's properties, allowing you to customize the block.

Supported data types for inputs and outputs are:

• Boolean.
• Scalar.
• Vector2, Vector3 and Vector4.
• Color.
• String.

To create an input or output, make sure the block is open, by right-clicking on the box in the Assets panel and selecting Edit. Then:

1. Select the block in the Scene panel - it'll be listed as Block Root.
2. Click Block Properties in the Inspector:

Then, either:

1. Click + next to Inputs - to add an input.
2. Click + next to Outputs - to add an output.

You'll see a list of options that you can edit to configure the input or output, depending on the data type you select:

• Type - this is where you'll set the data type.
• Input Limit - use this option to add minimum and maximum values for numerical and vector types. For vector types, it’ll be applied to each individual axis.
• Input Style - use this option to control how an input can changed in the Inspector. Choose between text or a slider.
• Default Value - set a default value.

Alternatively, you can create input and output ports using patches in the Patch Editor. To do this:

1. Click any input or output port in any patch you've added as part of your block.
2. Click Create Input to Block or Create Output for Block:

Using inputs in a block

Use inputs to customize your patch graph inside a block:

1. Open the block.
2. Select Block Root in the Scene panel.
3. Go to Interactions in the Inspector.
4. Click Create next to Producer Patch:

Alternatively, drag the block scene object from the Scene panel into the Patch Editor.

Using outputs in a block

Use outputs to pass information from the block, into your project. For example to a patch outside the block.

In the opened block:

1. Select Block Root in the Scene panel.
2. Click the arrow next to Output in the Inspector.

A consumer patch will be created:

Using inputs and outputs in your project

Inputs

All the inputs you've added to a Block will be listed under Inputs in the Inspector, when you select the block in the Scene panel:

You can change the values of the inputs in the Inspector, to change how the block behaves in your effect. Or, click the arrow next to the input to create a consumer patch that can be connected to the rest of your graph:

You can also drag the block from the Scene panel into the Patch Editor.

Outputs

Once you've defined the outputs of the block, drag it from the Scene panel into the Patch Editor to create a patch:

Scripting

You can set the values of inputs and get the values of outputs in a script by using the methods of the BlockSceneRoot class after accessing your block in the scene by name.

// Load in the scene module
const Scene = require('Scene');

// Locate a block in the scene
const myBlock = Scene.root.find('myBlock');

// Set a scalar input (signals also accepted)
myBlock.setScalarInput('blockInput', 5);

// Get a scalar output
const blockOutput = myBlock.getScalarOutput('blockOutput');

Adding a description

It's a good idea to add descriptions to your blocks. This will help any creators you share the block with understand what it does, and help you keep track too.

To add a description:

1. Select the Block Root in the Scene panel of the block.
2. Click Block Properties in the Inspector.
3. Enter your description of the Block in the General tab.

When you select the block in the Assets panel, you'll see the description in the Inspector:

Sharing blocks and using blocks in other projects

You can package blocks to share them with other creators, or add them to other projects.

To package a block:

1. Open your block.
2. Click File and select Package...
3. Choose a name and destination.
4. Click Save.

An .arblockpkg file will be created - you can share this with other creators. They'll be able to import the .arblockpkg file to their projects.

Choosing between blocks or Patch Groups

Blocks allow you to structure your project, to use parts of it again and again. They can contain scene objects, assets and patches.

Patch Groups allow you to save and share groups of patches with other Spark AR Studio creators. Saved patch groups can’t contain producer patches, consumer patches or any assets.

In general:

• If the element of your effect that you want to save and export only uses patches, use Patch Groups.
• If you're using scene objects and assets as well as patches, use blocks.

Restrictions

Blocks can only be used in projects with meters as the unit of measurement.

The following features are not supported:

• Some global objects and assets, for example ambient lights and environment textures.
• Trackers, like the face tracker and plane tracker.
• Scripts.
• Other elements that require special capabilities.

You can’t create a block within another block.