Package

You find the Elias Unity Plugin in the Extras folder of the Elias Studio application. The Extras folder can easily be opened from within Elias Studio - you find the menu option under the three-dot menu located in the application top bar, then under the “about” section.

The plugin is delivered as a unity UPM package, which is a tgz file named "audio.elias.unity-plugin.tgz". You import it to your Unity project by clicking on the + icon in the Unity Package Manager.

Once installed, you will also have the option to install samples for the plugin from the samples tab of the package entry in Unity Package Manager.

Important! 
Make sure your organisation is using a single version of Elias for your project. This means that the version of Elias Studio and the Unity Plugin should have come from the same installation on your local machine and everyone in the team should install using the same installer file. Version mismatch can cause the plugin to not work as expected.

Platforms

The Elias Unity Plugin is compatible with the following platforms:

• Windows (x64 only)
• macOS (arm64 and x64)
• iOS (arm64 together with simulator support for both arm64 and x64)
• Android (arm64, armv7 and x64)

The Elias system

Designtime and Runtime

The Elias Unity Plugin integrates to the Elias system through two parts, the Runtime and the Designtime.

The distinction between Elias Designtime and Runtime is similar to the distinction between the Editor and the Runtime code in your Unity project.

The runtime is what is bundled when you build your Unity project and is used at runtime. The runtime performs all audio playback. The main role of the designtime, on the other hand, is to support advanced content management.

The designtime is used when you work in Unity Editor - both while in edit mode but also in playmode. To support the audio generation, the designtime also contains a runtime. The runtime contained in the designtime is wired to the content management, enabling live editing where changes to the audio project takes effect in the playback immediately.

The main concept for organizing content in Designtime is a project. The main concept for organizing playback in the Runtime is a session.

Remote session from Elias Studio

While working in the Unity Editor in a project that contains a Elias Unity Plugin, you can use Elias Studio to connect to the Elias project that is associated with the Elias components you use in your scenes.

This is a very simple process, you simply have to open the Elias Studio application and select the listed remote session from the starts screen.

Once opened, you can live edit your audio project, having the changes taking effect immediately in the playback (if you are in play mode in your unity project).

Elias projects

Although integrated into Unity through the Elias Unity Plugin, the Elias system is a separate system that can be used fully standalone. When working with an Elias project, you work with assets organized into folders. Once created, the Elias assets can in turn be used in your Unity project.

The Elias assets that are directly selected from the unity project are:

• Patch - these are models for sounds effects or a system for music playback
• Zone - these are spatialization models for acoustic zones

Parameters

Parameters are defined in the Elias project and are used to control the behaviour of the sound effects and music at runtime. There are two kinds of parameters.

• Patch parameters - these are used to control the behaviour of individual sound instances
• Global parameters - these can be used for controlling individual sound instances but also for groups of sounds at the same time. Global parameters can also control the mixer graph.

Elias supports aA number of different signal types for the parameters:

• Boolean parameters - You can set them to true or false
• Integer parameters - You can set them to an integer value
• Float parameters - You can set them to a float value
• Enum parameters - You can set them to an enum value defined in an enum asset in the Elias project
• Pulse parameter - These don't contain a value but can be used to trigger actions at runtime

Your unity project

You involve the Elias project through the use of several Unity components provided by the Elias Unity Plugin:

• Session - The runtime session is the main unit of organization of playback in the runtime. You can think of the session as a container for the sound instances and spatiatialization information needed for the playback. A session itself is associated with a runtime instance. Several sessions can be organized within the same runtime instance but there is no interaction between the sounds of separate sessions.
• Listener - In each session, you need a listener. Since the listener has a location and orientation, the Elias Runtime will know how to spatialize the sounds correctly.
• Sound Instance - This is usually an ambience sound, a sound effect, but it can also be a component used for controlling the music playback. A sound instance is associated with a Patch asset in the Elias project and if the patch has parameters, they can be used to control the playback in real-time. The patch is also assocated with a spatialization preset in the elias project, controlling how the sound instance will be spatialized.
• Zone Instance - This is used for spatialization within a volume in your scene. A zone instance is associated with a zone asset in the Elias project. The zone asset holds the attributes for the spatialization of the zone.

How to use the Elias Session component

The session component creates an Elias runtime session. You can think of it as a container for sound instances and spatialization information. It is also here where you connect to an elias project. With a reference to the session component, you can programmatically access the global parameters of the elias project. The session component also holds fields for configuring the playback of the session, like buffer size and sample rate.

How to use the Elias Listener component

In normal circumstances you only need one listener in your scene. The listener component is used to define the location and orientation of the listener in the session.

You can associate the listener component with a session component. If you don't make this connection, the listener will automatically be associated with the first session component found in the scene.

Placement

The listener component is ideally placed on the Main Camera in your scene. It may also be placed on the player. In third person games, the listener is sometimes placed between the camera and the player character.

How to use the Elias Sound Instance component

This is the sound component where you will select a patch. Elias Sound Instance objects can be viewed as sound sources but with a major twist. Instead of managing audio assets and playback of specific sounds from the code in Unity we simply just set parameter values to a sound instance.

