Sonant Manual
Native Production-Oriented Contextual Audio Middleware for Unreal Engine 5.5 - 5.8
Sonant replaces scattered, ad-hoc audio triggers with a deterministic, data-driven audio pipeline. By evaluating gameplay-tagged events against exact physical surface properties, authored atmosphere priorities, and real-time raycasted room enclosure estimates, Sonant manages your entire spatial soundscape while maintaining streaming safety and minimal runtime footprint.
Unified Audio Subsystem for Surfaces, Atmospheres, and Acoustics
Sonant resolves physical surfaces via exact soft overrides and canonical tags, streams associated SoundBase, Niagara, and Decal assets asynchronously, and dynamically controls AudioModulation Sound Control Bus Mixes without polluting Blueprint graphs.
2. Key Features
๐ฏ 5-Tier Surface Resolver
Precise resolution hierarchy prioritizing Soft Physical Material Overrides and Soft Material Overrides ahead of canonical EPhysicalSurface maps, keyword searches, and fallbacks.
๐ฅ Physics & Normalized Impacts
Data-driven impact tiers mapping normalized force/intensity to customized GameplayTag events with independent volume/pitch scaling and minimum threshold jitter filtering.
๐ Listener-Space Auto Reverb
Amortized 2Hz raycast room probe sampling 6 axes from the active listener camera position, computing enclosure confidence, wall opposition, and ceiling evidence before applying reverb mixes.
๐๏ธ Priority Atmosphere Stack
Reference-counted atmosphere volumes that push/pop Control Bus Mixes by priority. Supports level streaming overlap adoption and graceful pawn unpossession lifecycle management.
๐ Spatial Utility Components
Includes USonantFoleyComponent for movement audio, USonantSplineAudioComponent for rivers/curves, and USonantProjectileTracker for pass-by closest approach audio.
โก Streaming Safety & Retention
Async loading for soft audio, Niagara, and decal references with completed handle pruning (IsLoadingInProgress) and a 32-entry bounded retention cache for visual FX.
๐ Server-Validated Networking
Multicast RPCs with Token Bucket rate limiting, server-side collision traces, quantized net vectors, and local client echo suppression via bOwnerAlreadyPlayed.
๐ ๏ธ Editor Nomad Setup & Audit
Dedicated Editor tab (Window > Sonant Configuration) offering single-click config generation (DA_Sonant_Config_Default) and read-only production asset auditing.
3. Architecture & Modules
Sonant separates runtime gameplay logic, editor configuration utilities, and interactive showcase environments into three distinct engine modules to guarantee clean shipping builds:
| Module | Type | Present in Cooked Build? | Primary Responsibility |
|---|---|---|---|
| Sonant | Runtime | Yes | Core subsystem, surface resolution, atmospheres, auto-reverb, and spatial components. |
| SonantEditor | Editor | No | Nomad setup tab spawner, asset wizard, and read-only production auditor. |
| SonantDemo | UncookedOnly | No | Interactive feature demo environment, showcase actors, and test character. |
4. Installation & Setup
Setting up Sonant requires enabling prerequisite engine plugins and registering your project's main configuration asset.
Navigate to Edit > Plugins. Enable AudioModulation, Niagara, and Sonant. Restart Unreal Editor when prompted.
In the main editor menu bar, open Window > Sonant Configuration. This tab provides a central hub for configuring Sonant.
Click Create or assign default config. This automatically generates a populated DA_Sonant_Config_Default asset at /Game/Sonant/ and links it to Project Settings > Plugins > Sonant Audio.
Click Run production audit to inspect your setup. The audit checks for valid soft asset references, unassigned surface entries, and proper collision settings without altering project files.
5. Editor Tools & Production Audit
The SonantEditor module equips audio programmers and technical sound designers with non-intrusive setup and validation tools accessible from Window > Sonant Configuration.
Key Production Audit Checks
- Config Validation: Ensures a valid USonantConfig asset is soft-referenced in project settings.
- Unassigned Sound Warnings: Identifies surface tags with missing sound, Niagara, or decal references.
- Tag Consistency: Checks that mapped GameplayTags exist in the project's tag dictionary.
- Zero Collision Mutation: The auditor is strictly read-only; it will never automatically add or modify project collision channels.
6. Data Asset Reference (USonantConfig)
The USonantConfig primary data asset houses all data-driven definitions for surfaces, impacts, atmospheres, and reverb presets.
FSonantSound Structure
| Property | Type | Description |
|---|---|---|
| Sound | TSoftObjectPtr<USoundBase> | Soft reference to SoundWave, SoundCue, or MetaSound asset. |
| Volume | float (Default: 1.0) | Base volume multiplier for this event. |
| PitchRandomization | float (Default: 0.05) | Random pitch variation +/- centered around 1.0. |
| Attenuation | TSoftObjectPtr<USoundAttenuation> | Optional attenuation override. |
| Concurrency | TSoftObjectPtr<USoundConcurrency> | Optional concurrency limits override. |
| VFX | TSoftObjectPtr<UNiagaraSystem> | Optional Niagara particle system spawned at impact location. |
| Decal | TSoftObjectPtr<UMaterialInterface> | Optional decal material projected on the surface. |
| DecalSize | FVector (Default: 10,10,10) | Extents of the projected decal volume. |
| DecalLifeSpan | float (Default: 10.0s) | Lifespan before the decal actor is destroyed. |
USonantConfig Fields
| Category | Property | Type | Description |
|---|---|---|---|
| Surfaces | SurfaceTypeMap | TMap<EPhysicalSurface, FSonantSurfaceDef> | Canonical surface enum mappings (fastest lookup). |
| Surfaces | PhysicalMaterialOverrides | TMap<TSoftObjectPtr<UPhysicalMaterial>, FSonantSurfaceDef> | Exact soft physical material asset overrides. |
| Surfaces | MaterialOverrides | TMap<TSoftObjectPtr<UMaterialInterface>, FSonantSurfaceDef> | Exact soft material interface overrides. |
| Fallback | KeywordPriority | TArray<FString> | Explicit keyword priority list before longest match sorting. |
| Fallback | KeywordMap | TMap<FString, FSonantSurfaceDef> | Material name substring mapping. |
| Fallback | DefaultSurface | FSonantSurfaceDef | Last-resort surface when no other rule matches. |
| Impacts | ImpactTiers | TArray<FSonantImpactTier> | Array of normalized intensity thresholds and event tag mappings. |
| Atmospheres | Atmospheres | TMap<FGameplayTag, FSonantMixDef> | Authored atmosphere tags mapped to Sound Control Bus Mixes & Priority. |
| Reverb | ReverbSettings | TArray<FSonantReverbDef> | Array of room radius limits mapped to Reverb Bus Mixes. |
7. Project Settings Reference (USonantSettings)
Configured in Project Settings > Plugins > Sonant Audio (DefaultGame.ini):
| Category | Setting Name | Default | Description |
|---|---|---|---|
| Core | MainConfig | None | Soft pointer to project's primary USonantConfig asset. |
| Tags | DefaultFootstepTag | Sonant.Event.Footstep | Default tag used by PlayFootstep. |
| Events | MaxEventDistance | 15000.0 | Distance threshold beyond which audio events are culled. |
| Events | MaxVolumeMultiplier | 4.0 | Hard safety clamp on volume inputs. |
| Occlusion | bEnableEventOcclusion | false | Opt-in line-of-sight audio occlusion trace. |
| Occlusion | EventOcclusionTraceChannel | ECC_Visibility | Trace channel used for line-of-sight occlusion checks. |
| Occlusion | OccludedVolumeMultiplier | 0.45 | Volume multiplier applied when sound origin is occluded. |
| Visuals | MaxVisualEffectDistance | 5000.0 | Distance threshold for spawning Niagara particles. |
| Visuals | MaxDecalDistance | 3000.0 | Distance threshold for spawning decal materials. |
| Impacts | MinimumImpactForce | 50.0 | Force threshold below which collisions are muted. |
| Impacts | ImpactForceForFullIntensity | 5000.0 | Force magnitude mapped to normalized intensity 1.0. |
| Auto Reverb | bEnableAutomaticReverb | false | Opt-in 2Hz listener-space raycast room scanner. |
| Auto Reverb | ReverbTickRate | 0.6s | Time interval for a complete 6-axis acoustic scan. |
| Auto Reverb | MinimumEnclosureConfidence | 0.75 | Confidence threshold required to classify space as enclosed. |
| Network | bAllowClientAudioReplication | false | Opt-in client-originated RPC audio replication. |
| Network | NetworkMaxEventsPerSecond | 8.0 | Token-bucket rate limit per component for client RPCs. |
8. Surface System & Precedence Ladder
Sonant evaluates hit surfaces against a strict 5-level precedence ladder. Most specific matches always take priority over general defaults:
Matches exact UPhysicalMaterial soft object reference in PhysicalMaterialOverrides.
Matches exact UMaterialInterface soft object reference in MaterialOverrides.
Matches standard engine surface type enum in SurfaceTypeMap.
Evaluates explicit keyword priority, then longest substring match against material name.
Guarantees audible playback using DefaultSurface when no other rule matches.
9. Physics & Impact Tiers
Physics impact audio is calculated using data-driven impact tiers. Each tier defines a minimum normalized intensity, target event GameplayTag, volume scaling range, and pitch scaling range.
10. Atmosphere System & Priority Stack
USonantVolume and ASonantBSPVolume manage authored atmospheric states using a priority-based push/pop stack that controls AudioModulation Sound Control Bus Mixes.
๐ Priority Stack Layering
When multiple atmosphere volumes overlap, the active mix with the highest priority parameter wins. Lower priority atmospheres remain queued on the stack.
๐ Streaming Overlap Adoption
USonantVolume automatically detects and adopts pawns that are already inside its bounds when a level stream finishes loading during play.
๐ป Unpossession Safety
A pawn unpossessed while inside a volume retains its atmosphere state until it physically exits or the volume is destroyed, preventing abrupt audio pops.
11. Spatial Utility Components
Sonant ships with three specialized spatial audio components tailored for distinct movement and trajectory requirements:
๐ USonantFoleyComponent
Translates owner actor velocity or external normalized intensity into continuous movement audio. Features configurable smoothing, local-only policy, async asset preloading, and automatic silent source suspension when motionless.
ใฐ๏ธ USonantSplineAudioComponent
Owns a persistent non-auto-destroy AudioComponent for river, highway, or ambient spline paths. Computes the true nearest point between the spline and active listeners, starting playback only when within hearing range.
๐ USonantProjectileTracker
Evaluates swept projectile movement segments against all local listeners between ticks. Triggers pass-by audio at the exact closest approach point so high-velocity projectiles never skip audible radius boundaries.
12. Audio Occlusion & Scalability
Sonant provides optional per-event line-of-sight occlusion traces using a dedicated trace channel (SonantEventOcclusion) lifted away from source surfaces. Occlusion modifies volume level only and never pitch-shifts as a low-pass substitute.
13. Multiplayer Networking & Echo Control
USonantNetworkComponent handles server-validated impact broadcasting without sending asset paths across the network.
14. Listener-Space Auto Reverb
When enabled (Sonant->SetAutomaticReverbEnabled(true)), the automatic reverb estimator performs an amortized 2Hz raycast probe in listener space.
- Enclosure Rules: Requires horizontal coverage, an opposing-wall pair, and minimum confidence. Ground alone cannot classify an outdoor listener as enclosed.
- Authored Overrides: Authored atmospheres with bSuppressAutomaticReverb take precedence over the automatic estimator.
15. Streaming Safety & Memory Model
Sonant enforces strict streaming hygiene to prevent transient asset memory leaks during continuous gameplay.
๐งน Completed Load Pruning
Streamable handles are pruned via IsLoadingInProgress(). Handles that finish loading are properly retired, returning tickable subsystem overhead to zero when idle.
๐ผ๏ธ 32-Entry Visual Retention Window
Niagara particle systems and decal material assets stay cached within a bounded 32-entry sliding window, keeping repeated effects instant without unbounded memory growth.
โก Explicit Preloading
PreloadEvent(Tag) guarantees zero first-frame stutter for critical events. Call ReleasePreloadedAssets() when leaving the region or biome.
16. Scalability & Console Controls
Sonant exposes console variables for live diagnostics and platform scalability policy tuning:
| Console Variable | Values | Description |
|---|---|---|
| Sonant.AutoReverb | -1 | 0 | 1 | -1 = Use Project Setting, 0 = Force Disable, 1 = Force Enable. |
| Sonant.Debug | 0 | 1 | Toggles visual acoustic raycast lines and room telemetry overlay. |
| Sonant.VisualEffects | 0 | 1 | Global gate controlling whether Sonant spawns Niagara systems for events. |
| Sonant.Decals | 0 | 1 | Global gate controlling whether Sonant spawns surface impact decals. |
17. Production Recipes & Workflows
๐ Recipe 1: Integrating MetaSounds and Sound Cues
Assign your MetaSound or SoundCue asset soft reference directly to the Sound property in your USonantConfig asset under SurfaceTypeMap or KeywordMap. Sonant will load the asset asynchronously when the event is requested, or immediately if PreloadEvent() is invoked.
๐ Recipe 2: Setting up Niagara Surface Impact FX
In USonantConfig, set the VFX soft pointer in FSonantSound to your Niagara System (e.g. NS_GrassDust or NS_MetalSparks). Sonant automatically spawns the effect aligned with the surface impact normal, respecting MaxVisualEffectDistance (5000 units) and the Sonant.VisualEffects console variable.
๐ Recipe 3: Deferred Decal Material Projection
Assign a decal material to Decal in FSonantSound. Configure DecalSize (e.g., FVector(15, 15, 15)) and DecalLifeSpan (e.g., 10.0s). Sonant projects the decal onto the hit mesh, auto-destroying it after the lifespan expires while adhering to MaxDecalDistance (3000 units).
๐ Recipe 4: Creating AudioModulation Atmosphere Control Bus Mixes
1. Right click Content Browser > Audio > Modulation > Sound Control Bus Mix. Name it Mix_Cave.
2. In USonantConfig, map tag Sonant.Atmosphere.Cave to Mix_Cave with Priority 50.
3. Add a USonantVolume to your cave blueprint, set Atmosphere Tag to Sonant.Atmosphere.Cave. The mix activates on player entry and pops on exit.
18. C++ API Reference
PlayFootstep(const FVector& Location, const FHitResult& SurfaceHit)
Triggers footstep audio, Niagara FX, and decal materials at the target location resolved against the surface hit result.
PlaySoundAtLocation(FGameplayTag EventTag, const FVector& Location, const FHitResult& SurfaceHit, float VolumeMultiplier, float PitchMultiplier)
General-purpose tagged event router. Resolves surface properties and triggers mapped sounds with volume/pitch multipliers.
PlayImpact(const FVector& Location, float ImpactForce, const FHitResult& SurfaceHit)
Translates raw impact force into data-driven impact tiers, executing the corresponding light/heavy event.
PreloadEvent(FGameplayTag EventTag) / ReleasePreloadedAssets()
Asynchronously retains soft assets associated with an event tag to prevent hitches during gameplay.
PushAtmosphere(FGameplayTag Tag) / PopAtmosphere(FGameplayTag Tag)
Pushes or pops an authored atmospheric state onto the priority stack, updating active Control Bus Mixes.
19. Blueprint Integration Guide
Access Sonant from any Character, Animation Notify, or Weapon Blueprint:
20. Showcase & Demo Map Layout
The SonantDemo module includes interactive showcase actors (ASonantFeatureDemo, ASonantDemoCharacter, ASonantDemoGenerator, ASonantAutoShowcase, ASonantGodRayShowcase, ASonantSpectacle) allowing complete hands-on testing without custom audio assets.
5 keyword-matched platforms (Grass, Metal, Stone, Wood, Glass) to verify real-time surface detection.
Interactive target objects with Q/E keybindings for light (500) and heavy (3000) impulse collision testing.
Nested trigger volumes showcasing priority-based Control Bus Mix pushing, popping, and stack fallbacks.
Enclosed chambers of varying dimensions (Closet, Room, Hall, Cavern) testing automatic 2Hz acoustic estimation.
Demo Player Controls
| Key | Action | Description |
|---|---|---|
| 1 - 5 | Test Surface Types | Directly triggers surface test audio for Grass, Metal, Stone, Wood, Glass. |
| Q / E | Light / Heavy Impact | Spawns physics test projectiles with 500 N or 3000 N impulse. |
| Space | Jump / Footstep | Triggers jump event and land detection trace. |
| T | Print Telemetry | Displays active surface, atmosphere stack, and reverb telemetry on screen. |
| 0 | Toggle Auto-Demo | Cycles through showcase stations automatically. |
| 9 | Rebuild Environment | Destroys and recreates the showcase layout. |
21. Automation Suite & Release Gates
Sonant contains a pure C++ decision automation test suite validating all contextual logic without rendering or audio device dependencies.
// Execute pure decision tests in Unreal Editor Automation Window or CLI:
Automation RunTests Sonant.DecisionVerified Release Gates
- Open terrain classification and enclosed room estimation.
- Overhang rejection and ceiling-less confidence normalization.
- Deterministic keyword selection and unsorted impact tier interpolation.
- Surface-resolution precedence order enforcement.
- Network proximity/rate boundary checks and echo suppression verification.
- Configured asset schema migration safety.
22. Troubleshooting & Diagnostics
๐ Complete Silence on Event Call
Verify that AudioModulation is enabled in plugins, a SonantConfig asset is assigned in Project Settings, and Sonant->IsReady() returns true before firing event calls.
๐ต Incorrect Surface Sound Selected
Check if a physical material asset is assigned to the hit mesh. Soft physical-material overrides take precedence over material names and canonical maps. Clear surface cache using Sonant->InvalidateSurfaceCache() if materials were renamed during PIE.
๐ Server Audio Inaudible to Owner Pawn
Ensure your project build includes Sonant 0.4.5+ where multicast RPCs transmit bOwnerAlreadyPlayed to differentiate predicted local client sounds from server-initiated authority events.
23. Frequently Asked Questions
Does Sonant support MetaSounds and Sound Cues?
Yes. Sonant uses soft references to standard USoundBase objects, fully supporting MetaSounds, Sound Cues, and Sound Waves.
Can Sonant be packaged for mobile platforms?
Yes. The runtime Sonant module supports Win64, Mac, Linux, Android, and iOS.
Does auto-reverb require physical volumes?
No. Auto-reverb performs real-time raycasting around the listener camera position to dynamically infer room volume without requiring physical volume placement.