Creating a Block

You can either create an empty Block, or combine objects you’ve already added to the Scene panel into a Block.

Creating an empty Block

To create an empty block:

1. Click + 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:

Creating a Block from objects in the Scene panel

When you create a Block using objects in the Scene panel, any related assets and patches will be added to the Block.

Before creating a Block this way, make sure any objects you want to add are:

• Children of the same parent object in the Scene panel.
• On the same layer - this includes any children of parent objects.
• Supported objects or capabilities

To create a Block from objects in the Scene panel:

1. In the Scene panel, select all the objects you want to add to the Block.
2. Right-click, and select Create Block:

When the Block has been created, it will be listed in the Assets panel. The scene objects added to the Block will be replaced with a Block in the Scene panel.

Editing Blocks

To add scene objects and other elements to a block:

1. Select the Block in the Assets panel.
2. Click Edit in the Inspector.

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

Here, 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 Meta Spark 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 main Block.
• The Block in the Scene panel is an instance of the main 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 main 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.

The following data types are supported:

• Animation
• Audio
• Boolean
• Color
• Number
• Pulse
• Text
• Texture
• Vector2
• Vector3
• Vector4

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. In the Inspector, click Block Properties:

To add:

• An input, click + next to Inputs.
• An output, click + next to Outputs.

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 or Create Output:

Reordering inputs and outputs

To reorder inputs and outputs, just click and drag them in the properties window. For example, you could place blockInput0 below blockInput1.

Accessing inputs and outputs with patches

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.

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:

Accessing inputs and outputs with scripts

The values of a Block's inputs and outputs can be accessed from a script located within the Block using the functionality exposed by the BlocksModule API:

A script within a Block can only access and modify its own inputs and outputs, those of other Blocks are not available.

The only supported way of communicating data between scripts in different Block contexts is by using a Block’s inputs and outputs. Other forms of state sharing between Blocks, such as by modifying the global JavaScript state, are not supported.

As such, access to the global and globalThis objects in scripts has been restricted to keep effects self-contained. Both identifiers are mapped to undefined and display an error message in the console if used.

Using inputs and outputs in your project

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.

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

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

Making your blocks downloadable

Any blocks that you add to your project will be included in its .arexport file. When your effect is used on a device, all the assets that make up your effect (including blocks) will be loaded as soon as the effect is opened.

However, if you are creating a long-form AR experience or an experience with many possible outcomes, you may find it beneficial to delay downloading certain blocks to the user’s device until they are required.

For example, imagine an AR game you are creating displays a 3D model of a bronze, silver or gold trophy to users depending on the outcome of their game. By using downloadable blocks, you could avoid downloading the trophy models until the game is nearly complete. Alternatively, you could download only the single trophy model that is being shown to the user, removing the need to download all three.

Downloadable blocks are an extension of the dynamic instantiation capability. To make a block downloadable, it must be instantiated via a call to the instantiate() method exposed by the BlocksModule API. It can then be included in your scene using the he addChild() method exposed by the SceneModule API. Once the block is no longer needed in the scene, it can be destroyed using the destroy() method exposed by the SceneModule and MaterialsModule APIs.

To make a block in your effect downloadable:

1. Select your block in the Assets panel.
2. Check the box next to Downloadable.

By default, a block that is set as downloadable will start loading as soon as it is instantiated. But, in some instances, you may want to load the contents of a block slightly before it will be used in the effect. Blocks can be downloaded before they are first instantiated using the download method found in the blocksModule class.

Note: Downloadable blocks are still counted in your effects total file size, and are not a method for creating effects that exceed the file size requirements. However, using dynamically instantiated, downloadable blocks does allow for optimization of load times and performance.

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 or add the Block to another project. They'll be able to import the .arblockpkg file to their projects.

Creating a Block within a Block

It is also possible to create Blocks within Blocks.

Let’s reuse the Block with the particle system that looks like snow:

To add another Block inside SnowBlock:

1. Double-click SnowBlock to open it in a new, first-level window.
2. In the Assets panel, create another Block.

The second-level Block will be listed as block0 in the Assets panel.

To edit the second-level Block:

1. Select block0 in the Assets panel, in the Inspector, click Edit.
2. Make any edits in the new second-level window that opens.
3. Go to File and click Save.
4. In the example below we added a different particle system to block0. It’s listed in the Scene panel as emitter0.

You need to instantiate the second-level Block so the contents also appears in the first-level Block. To do so:

1. Go back to the first-level window, right-click block0 in the Assets panel and select Instantiate.
2. Go to File and click Save.

The contents of both Blocks will now be visible in the first-level window.

The contents of both Blocks will also be visible in the main project. In our example, both particle systems are visible in the Viewport and Simulator:

Choosing between Blocks and Patch Assets

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

Patch Assets allow you to save and share groups of patches with other Meta Spark Studio creators. Patch Assets 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 where meters is the the unit of measurement.

The following features are not supported:

• Some global objects and assets, for example ambient lights and environment textures.
• Other elements that require special capabilities.