search

podcastSonant

Contextual Audio Middleware. 1.0.0. Documentation (c) Andras Gregori @ Gregorigin.com

Native C++ • Zero-Bloat • Data-Driven

https://www.youtube.com/watch?v=xVJVU_sZmpkwww.youtube.comchevron-right

hashtag
1. Introduction

Sonant is a stateless, high-performance audio manager designed for Unreal Engine 5.7+. It eliminates the need for complex Blueprint spaghetti and extensive Physical Material setup by treating audio as Logic, not just Content.

hashtag
Core Philosophy

  • Context Over Configuration: Material sounds are resolved via smart string matching, removing the need to strictly define Physical Surface Types for every asset.

  • Priority Over Logic: Ambiance mixing handles nested overlaps (e.g., Cave inside Forest) automatically via a weighted priority stack.

  • Native Performance: All logic executes in C++ on the Game Instance Subsystem. Zero tick overhead.

hashtag
2. Quick Start

hashtag
Step 1: Enable the Plugin

Ensure Sonant, AudioModulation, and GameplayTags are enabled in your project.

hashtag
Step 2: Create the Configuration

  1. Right-click in the Content Browser.

  2. Select Miscellaneous > Data Asset.

  3. Choose SonantConfig as the class.

  4. Name it DA_Sonant_Global.

hashtag
Step 3: Assign to Project

  1. Go to Project Settings > Game > Sonant Audio.

  2. Assign your DA_Sonant_Global to the Main Config slot.

Sonant is now active. You do not need to add components to your character.

hashtag
3. Surface System (Footsteps & Impacts)

Sonant uses a cascading fallback system to resolve which sound to play when a surface is hit.

hashtag
The Resolution Logic (in order):

  1. Physics Check: Does the hit component have a specific Physical Material assigned? If yes, and it exists in the Physics Map, play that sound.

  2. Smart String Match: (The unique feature). Sonant reads the name of the Material Interface (e.g., M_Temple_Stone_Wet). It checks your Keyword Map for substrings.

    • Example: If your config maps "Stone" to S_Stone_Impact, any material featuring the word "Stone" triggers this sound.

    • Performance: This search runs once per material per session. Results are cached for O(1) lookup speed.

  3. Default: If no match is found, the DefaultSurface sound plays.

hashtag
Setting up the Config (SonantConfig)

Under the Surfaces category:

  • Keyword Map: Add an element.

    • Key: Grass (The substring to find).

    • Sound: Select your Sound Cue or MetaSound Source.

    • Volume/Pitch: Adjust randomization ranges here.

  • Physics Map: Useful for precise overrides (e.g., a "Hollow Metal" grate that visually looks like standard metal).

hashtag
Triggering a Footstep

Call this function from your Animation Blueprint (AnimNotify) or Character Blueprint:

Function: Play Footstep

  • Target: Sonant Subsystem

  • Inputs:

    • Location: Location of the foot bone.

    • Surface Hit: The output of a line trace (standard generic trace).

hashtag
4. Atmosphere System (Mixing & Zones)

Sonant manages Audio Modulation Control Buses using a Priority Stack.

hashtag
The Problem

In standard Unreal Audio, entering a trigger volume sets a Mix. If you enter a second volume (e.g., a pool of water inside a cave) and then leave it, the "Cave" mix often breaks or doesn't return correctly.

hashtag
The Sonant Solution

  1. Define Mix Definitions in SonantConfig.

    • Map Key: A Gameplay Tag (e.g., Audio.Zone.Indoor).

    • Mix Asset: The Sound Control Bus Mix to activate.

    • Priority: An Integer (0-100).

      • Examples: Outdoor = 0, Indoor = 10, Underwater = 50, Combat = 90.

  2. Sonant automatically calculates the Highest Priority Active Tag.

    • If the player is in Indoor (10) and Underwater (50), the system applies the Underwater mix.

    • When the player surfaces, Underwater is popped, and the system instantly reverts to Indoor.

