Oct 20, 2023

Your first steps in Spatial

Spatial has its own logic system components. They are very simple and allow us to make quests without depending on codeworks, at least for simple tasks

The mission

The mission is to learn this system and create experiences without having to open a code graph, or, in fact, opening it the lesser possible.

Tweak experiences with interactable object, quests, and simple functionalities.


  • Unity Spatial SDK project template (2021.3.8)
  • WebGL export Support installed on version.


File deleting before Spatial SDK template creation
This file access to a paid feature of github, and it has something similar to a “trial” time. Once the trial time is finishes, it will kick every user in the repository from it and won´t let anyone to make pushes or pulls, blocking it completely until this file is deleted.


Spatial SDK has its own “logic” system, which is based on Unity components. They also support Unity Visual Scripting Graph, but we will only cover components here as this is thought for artists.

For testing we will create a super basic scene. just add some default cubes and a plane.

Unity basic scene for Spatial

Note: for collider in Spatial we will use the collider components from Unity (box collider, sphere collider or mesh collider depending on how much complexity you want on them).

Every component you add from spatial should be put on Unity empty objects and make it child of whatever object you want it to affect to. Putting them directly into the objects bugs and can lead to a not working feature.

Setting the scene to make a local export

First of all, you have to create an entrance point. For that we will create an Unity "empty object" and add an “spatial entrance point” component to it.

Spatial scene entrance point design

Note: the white gizmo allow you to modify the angle of effect. In this component, it allows you to amplify or reduce the area where the player will spawn randomly. I personally recommend to put it to 1.

Spatial SDK tab

Next, we have to access to the SDK window, which will allow us to create the scene template for exports.

For making local export we will need to log in our Spatial account, so, first of all, create one.

Spatial SDK account log in tab

Once we have an account we will go to the “account” tab on the SDK window and press on “get login token”. It will open us a tab on our browser.

Spatial scene uploader

Spatial SDK tab

Next we click on “copy to clipboard” and return to Unity.

On the Spatial SDK window we will click now on “paste login token”. Now we should be logged in and we should see something like this.

Thumbnail camera

Add a Spatial "thumbnail camera" component to the main camera on your scene. It doesn´t work for making thumbnails yet, but it´s needed for making the export.

Also remove the audio listener component from it, as it is not suported by Spatial yet.

Creating scene template and export

Spatial SDK configuration tab

Go to the “config” tab on SDK window and create an "scene template".

As you can see, you have a “publish” and “delete” buttons. In this case, we are not using them, but if we pushed them by mistake, there would be no problem as we could delete it on the Spatial web without making it public to everyone.

Assign your scene and tumbnails and put a name to the package and scene.

Thumbnails must be 1024x512 px or the exporter won´t let you run the project.

Spatial SDK issues tab

Once this is finished we are going to the “issues” tab on SDK window and we will see that is very similar to Decentraland SDK. Press “refresh" to see if we have warnings. Unless lights are completely baked, there should not be lightmaps or lightprobes.

Note: light probes and lightmaps are supported, but you are free to use realtime lighting and will work fine on the web.

Local export

Spatial local scene exporter

Once you have done everything above, push the “test active scene” button and it will process the scene for you to play it localy in Spatial. If there's any but or error, it will show it to you on the SDK “issues” window and will explain cleanly what´s going on and what you missed.

Congrats! You have exported your space locally!

Spatial local scene

Basic logic components

Spatial interactable

This component allow us to create interactable objects for different purposes: making things appear and dissapear, text arrays, look at, animation machines, state machines, etc…

Spatial interactable component

You can add events related to assets, animations, or prefabs.

There are 3 kind of events handlers on this component:

  • On interact: everytime you press “F” on the radius of detection of this component, something happens.
  • On exit: If this interactable object is a trigger, you can add an “event” every time you stop hitting the trigger.
  • On enter: If this interactable object is a trigger, you can add an “event” every time you hit the trigger.

Unity synced Spatial scene

The synced checkbox is for making this logic “local” or “global”; this checks if everyone will see the logic working the same way for everyone or if it will be independenly displayed for each player.

Example: An event should be global and a land quest should be local.

You can also assign this logic as we said, to objects, animations, prefabs,… and make then run only on editor, or on runtime, or both.

Unity component functions

There are a lot of different functions inside each component, so it is up to you to explore, as they are a lot.

Spatial event trigger

This is exactly the same component as the interactable, but only for trigger logic. In this case we will have to add also a collider to the object and check the trigger checkbox to make it work.

Spatial event trigger component

This component also has a lot of different functions to explore.

Spatial avatar teleporter

This component allows us to move the player between positions in the scene. This is probably the simplest component on Spatial. It also needs a trigger to work.

Spatial player movement component

On the component, you assign another empty object that will be the teleport target.

Empty frame

This component allow us to put images, videos or models on the Spatial scene.

Spatial images upload component

You can edit its size by moving the gizmos on the viewport or changing the “size” on the component.

You should see something like this on web:

Spatial images frames

Avatar override

Using custom avatars

Avatar override in Spatial SDK

Using custom avatars is available in the Spatial SDK tookit, however the steps to follow must be executed correctly and in order, otherwise the process will not work.

Here the video tutorial

Importing .fbx

Rigged avatar importer
  • Import a rigged, humanoid 3D model (preferably .fbx format) into Unity. This model does not need to have animations, but if there are some, you may add them through the Avatar Animation package and component. Ensure that the "animation type" under the "rig" tab is set to "humanoid".

  • Create a prefab from this model. You can do so easily by right clicking the asset and selecting Create > Prefab Variant.

Avatar prefab creation
  • Add the Spatial avatar component to this newly created prefab.

  • Create a new avatar package under project configuration and drag the prefab into the "prefab" (3)  field. You will also need to supply a thumbnail of size 256x256 (2) in an uncompressed format. The background should be transparent.

Avatar package creation

Open Spatial folder to find all the created spaces, templates and avatars

Avatar example configuration
Avatar example configuration

Publishing the avatar

Now that we have created the avatar space and configuration it is time to publish it into Spatial.

Avatar publication
SKU copy

Spatial interactable tool creation

Once the avatar is published, copy the SKU and create an Spatial interactable tool, which will allow along the script machine to use the avatar as a character.

Add the "script machine" component and create a new script, after that edit the graph and add the visual scripting shown below.

Script machine component addition
Script machine

Now test the land and approach the model you have uploaded, you should be able to interact with it and change the sking you are wearing!

Demo of the override character

Quests and rewards

Quest progression in Spatial SDK

A quest is a journey taken in order to fulfill a certain goal or objective, involving a series of tasks along the way.

Same functionalities as the interact component. But you can define objectives, tasks and rewards.

Quest properties

  • Check: the task can be completed by doing one action.
  • Progress bar: the task can be completed by doing a number of actions specified in progress steps.

Progress steps is the number of times the task has to be and it only can be used if task type is progress bar.

On completed event means Spatial event will be executed when the certain task is completed.

Quest tool with multiple tasks
Naming guide of the on started event quests

Quest statuses

Starting a quest

There are two ways to start a quest:

  • Set the quest to start automatically (only one quest can be started automatically on a space).
  • Call the quest event “start quest”. This is accessed through any Spatial event available via Trigger Event, Point Of Interest, and Interactable.

Starting a quest

How to progress a quest

You can trigger a quest task to complete or progress through quest events. These can be triggered through any Spatial event available.

Quest progression
Quest progression
Javier Irala
Environment Artist
How to import Decentraland SkyboxEditor into Unity
Doing a MANA transaction in a Decentraland scene
Canvas (2D UI) Manager in Decentraland