Spatial Creator Toolkit home page

Controlling the Avatar

Core to Spatial is the player avatar. Each player brings their own customized avatar into every space they join. By default every space uses the same avatar controller physics, input, and camera control.

On Spatial each player is their avatar and your space's should be constructed around this. Overwriting or hiding the players avatar should only be done if absolutely necessary.

If your experience requires overwriting the players avatar, such as transforming them into an animal, its best-practice to try contextualizing this inside of your space.

The Avatar

By default players can move around in space's using WASD and move the camera with the mouse. If this is all your space needs then you don't need to configure anything or write any code.

Change Avatar Movement Config

The easiest way to change how avatars move and jump inside of a space is through the Environment Settings Override component.

Moving Avatar With Code

In C# the local IAvatar can be accessed using the Actor Service. Once you have a reference to an avatar you can directly set its position.

// Get a reference to the local avatar
IAvatar localAvatar = SpatialBridge.actorService.localActor.avatar;
localAvatar.position = new Vector3(1, 0, 0);
// Get a reference to the local avatar
IAvatar localAvatar = SpatialBridge.actorService.localActor.avatar;
localAvatar.position = new Vector3(1, 0, 0);

Additionally you can command the avatar to move as though it is receiving inputs through the Move and Jump methods.

IAvatar localAvatar = SpatialBridge.actorService.localActor.avatar;

// Equivalent to the player holding [W] for 1 frame
localAvatar.Move(Vector.up);
// Make the avatar jump
localAvatar.Jump();
IAvatar localAvatar = SpatialBridge.actorService.localActor.avatar;

// Equivalent to the player holding [W] for 1 frame
localAvatar.Move(Vector.up);
// Make the avatar jump
localAvatar.Jump();

Controlling Player Avatar Input

Customizing how inputs are handled in Spatial can be done with the Input Service. To override just the players avatar inputs you can implement an IAvatarInputActionsListener and start an Avatar Input Capture like shown below.

public class AvatarInputListenerExample : MonoBehaviour, IAvatarInputActionsListener
{
    private void Start()
    {
        SpatialBridge.inputService.StartAvatarInputCapture(true, true, true, true, this);
    }

    public void OnAvatarJumpInput(InputPhase inputPhase)
    {
        SpatialBridge.coreGUIService.DisplayToastMessage("Jump input!");
    }
}
public class AvatarInputListenerExample : MonoBehaviour, IAvatarInputActionsListener
{
    private void Start()
    {
        SpatialBridge.inputService.StartAvatarInputCapture(true, true, true, true, this);
    }

    public void OnAvatarJumpInput(InputPhase inputPhase)
    {
        SpatialBridge.coreGUIService.DisplayToastMessage("Jump input!");
    }
}

Changing Avatar Mesh / Visuals

The visual element of an avatar is defined by the Spatial Avatar package. Once you have created an avatar package you can assign it to an avatar using the following.

IAvatar localAvatar = SpatialBridge.actorService.localActor.avatar;
localAvatar.SetAvatarBody(AssetType.Package, {Avatar Package SKU})
IAvatar localAvatar = SpatialBridge.actorService.localActor.avatar;
localAvatar.SetAvatarBody(AssetType.Package, {Avatar Package SKU})

Avatar Animation

You can trigger "one-shot" animations on avatars using Avatar Animation packages. Once you have published an avatar animation you can trigger it on the local avatar using PlayEmote.

public void StartAnimation()
{
	    SpatialBridge.actorService.localActor.avatar.PlayEmote(AssetType.EmbeddedAsset, {Animation Package SKU}, immediately: true, loop: true);
}

public void StopAnimation()
{
    SpatialBridge.actorService.localActor.avatar.StopEmote();
}
public void StartAnimation()
{
	    SpatialBridge.actorService.localActor.avatar.PlayEmote(AssetType.EmbeddedAsset, {Animation Package SKU}, immediately: true, loop: true);
}

public void StopAnimation()
{
    SpatialBridge.actorService.localActor.avatar.StopEmote();
}

Hiding Avatars

The visibility of an avatar can be controlled with the visibleLocally and visibleRemotely properties.

  • visibleLocally hides the avatar for the local client. You can set this for any actor’s avatar.
  • visibleRemotely hides the avatar for everyone. Only available on the localActor’s avatar. Below is an example of hiding all avatars for the local client.
public void SetAllAvatarsVisibilityLocally(bool visible)
{
    foreach (var actor in SpatialBridge.actorService.actors.Values)
    {
        if (actor != SpatialBridge.actorService.localActor)
        {
            actor.avatar.visibleLocally = visible;
        }
    }
}
public void SetAllAvatarsVisibilityLocally(bool visible)
{
    foreach (var actor in SpatialBridge.actorService.actors.Values)
    {
        if (actor != SpatialBridge.actorService.localActor)
        {
            actor.avatar.visibleLocally = visible;
        }
    }
}