hashtag
Setting up Zones

  1. Create a Blueprint or add a component to a Trigger Box.

  2. Add the Sonant Volume Component.

  3. Set the Atmosphere Tag (e.g., Audio.Zone.Indoor).

  4. Done. The Subsystem handles the overlap/end-overlap logic automatically.

hashtag
5. API Reference (Blueprint & C++)

Sonant is built as a Game Instance Subsystem. It persists across level loads.

hashtag
Blueprint Access

Get the subsystem by typing "Sonant" in the node context menu.

Function

Description

Play Footstep

Resolves the material at the hit location, caches the result, and plays the defined Sound/MetaSound.

Push Atmosphere

Adds a Gameplay Tag to the active stack. Increments reference count.

Pop Atmosphere

Removes a Gameplay Tag. Recalculates the mixer based on the remaining highest priority tag.

hashtag
C++ Access

hashtag
6. Optimization & Technical Notes

  • Assets: Sonant uses TSoftObjectPtr. It does not hard-load your entire audio library into memory. Sounds are loaded on demand or should be managed via standard UE5 Asset Manager rules.

  • One-Time Scan: The string matching logic (ResolveMaterial) performs a string search only the first time a specific Material Interface is walked upon. Subsequent steps use a TMap lookup (~0.00ms cost).

  • MetaSounds: Fully compatible. Assign a MetaSoundSource to the Surface Sound slot to use procedural audio logic (e.g., changing footsteps based on walk speed).

hashtag
7. Technical Architecture & Performance Analysis

This section details the internal logic of the Sonant module, providing transparency regarding memory usage, computational complexity, and execution context.

hashtag
7.1 Module Architecture

Sonant is built on the Singleton-like pattern using the Unreal Engine Subsystem architecture.

  • Type: UGameInstanceSubsystem

  • Lifecycle: Initialized when the Game Instance is created. Persists across Level Transitions. Destroyed on Game Shutdown.

  • Thread Safety: Designed for execution on the Game Thread. Audio playback and Modulation commands are dispatched to the Audio Thread/Render Thread by the Engine automatically.

hashtag
7.2 Surface Resolution (Cached Regex)

The core USP of Sonant is the removal of strict Physical Material requirements via string matching. To maintain high performance, a runtime caching layer is implemented.

Algorithm

  1. Input: FHitResult containing a UPrimitiveComponent and UPhysicalMaterial.

  2. Quick Rejection: If a specific UPhysicalMaterial is defined in the Physics Map, O(1)

  3. Cache Lookup: If no Physics override exists, the system uses the UMaterialInterface* address as a key in a TMap.

    • Complexity: O(1)(Average).

  4. Cold Miss (First Hit): If the Material is not in the cache:

    • The system iteratively performs UsingString.Contains(Keyword) for every entry in the KeywordMap.

    • Complexity: O(N×M) where N is the number of Keywords and M is the string length.

    • Note: This occurs once per unique Material asset per session.

  5. Cache Commit: The result (Subtitle Match or Default) is linked to the UMaterialInterface*.

Performance Implication

  • Amortized Cost: Negligible. The heavyweight string comparison happens only on the very first footstep of a new material type.

  • Memory Footprint: The Cache stores TMap<void*, void*>. For a game with 1,000 unique materials, the memory overhead is < 50KB.

hashtag
7.3 Atmosphere Mixer (Priority Stack)

Sonant avoids the generic "Push/Pop" stack issues (LIFO) by implementing a Weighted Priority State Machine.

Logic

  • Storage: TMap<FGameplayTag, int32> tracks the Reference Count of active triggers.

  • Evaluation: On any Push or Pop event, the system iterates through the active keys (Count>0).

  • Resolution: It compares the Priority integer defined in SonantConfig. The highest integer wins.

  • Transition:

    1. If the winning tag differs from CurrentAppliedMixTag,

      UAudioModulationStatics::DeactivateBusMix is called on the old Mix.

    2. UAudioModulationStatics::ActivateBusMix is called on the new Mix.