You can associate the sound instance component with a session component. If you don't make this connection, the sound instance will automatically be associated with the first session component found in the scene.

How to use the Elias Zone Instance component

Once you create a zone instance component, you can edit the associated volume in the Unity scene.

You can associate the zone instance component with a session component. If you don't make this connection, the zone instance will automatically be associated with the first session component found in the scene.

Component Lifecycles

The listeners, sound and zone instances are dependent on a runtime session already being established. Therefore the session component has a somewhat different lifecycle compared to the other components. When other components are started, the session is already established. And the session is only updated after all other components have been updated. When working in the Unity Editor, the session component is responsible for holding a connection to the associated Elias project, so the lifecycles are slightly different between the Unity Editor and a standalone or platform build.

Editor Context Lifecycle Events

Below is a diagram on how the component lifecycles are handled when working in the Unity Editor. Note that the session component is responding to lifecycle events even when not in play mode. 

Standalone or Platform Build Context Lifecycle Events

Below is a diagram on how the component lifecycles are handled when working when you have built the game as standalone or for some platform. 

Source

Although the Elias system is delivered as precompiled binaries, the source code for the unity integration is provided inside of the tgz file. The file can easily be expanded using 7zip, or any other tool that can extract tgz files. The expanded package can still be imported into your unity project using the unity package manager.

Package structure

The package layout for the Elias Unity Plugin generally follow the recommendations given by Unity here.

Libraries & API

Embedded in the package, in the Plugins folder, are binary library files for Elias Designtime and Elias Runtime. Separate files are provided for each platform/architecture combination. You are encouraged to use the provided Elias components in order to use the Elias system. But the components in turn use some C# classes that we'd like to explain so it can help if you need to troubleshoot some problem. For runtime access, the components call an instance of the EliasRuntime class. This class provides a logical and friendly API against the runtime. The instance of EliasRuntime represents a runtime instance as it has been created in Elias Runtime. EliasRuntime in turn calls the EliasRuntimeLibrary class which is a direct C# wrapper for the Elias Runtime C API.

EliasDesigntime is the friendly API for accessing Elias Designtime. It represents a designtime instance and provides automatic management of the API keys that are needed for designtime calls. EliasDesigntime in turn calls EliasDesigntimeLibrary which is a direct C# wrapper for the Elias Designtime C API. The C API provided by Elias Designtime is only a transport API, the real API is based on GraphQL and is sent and received as strings using the C-API.

Samples

Elias Footstep Demo

This demo scene called “EliasFootstepDemo.unity” can be found as a sample provided with the Elias Unity Plugin package. This example also comes with an Elias project. For simplicity of importing the sample, the Elias Project is placed inside the assets of the sample. This is not common practice, however, since it is better to keep Elias projects outside the assets of the unity project. We recommend to place Elias projects in some folder in your project, but outside of the Assets folder.

Once imported, you should be able to run the scene without any additional setup. When you play the scene you can listen to the footsteps. It triggers footstep sounds as the first-person character moves around and will switch samples depending on what surface the character will walk on.

The Elias project

Once you have got running with this demo scene, you can open Elias Studio and connect to the remote session provided by Elias Unity Plugin. In the Elias project you will find The “Footstep_Demo” patch. The nodes used within the patch from left to right and see how this system work:

• Distance to Pulse - This is a special node that will keep track of something in the scene, the listener in this example, and once it has moved a specified distance (set by the threshold) a pulse will be sent out.
• Pulse Switch: Materials - You can create a Pulse switch node from any Enum Asset you have available, and in this example, we have created an Enum with the two items “Concreate” and “Metal”. In this case, the switcher can then be in either of these two states.
• Connected to the switcher is the global Enum parameter, and this is the parameter that the game sets as the player steps on each surface type.
• Randomizer - Branching off after the Distance to pulse we also have a randomizer node, that when getting a pulse, will randomize a value between the specified minimum and maximum values. This one connects to the pitch socket on the two sound players to add some more variation to every step.
• The two sound players - The two sound players represent the two different surface types, so they each contain 7 samples of the footsteps. Which one of the two sound players that is going to be played is depending on the state of the global “FootstepMaterials” parameter.
• The sound players output the sound to the same Output node and will play the sound through the selected group channel called “Master”, found in the mixer.

To summarize: the movement of the listener will generate pulses in even intervals that will first look at what current material type is active and then play the corresponding sound player.

The “FootstepDemo” unity scene components.

The unity scene

Elias session component - is placed on the game object called “EliasSession” and is where we connect to the Elias project.

Elias listener component - is placed on the Main Camera found in the FPSPlayer. The FPSPlayer has some control scripts to make the movement possible, so this is what changes the location of the listener and what the node in the patch is keeping track of.

FootStepMaterialSelector script - This script is where we update the parameter “FootStepMaterials” and is what the pulse switcher Materials node will look at to decide its current state.

MaterialType script - Can be found on the objects “ConcreteFloor” and “MetalFloor” and looks at the Elias Enum found in the Elias project called “footstepMaterial”. It has a public EliasEnumValue that will let the user select on the component in the inspector what surface type this floor is. When the player collides with the floor it will then look at what surface type it is (what Enum item it has selected) and then update the state in the FoorStepMaterialSelector script.