Package

You find the Elias Godot Plugin in the Extras folder of the Elias Studio application. The Extras folder can easily be opened from within Elias Studio. On Windows you find the menu option under the three-dot menu located in the application top bar. On macOS you reach the menu at the top of your screen like for all other applications. You reach the Extras folder through the Extras option of the "About" section in the menu.

The plugin is delivered as a zip file according to common practice for Godot named "elias-godot-plugin.zip". You import it to your Godot simply by unzipping the file in your project root directory. The plugin files will appear as "elias_godot_plugin" under your "addons" folder.

Important

Use one Elias version across your team. Elias Studio and the Godot Plugin should come from the same installer package. Version mismatch can cause unexpected behavior.

If you only have the Godot plugin, you can check out how the integration works but you will not be able to create or edit audio assets until you also have Elias Studio. please request the full solution through clicking on "Download Full Solution" in the about-dialog.

You can verify versions here:

• Elias Studio: About dialog
• Godot plugin: Elias button in the editor toolbar

Platforms

The Elias Godot 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 Godot 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 Godot project.

The runtime is what is bundled when you export your Godot 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 the Godot Editor - both while in edit mode but also in play mode. 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.

Connected work from Elias Studio

While working in the Godot Editor in a project that contains an Elias Godot Plugin, you can use Elias Studio to quickly open the Elias project that is associated with the Elias nodes you use in your scenes.

This is a very simple process, you simply have to open the Elias Studio application and select the listed project from the start screen. When the project is actively open in Godot, a Godot icon is displayed to the right of the project listed in Elias Studio.

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 Godot project).

Elias projects

Although integrated into Godot through the Elias Godot 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 Godot project.

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

• Patch - selected in the sound instance node - these are models for sounds effects or a system for music playback
• Config - selected in the sound instance node - these are derivations of patches, edited as a form in Elias Studio
• Zone - selected in the zone instance node - these are spatialization models for acoustic zones

Parameters

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

• Patch parameters - these are used to control the behavior 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 a number of different types of 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 Godot project

You involve the Elias project through the use of several Godot resource and node types provided by the Elias Godot Plugin:

Resources

• Asset Context - This is where you connect to the Elias project.

Nodes

• 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 spatialization 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 or a sound effect, but it can also be a node used for controlling the music playback. A sound instance is associated with a Patch or a Config asset in the Elias project and if the patch has parameters, they can be used to control the playback in real-time. The patch or config is also, in turn, associated 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 Asset Context resource type

For a typical Godot project you create an Elias asset context and place it directly under the root of your project. In this asset context, you select the Elias project that you want to use in your Godot project.

Every Godot resource is associated with the Elias asset context that is closest to it in the resource folder hierarchy, moving up towards the project root folder. Nodes in a Godot scene gets its asset context association from how the scene is located in the resource folder hierarchy.

All Elias nodes that relate to an Elias project will be marked as invalid when first created or when selecting a new Elias project in the associated asset context. This is because project settings and content differs between Elias projects so those nodes will not be able to function until they are properly associated with the new project. You will see this as a warning in the Godot Editor when you inspect the node.

How to use the Elias Session node type

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

When first created or if you change the Elias project in the associated Elias Asset Context, the session node needs to be re-initialized to be valid.

How to use the Elias Listener node type

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

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

Placement

The listener node 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 node type

This is the sound node where you will select a patch or a config. 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 Godot we simply just set parameter values to a sound instance.

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

How to use the Elias Zone Instance node type

Once you have created a zone instance node, you can edit the associated volume in the Godot scene.

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

Node Lifecycles

The listeners, sound and zone instances are dependent on a runtime session already being established. Therefore the session node has a somewhat different lifecycle compared to the other nodes. When other nodes are started, the session is already established. The session is only updated after all other nodes have been updated.

In pure editor scene editing, the runtime session is not established for scene playback. When running in play mode from the editor, however, a session is created and dependent nodes are activated against it. In exported builds, the same node lifecycle shape applies, but the session uses a self-managed runtime instance instead of wrapping the designtime runtime handle used in editor context.

Editor Context Lifecycle Events

Below is a diagram showing lifecycle behavior while using Godot Editor (including play mode launched from editor): 

Standalone or Platform Build Context Lifecycle Events

Below is a diagram showing lifecycle behavior in exported games (non-editor runtime): 
 

Exporting

When exporting your game, Elias will export audio assets to the "res://elias/assets" folder in your project. The logic for what goes into the export follows the selection you make in the preset (based on the export template).

Source

Although the Elias system is delivered as precompiled binaries, the source code for the Godot integration is provided inside of the zip file.

Plugin file structure

The file and folder layout for the Elias Godot Plugin is quite simple:

• The bin folder contains the Elias GDExtension binaries used for different platforms
• Under the gd folder there is an editor and a runtime folder. Both are used when running in edit and play modes. When running an exported project, only the contents of the runtime folder are used.

Libraries & API

Embedded in the plugin, in the bin 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 nodes in order to use the Elias system. But the nodes in turn use some GDScript and GDExtension classes that we'd like to explain so it can help if you need to troubleshoot some problem. For runtime access, the nodes 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 GDScript 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 GDScript 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.

Implementation Architecture

This section describes key software architecture decisions and operational concerns in the plugin implementation.

Plugin bootstrap responsibilities

When the plugin enters the tree in the editor, it wires up several responsibilities:

• Adds a toolbar button and "About" dialog integration
• Registers and syncs Elias asset contexts in project settings
• Registers custom inspector plugins for Elias resources and nodes
• Registers the custom 3D gizmo/tool for zone editing
• Registers the custom export plugin that builds Elias runtime assets during Godot export

