Sonant Manual

Native Contextual Audio Manager for Unreal Engine 5.5-5.7

Welcome to Sonant! This plugin replaces scattered audio logic with a unified, data-driven pipeline. From physically accurate footsteps to dynamic room estimation, Sonant handles the complexity so you can focus on the soundscape. Designed for performance and ease of use, Sonant integrates seamlessly with UE5's AudioModulation system.

Installation & Setup

Editor Tools & Validation

Sonant provides robust, game-ready editor tooling to accelerate your workflow and ensure your audio setup is flawless before shipping.

Using the Setup Wizard

1. In your editor, find the BP_SonantSceneSetup actor (generated by the demo script or found in the plugin Content).
2. Drag it into your scene.
3. In the Details panel, click the Run Setup button.
4. Watch the progress bar as Sonant registers all physical materials in your project directly into your Global Config!

Quick Start Guide

Get your first contextual footstep working in under 5 minutes:

1. Prepare Your Audio

Import your footstep sounds and create Sound Cues or MetaSounds for different surface types (Grass, Metal, Stone, etc.).

2. Configure Surfaces

Open your SonantConfig asset and add entries to the Keyword Map:

• Key: Grass (matches materials with "Grass" in the name)
• Sounds Map: Add entry with Key Sonant.Event.Footstep
• Assign your grass footstep Sound Cue

3. Trigger from Blueprint

In your Character Blueprint, during the footstep animation notify:

Get Owning Local Player -> Get Subsystem (Sonant Subsystem)
    -> Play Footstep
        Location: Get Actor Location
        Surface Hit: Line Trace result from foot socket
            

4. Test

Place meshes with materials containing "Grass" in your level and walk on them. You should hear your configured sounds!

Generalized Surface System

Sonant introduces a powerful GameplayTag-driven event system. Instead of just "Footsteps", you can now define any audio event for a surface type—landing, jumping, scuffing, rolling, or custom gameplay actions.

Resolution Priority

Sonant resolves surface types in this order (first match wins):

1. Physical Material Map - Exact asset match (most precise)
2. Material Cache - Previously resolved material lookup
3. Keyword Map - Substring search in material name
4. Default Surface - Fallback configuration

How to Add a New Footstep Type

1. Open your SonantConfig asset.
2. Find or Add an entry in Keyword Map (e.g., Key: "Grass" matches any material with "Grass" in the name).
3. Expand the Sounds map.
4. Add a Key: Sonant.Event.Footstep (or your custom tag).
5. Assign your Sound Cue or MetaSound to the Sound property.
6. Adjust Volume and Pitch Randomization to add variety.

Supported Material Types

Physics Impact System

The PlayImpact API handles collision audio automatically. It calculates intensity based on impact force and selects the appropriate tag, pitch, and volume scaling.

Blueprint Usage

Call PlayImpact in your actor's OnComponentHit event:

Event Hit (MyActor)
    -> Sonant Subsystem: Play Impact
        Location: Hit.Location
        Impact Force: NormalImpulse.Size()
        Surface Hit: Hit Result
            

Thresholds & Logic

The system automatically categorizes impacts into tiers:

• Force < 50.0: Ignored (Silence) - prevents micro-jitter noise.
• Force 50 - 2000: Triggers Sonant.Event.Impact.Light. Pitch is slightly increased (1.2x) for a lighter sound.
• Force > 2000: Triggers Sonant.Event.Impact.Heavy. Pitch is lowered (0.8x) for a heavier thud. Volume scales with force up to 2.0x.

Atmosphere System

The Atmosphere System manages environmental audio transitions through priority-based Control Bus Mix activation. Perfect for areas with distinct acoustic properties.

Common Use Cases

• Underwater: Muffle high frequencies, apply underwater reverb
• Caves: Heavy reverb, echo effects
• Forests: Open ambience, distant wildlife
• Indoors: Room tone, muffled exterior sounds
• Radio Zones: Music mixing areas

Setting Up Atmosphere Zones

1. Create Sound Control Bus Mixes for each atmosphere type in your project
2. In SonantConfig, expand the Atmospheres map
3. Add entries with GameplayTag keys (e.g., Sonant.Atmosphere.Underwater)
4. Set Priority (higher wins): Underwater=100, Cave=50, Forest=10
5. Assign the Mix Asset (your Sound Control Bus Mix)

Using SonantVolume Components

Add a USonantVolume component to any actor to create atmosphere zones:

1. Add the component to your trigger volume or blocking volume
2. Set the Atmosphere Tag property
3. The atmosphere pushes on overlap and pops on end overlap automatically

Nested Atmospheres

Sonant supports nested zones through reference counting. If the player enters a Cave (priority 50) inside a Forest (priority 10), the Cave mix wins. When they exit the cave, it automatically falls back to Forest.

Spline Audio

For volumetric audio sources like rivers, traffic, or long electrical humming, Sonant includes the USonantSplineAudioComponent. It automatically tracks the listener and moves the audio source along the spline to the closest point, creating a seamless volumetric sound.

Usage