Edge Case Handling

  • Nested Volumes: Correctly handles Player -> Enter Forest -> Enter Cave -> Exit Cave -> (Back in Forest).

  • Concurrent Overlaps: Reference counting ensures that if two volumes share the same Tag, the mix remains active until the count reaches zero.

hashtag
7.4 Asset Loading Strategy

Sonant operates on a Soft Reference (TSoftObjectPtr) architecture to ensure minimal memory footprint on boot.

  • Config Data: The SonantConfig Data Asset is small (logic only). It should be loaded at startup (Game Instance).

  • Audio Assets:

    • USoundBase and USoundControlBusMix pointers are Soft.

    • Resolving: The Subsystem performs a LoadSynchronous() call upon resolution.

    • Optimization Note: For large AAA productions, ensure your Sound Cues/MetaSounds are resident in memory via standard Level Streaming or Asset Manager rules to prevent a micro-hitch on the very first trigger.

hashtag
7.5 C++ Class Reference

USonantConfig (DataAsset)

The central registry. Can be subclassed if dynamic injection of rules is required (uncommon).

  • Location: Plugins/Sonant/Source/Sonant/Public/SonantConfig.h

USonantSubsystem (Manager)

The execution engine.

  • Location: Plugins/Sonant/Source/Sonant/Public/SonantSubsystem.h

  • Extension: functionality is virtual; however, composition is preferred over inheritance. Use the SonantSettings to hot-swap configuration assets if different game modes require different rules.

USonantSettings (DeveloperSettings)

Handles the Project Settings integration.

  • Registry Path: /Script/Sonant.SonantSettings

  • Config File: stored in DefaultGame.ini.

hashtag
7.6 Module Dependencies

To link against Sonant in your own C++ modules, add the following to your Build.cs:

Required Engine Plugins:

  • AudioModulation (Enabled by default in Sonant.uplugin)

  • GameplayTags (Core)

hashtag
8. Troubleshooting

  • "Sound not playing on Landscape": Ensure line trace is hitting the Landscape and returning a component. If Physics Material is empty, ensure the Layer Info name contains a keyword (e.g., "Grass").

  • "Mix not activating": Ensure default AudioModulation requires that the Sound Control Bus Mix is loaded. Sonant loads it synchronously on demand, but ensure your USoundControlBusMix asset is saved and valid.

hashtag
9. Legal & disclaimer

9.1 LIMITATION OF WARRANTY (THE "AS-IS" CLAUSE)

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

9.2 UNREAL ENGINE COMPATIBILITY

Sonant is developed and verified for Unreal Engine 5.7. While the architecture relies on stable Subsystem and Audio APIs, Epic Games may alter C++ module dependencies (e.g., AudioModulation, PhysicsCore) in future engine releases.

  • Update Policy: We strive to update Sonant for major engine releases (e.g., 5.8), but we do not guarantee "Day One" compatibility for Preview/Experimental engine builds.

  • Backward Compatibility: Sonant utilizes audio features specific to UE 5.5+. It is not compatible with UE 4.x.

9.3 INTEGRATION & DATA SAFETY

Sonant performs runtime string operations on Material names. While heavily optimized via caching (O(1) post-cache), misuse of the configuration (e.g., mapping generic keywords like "e" or "a" that match 100% of materials) may result in unintended audio behavior.

  • User Responsibility: The user is responsible for verifying the performance impact on their specific target hardware (e.g., Mobile/Switch) using the provided Unreal Profiler tools.

  • Asset References: Sonant uses Soft Object Pointers. It is the user's responsibility to ensure referenced Audio Assets are included in the final cook/package via the Asset Manager or Level Streaming.

9.4 REFUND POLICY

As Sonant is a digital C++ plugin including full source code, all sales on Fab.com are final once the files have been downloaded, in accordance with the standard Fab Marketplace EULA. Refunds are only honored in cases where the plugin is proven technically defective on a clean project within the supported Engine version.

hashtag
10. Support

For bug reports, specific feature requests, or enterprise licensing:

Sonant is a Trademark, designed to make game development more logical and with less bloat.

© GregOrigin LLC 2025

Last updated