Positional channel configuration

Configure positional channels for spatial audio in 3D environments.

Read time 1 minute

Last updated a day ago

If a game has joined a positional channel, it must frequently update the Vivox SDK with the position and orientation of the user in the 3D space that is associated with that channel. The client does this by calling the

VivoxService.Instance.Set3DPosition(GameObject participantObject, string channelName)

method with the GameObject representing the player in the scene, and the

channelName

of an active positional channel with audio connected. You can additionally have your TextState connected, but to set your position, you must connect to audio.

Note

If you plan to have players in 3D and 2D channels are the same time, add players to the 3D channel first, before joining any 2D channels.

A participant's location in a positional channel affects who they can hear and the perceived loudness and direction of other players’ voices. With text enabled, location limits the delivery of text messages to only users within the audible vicinity of the sender. Positional channels use a right-hand coordinate system. When the player avatar is standing facing directly forward, the following criteria applies:

The positive X-axis is to the avatar's right.
The positive Y-axis runs from the avatar's feet upward through their head.
The positive Z-axis runs from the avatar's chest out through their back.

When a player joins a positional channel, the player avatar is placed at a null position until they move to a position.

Note

Unity uses a left-hand, Y-up world coordinate system (positive X-axis is to the right, positive Y-axis is up, positive Z-axis is into the screen). Do not manually perform the conversion between coordinate systems because it is handled internally by the Vivox SDK.

After you set up and join a positional channel with any configured 3D properties, you then report your actor's position and orientation to the Vivox SDK. The best practice recommendation is to update the users position 2-4 times per second. The following code is an example of how to set a user's position in a positional channel:


using UnityEngine;using Unity.Services.Vivox;class PositionalChannelExample : MonoBehaviour{    . . .    // For this example, _nextPosUpdate has been initialized as Time.time at    // game start. _localPlayerGameObject is the GameObject controlled by the local player.    void Update()    {        . . .        if (Time.time > _nextPosUpdate)        {            VivoxService.Instance.Set3DPosition(_localPlayerGameObject, activePositionalChannelName);            _nextPosUpdate += 0.3f; // Only update after 0.3 or more seconds        }        . . .    }    . . .}

This sample code demonstrates methods to limit the number of 3D positional updates that are sent. For example, a time tracking technique in the update method can rate limit update attempts to a reasonable number of times per second. In the sample method

Update3DPosition

, a custom CachedPosition class, caches the player’s position and orientation, which allows for a

Set3DPosition

call if the values change.

Documentation

Development

User Acquisition

Monetization

Industry