1. Create an Actor and add a Spline Component to define your path (e.g., a riverbed).
2. Add the Sonant Spline Audio component.
3. Assign your Sound Asset in the Details panel.
4. The component handles the rest, calculating the closest point on the spline for each player and translating the sound instantly.

Auto Reverb Estimation

Sonant passively scans the environment around the player to determine room size using a 6-axis raycast system. This eliminates the need for manual reverb volume placement in most scenarios.

How it Works

Every 0.5 seconds, the subsystem fires rays in 6 directions (Up, Down, Left, Right, Forward, Back) up to 50 meters. It calculates the Average Open Distance and compares against your Reverb Settings in SonantConfig.

Configuration

In SonantConfig, fill the Reverb Settings array:

• Max Room Radius: The upper limit for this preset (e.g., 500 for Small Room, 2000 for Hall).
• Reverb Mix: The Sound Control Bus Mix to activate. This mix should apply a Reverb Submix Effect.

The system automatically selects the smallest Radius that fits the current average distance (Best Fit algorithm).

Example Presets

Performance Optimization

Material Cache & Pre-caching

Sonant maintains an O(1) lookup cache for material resolutions. The cache auto-initializes with 128 entries and grows as needed. First contact with a new material performs a substring search; subsequent contacts are instant. Furthermore, the PrecacheMaterials() API allows you to force a background scan during level load, sanitizing your KeywordMap and completely eliminating runtime hitches.

Raycast Budget

The auto-reverb system uses a fixed budget:

• Frequency: 2Hz (every 0.5 seconds)
• Ray Count: 6 traces per update
• Max Distance: 5000 units (configurable in code)
• Collision: Uses the dedicated AudioTrace profile to ensure sound waves ignore invisible blockers or foliage, hitting only dense acoustic geometry.

Profiling

Use these console commands to monitor Sonant:

stat sonant        // Display Sonant performance stats (if implemented)
stat game          // General game thread performance
show collision     // Visualize trace queries
            

Optimization Tips

C++ API Reference

Access via USonantSubsystem, a ULocalPlayerSubsystem designed for local listener state, client-side atmosphere stacks, and player-specific reverb decisions.

Internal Methods

Blueprint Guide

Accessing the Subsystem

All Sonant functions are available through the Local Player Subsystem:

Get Player Controller
    -> Get Local Player
    -> Get Subsystem (Class: Sonant Subsystem)
        -> [Any Sonant function]
            

Character Footstep Setup

1. Open your Character Blueprint
2. Add a Line Trace by Channel before the footstep should play
3. Set Start to Foot Socket location, End to Start + (0,0,-50)
4. On Hit: Get Local Player → Get Subsystem (Sonant)
5. Call Play Footstep with Hit Location and Hit Result

Physics Impact Setup

1. Select your physics-enabled mesh
2. Add Event On Component Hit
3. Get Sonant Subsystem
4. Call Play Impact with:
   • Location: Hit.Location
   • Impact Force: Normal Impulse → Vector Length
   • Surface Hit: Hit Result pin

Atmosphere Volume Setup

1. Create a Blueprint extending Actor
2. Add a Box Collision component
3. Add Sonant Volume component
4. Set Atmosphere Tag property (e.g., Sonant.Atmosphere.Underwater)
5. Set collision to Overlap All or specific channels

Best Practices

Troubleshooting

Frequently Asked Questions

Does Sonant work with MetaSounds?

Yes! Sonant works with any USoundBase asset, which includes Sound Cues, MetaSounds, and Wave files.

Can I use Sonant with multiplayer?

Yes. Sonant runs locally on each client. For replicated physics events, trigger the audio on each client when the replicated event occurs. The demo generators include network-safe checks.

Does it support Niagara particle audio?

Sonant handles surface-based audio events. For particle audio, use Niagara's built-in audio or trigger Sonant functions from Blueprints based on particle collision events.

Can I disable auto-reverb and use manual zones?

Absolutely. Auto-reverb is optional. You can leave the Reverb Settings array empty and use atmosphere zones exclusively.

Is there a performance cost for having many surface types?

No. Once cached, surface resolution is O(1) regardless of how many types you have. The only cost is initial memory for the cache entries.

Does Sonant work with World Partition?

Yes. Sonant operates independently of level streaming. Atmosphere zones should be placed in persistent levels or appropriate sub-levels.

Can I extend Sonant with custom C++?

Yes. Sonant is designed as a foundation. Inherit from USonantSubsystem or modify the plugin source directly for project-specific needs.

Demo & Quick Start Content

Sonant includes a fully automated Python script that generates a comprehensive demo system, complete with synthetic placeholder audio, prefabs, and a showcase map directly into your project's Content folder.

import sys; sys.path.append(r"C:\1gregorigin\SonantDev 5.7\Plugins\Sonant\Resources"); import GenerateSonantContent; GenerateSonantContent.run()

What's Included in the Generated Content?

Replacing the Placeholder Audio

The generated synthetic audio is completely royalty-free and safe for prototyping. When you are ready for production:

1. Open the SonantConfig asset assigned in your Project Settings.
2. Under the Keyword Map or Physics Map, replace the referenced Sound Waves with your own high-quality assets.
3. Adjust the Volume and Pitch Randomization multipliers to fit your new sounds.