Dec 22, 2023

Custom avatar animations in Spatial

The purpose of this blog is to be teach how to use the same animations for different avatars in Spatial


Spatial is a cutting-edge web3 metaverse that offers users with a versatile platform for creating, exploring and interacting within virtual worlds.

Spatial uses Unity Engine as its tech base, providing creators access to nearly limitless tools.



The purpose of this is to be able to use the same animations for different avatars, as demonstrated in the Shilly project. For instance, players can ride the skateboard and experience consistent animations throughout their playtime.

Skateboarding animation in Spatial


The challenge we faced revolved around the need to integrate custom animations into our project without requiring the upload of entire avatars with animations.

Our objective was to empower users to preferentially introduce custom animations, enhancing their experience while retaining their existing avatars.

To deal with this challenge, we embraced an approach that uses the emote component as a seamless means of integrating custom animations. This approach enabled us to bypass the need of uploading complete avatars with animations, presenting a more efficient and flexible solution. Leveraging the emote component allowed users to gather the advantages of custom animations while maintaining the integrity of their chosen avatars.

Spatial avatar animation
Spatial custom avatar component

To overcome this challenge, we crafted the concept of creating custom emotes as animations within the skateboard. We designed a "state machine" that seamlessly switches between three different states, each representing a different emote played in a loop. This innovation enabled all players to use their own avatars, while still enjoying the same animations as those who opted for the custom avatar.

To ensure uniform positioning of all animations, we implemented a mechanism that tied up the user to the skateboard in-game. The skateboard became the only moving component allowing players to use their unique avatars while enhancing the overall gaming experience.

Before starting

For this task, a basic understanding of Unity’s Visual Scripting is needed. You can refer to Gettin Started | Spatial Creator Toolkit for more information.

You’ll need one model of the vehicle that the user will control, along with all the associated animations. If you don’t have one, you can use the default model provided by Spatial, which is the base model we’ve use in this project.

We recommend using Mixamo because it has the same humanoid rig base that Spatial is using for their avatars. If you don’t know how to create animations, or if you’re already familiar with animation creation, please follow the Spatial Documentation on how to upload them. You can find the link in resources section.

Essential: install Unity

The first thing you’ll need is to have Unity installed. You will need version 2021.3.21 to be able to test in your sandbox space. The minimum version that we support is 2021.3.8.

Installing Unity

  • Click the “Unity Hub” button next to 2021.3.21 on this page.
  • Install the “WebGL Build Support” module to be able to test in your sandbox space via your web browser.

Starting a new project

The most straightforward way to begin with Spatial is by creating a new Unity project.

1. Download the starter template

  • Click here to download the starter template.
  • Unzip the archive and open the project using Unity Hub.
  • Upon opening the project, you might face is an update dialog. Click “Yes” to update the latest version of the Spatial Unity SDK.
  • Then open the “Environment.unity” scene.

2. Authenticate with Spatial

Now you’ll need to authenticate with Spatial. Under the main menu bar, select “Spatial SDK/Account”. Follow steps outlined in the window.

Spatial account authentication

3. Test in your sandbox space

Now, you are ready to test this package directly in Spatial. Click the “Test” button in the main Unity toolbar.

Spatial's Unity package testing

Once this process is completed, the environment will be loaded directly into your Spatial sandbox.

We recommend using private browsing for a faster load time. First, log in, then go to spatial.io/sandbox to load your space and test it. (Don’t close the browser if you want to keep testing; just reload the page after Unity opens again in another tab, or set your favorite private browser as the default browser.)

Introducing custom animations

In leveraging the Spatial SDK, our objective was to establish a connection between the avatar and the user. To achieve customized physics-based movement, we implemented the Spatial Sit Component in combination with the skate prefab. Furthermore, our aim was to grant each user control over their individual skateboard, ensuring a personalized experience.

To facilitate this, we integrated the Spatial Synced Object within the prefab. This strategic inclusion enabled us to employ a node in the script, ensuring the uniqueness of the prefab for each user.

Creating a controller script for the vehicle

In our effort to handle user inputs and camera control, we employed the "Spatial Input → Set Overriden Avatar Input Capture" node. We set it to true for specific actions: movement, jump, and sprint.

However, users can customize this configuration according to ther preferences, such as using an action button, commonly mapped to the 'E' key in Spatial.

In our case, we tailored the control scheme to be responsive to the 'WASD' keys and the 'Space' key for skateboard control.

We use On Interact → subnode.

On interact subnode event

Enter vehicle subnode

Exit vehicle subnode

To control the areas where players could ride the skateboard, we implemented a couple of Spatial triggers.

Exit vehicle subnode part 2

Exit vehicle subnode part 3

We employ this script to prompt the user exit the skateboard. The first sudnode includes the three booleans that we use to control the animation state machine.

Booleans to control animation state machine

After addressing input and limiting the user within the skateboard prefab, we proceeded to modify the default car script provided by Spatial. Our modifications mainly focused on enhancing the jumping mechanics and refining the animation state machine.

In a separate code segment, we developed a Skate Spawner Object to enable each user to gather their own skateboard while in the skate park. This was accomplished through the straightforward process of instantiating the skateboard prefab. However, we faced an issue where players could spawn an infinite number of skateboards.

To address this, we introduced specific variables and checks. Firstly, we ensured that a player couldn't spawn multiple skateboards simultaneously. Secondly, upon exiting the skateboard or leaving the skate park, the skateboard would self-destruct and reset itself, preventing unnecessary clutter and disruptions in the user experience.

Creating a spawner script for the skateboard

Skateboard spawner script

The script spawns a skateboard beneath the user and sets a user variable indicating that a skateboard has been spawned for them.

The self-destruct object graph is implemented in the update script of the skateboard prefab.

Skate node to destroy itself if not being controlled by user

All nodes used


The project creatively leveraged Spatial's features by repurposing functionalities originally intended for different purposes, such as custom avatar emotes, particularly within the realm of skateboarding.

By seamlessly integrating custom emote animations into skateboards and attaching users to them, it ensures a uniquely smooth and customized experience, enhancing immersion and broadening the range of possibilities within Spatial.

Polygonal Mind
Creative Development 3D Studio

Since 2015 creating cool experiences, games and avatars on digital platforms

How to import Decentraland SkyboxEditor into Unity
Doing a MANA transaction in a Decentraland scene
Canvas (2D UI) Manager in Decentraland