When the plugin exits the tree, all these integrations are explicitly disconnected/removed.

Boundary between editor and runtime code

The plugin keeps a strict separation between editor and exported-runtime behavior:

• Editor-only behavior is guarded by @tool scripts and editor checks (OS.has_feature("editor") / Engine.is_editor_hint())
• Exported projects use runtime-only data captured during export (for example, serialized asset-context references and validity flags)
• Runtime code can reference a designtime abstraction, but only the editor provides a real implementation; exported games get a stub base class

This separation is important to avoid accidental designtime dependencies in shipped builds.

Asset Context hierarchy and project ownership

Asset context lookup is folder-based and hierarchical:

• The node/scene starts lookup from its own resource folder
• If no asset context is found there, lookup moves upward directory by directory
• The nearest context wins

Project ownership is also hierarchical:

• Any context with a selected .elias project becomes a project master
• Child contexts can inherit project association from parent contexts
• The "project asset context" is the first context in the parent chain that has a selected project

This design supports large projects with multiple content roots while still allowing per-subtree overrides.

Node validity model and invalidation behavior

Elias nodes are considered valid only when all required associations are consistent:

• Basic nodes require a resolved asset context
• Project-based nodes additionally require a resolved project and matching selected_project_uuid

Changing project selection in an associated context invalidates previously configured nodes by design. This protects against silent mismatch between serialized node settings and the newly selected Elias project schema/content.

Session ownership and lifecycle orchestration

EliasSession3D is the lifecycle anchor for playback:

• In _ready, it resolves project context, sets up runtime, creates a session, then activates contained dependent nodes
• In _exit_tree, it deactivates dependent nodes first, then destroys runtime session/runtime wrapper
• It performs session update via deferred call so updates are committed after other nodes have processed for the frame

Session-dependent nodes (Listener, Sound Instance, Zone Instance) register themselves with the effective session and react to:

• _on_session_ready
• _on_before_session_destroyed

If no explicit session is set, they fall back to the first session instance found.

Runtime wrapper modes (shared vs self-managed)

EliasRuntime has two operational modes:

• Self-managed mode: creates and owns a native runtime instance (typical in exported game)
• Handle-wrapping mode: wraps a runtime context handle provided by designtime (typical when running in editor/play mode with connected project)

This enables live editing in editor while keeping exported runtime independent.

Designtime transport architecture

Designtime calls are GraphQL requests sent over the designtime C transport API:

• EliasDesigntime acquires/releases API consumer keys
• Calls are guarded with an is_calling gate to avoid parallel invocations through this singleton
• URI translation is performed between designtime-specific URIs and stable project-based URIs (elias://project/...) used in Godot-side models
• Open projects are tracked in-memory to avoid repeated open calls and preserve project URI/model pairing

Export architecture and dependency collection

The export flow is split into two stages:

Scene customization stage in EliasBuilder

Runs for selected scenes

Updates Elias node runtime-only serialized fields (runtime_only_*) before packaging

Asset build stage in EliasExporter

Collects directly referenced Elias assets from scene graph state

1. Resolves transitive/indirect references via designtime API
2. Adds implicit required runtime assets (global parameters, group channels, default mixer, default spatial preset)
3. Exports runtime model files into res://elias/assets/...
4. Builds eliasrtindex.txt mapping model IDs to file paths

The runtime reader context depends on this index to resolve model IDs at runtime.

Runtime file contract

Current runtime asset contract:

• Root folder: res://elias/assets
• Runtime model extension: .eliasrtmodel
• Runtime index file: eliasrtindex.txt

The reader context asserts when a requested model ID is missing from the index. This makes export completeness critical.

Custom editor UX architecture

The plugin adds specialized editor UX beyond standard inspectors:

• Custom asset picker editor property with server-side filtering (listAssets)
• Validation-aware inspectors that hide/disable fields when the node is invalid
• Session inspector "Initialize" action to copy project default audio settings into node settings
• Zone gizmo/tool with:
• Handle dragging for polygon vertices and height
• Cmd/Ctrl-click edge insertion and vertex removal
• Mesh preview generation for zone volume
• Vertex-count limits and user warning feedback

Performance and scaling concerns

Current implementation choices to be aware of:

• Asset context registry can perform full filesystem scanning for context resources
• Some inspector UI interactions trigger live designtime calls (asset listing/filtering)
• Listener, sound instance, and zone instance update transforms each frame
• Zone geometry updates are pushed to runtime each frame
• Parameter lookup by name is linear over parameter arrays (with TODO comments to cache IDs)

These are acceptable for typical projects but worth monitoring in very large scenes/projects.

Error handling strategy

Error handling is intentionally mixed depending on context:

• assert(...) for programmer/contract violations (invalid IDs, invalid lifecycle ordering)
• push_error(...) for runtime/editor failure visibility in Godot output
• push_warning(...) for non-fatal API/transport issues

In production pipelines, teams should consider adding additional telemetry around designtime/export failures.

Concurrency and thread-safety assumptions

The plugin assumes main-thread-oriented usage:

• Runtime entity updates are called from node _process
• Session commit is deferred inside frame processing
• Designtime singleton call path blocks parallel calls through an is_calling guard

If advanced tooling introduces multithreaded access patterns, this model should be revisited.

Extension points

Common extension points in the current architecture:

• Add new inspector plugins for additional Elias node/resource types
• Extend export asset collection rules to support new node properties or resource references
• Customize runtime reader/export context for alternative storage backends
• Build richer validation/fix-up workflows in editor utilities
• Introduce parameter ID caching in session/sound nodes for faster frequent calls