Get it on Fab

Sonant 1.0

Native Contextual Audio Middleware for Unreal Engine 5.7

Sonant 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.

🎯 Contextual Surfaces

Map GameplayTags (Walk, Run, Land) to specific materials. Supports Physical Materials, Material Instances, and Sub-Mesh detection with intelligent caching.

💥 Physics Audio

Automatically triggers impact sounds based on Mass and Velocity. Falls, collisions, and debris sound right instantly with automatic intensity detection.

🌊 Auto Reverb

Raycasts the environment in real-time (2Hz) to determine room size and apply the perfect Reverb Bus Mix dynamically without manual volume triggers.

🏔️ Atmosphere Zones

Push and pop atmospheric zones with priority-based mixing. Perfect for underwater sections, caves, forests, or any environmental audio transition.

⚡ High Performance

O(1) material lookup caching, optimized raycasting, and minimal overhead. Built for AAA production environments with profiling in mind.

🔧 Data-Driven

Configure everything through Data Assets. No code changes needed for new surface types, allowing sound designers to work independently.

Installation & Setup

Prerequisites: Unreal Engine 5.7+ and the AudioModulation plugin enabled in your project.
1 Install the Plugin

Copy the Sonant folder into your project's Plugins/ directory. Restart the editor if it was open.

2 Enable the Plugin

Navigate to Edit > Plugins > Audio > Sonant and check the enabled box. Restart the editor when prompted.

3 Create Configuration Asset

In the Content Browser, Right Click > Miscellaneous > Data Asset > Select SonantConfig. Name it something like DA_Sonant_Global.

4 Register Configuration

Open Project Settings > Plugins > Sonant Audio and assign your created config to the Main Config property.

5 Setup GameplayTags (Optional)

In Project Settings > GameplayTags, add default tags like Sonant.Event.Footstep, Sonant.Event.Impact.Light, and Sonant.Event.Impact.Heavy.

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:

3. Trigger from Blueprint

In your Character Blueprint, during the footstep animation notify:

Get Game Instance -> 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!

Pro Tip: Use the included ASonantDemoGenerator actor to quickly visualize and test your surface configurations in a generated test environment.

Generalized Surface System

Sonant 1.0 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.

Surface Hit (Grass) → Event Tag (Run) → Play: SFC_Grass_Run.wav

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.
Tip: Use Physical Materials for precise control. Add an entry to Physics Map and assign your Physical Material asset (e.g. PM_Metal). This overrides name-based detection.

Supported Material Types

Material Type Detection Method Use Case
Base Materials Name substring matching Prototyping, simple projects
Material Instances Parent material name Production environments
Physical Materials Direct asset reference Precise control, final shipping
Per-Face Materials Collision face index lookup Complex meshes with multiple surfaces

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:

Optimization: The physics system respects collision response settings. Ensure your meshes have appropriate collision profiles to avoid unnecessary audio calculations.

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

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.

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.

Raycast Up Raycast Down Raycast Left/Right Raycast Forward/Back

↓

Average Distance = 450cm → Apply: SmallRoom_Reverb

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:

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

Example Presets

Environment Max Room Radius Description
Outdoors/Open 5000 No reverb or minimal room tone
Large Hall 2000 Cathedrals, stadiums, large caves
Medium Room 800 Offices, apartments, corridors
Small Room 400 Bathrooms, closets, tight spaces
Performance: Reverb updates run at 2Hz on the game thread. The system caches results and only activates/deactivates mixes when necessary, minimizing AudioModulation overhead.

Performance Optimization

Material Cache

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.

Raycast Budget

The auto-reverb system uses a fixed budget:

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

Large Open Worlds

For very large open worlds, consider disabling auto-reverb outdoors and using manual atmosphere zones for specific landmarks. Use the UpdateReverb() function's source code as a reference for custom implementations.

High-Frequency Events

For rapid-fire events (machine gun impacts, fast footsteps), consider implementing cooldown timers in your Blueprints to avoid flooding the audio thread. Sonant handles the surface detection efficiently, but audio instantiation has inherent costs.

C++ API Reference

Access via USonantSubsystem (GameInstance Subsystem).

PlaySoundAtLocation(EventTag, Location, SurfaceHit, VolumeMultiplier, PitchMultiplier)

Generic audio event system. Use this for any custom event (Land, Jump, Scuff).

EventTag FGameplayTag - The event type (e.g., Sonant.Event.Footstep)
Location FVector - World position for 3D audio
SurfaceHit FHitResult - Trace result containing material info
VolumeMultiplier float - Additional volume scaling (default: 1.0)
PitchMultiplier float - Additional pitch scaling (default: 1.0)

PlayImpact(Location, ImpactForce, SurfaceHit)

Helper for collision events. Automatically selects Light/Heavy impact tags based on force.

Location FVector - Impact world position
ImpactForce float - Magnitude of impact (NormalImpulse.Size())
SurfaceHit FHitResult - Collision result

PlayFootstep(Location, SurfaceHit)

Convenience wrapper that calls PlaySoundAtLocation with Sonant.Event.Footstep tag.

PushAtmosphere(Tag)

Activates an atmosphere by tag. Increments reference count if already active.

PopAtmosphere(Tag)

Deactivates an atmosphere by tag. Decrements reference count; mix persists if count > 0.

Internal Methods

ResolveMaterial(Hit) → const FSonantSurfaceDef*

Core material resolution logic. Returns surface definition based on priority order (Physics → Cache → Keyword → Default).

Blueprint Guide

Accessing the Subsystem

All Sonant functions are available through the Game Instance Subsystem:

Get Game Instance
    -> 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 Game Instance → 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

🎯 Naming Conventions

Establish consistent material naming early. Use M_SurfaceType_Variant format (e.g., M_Grass_Dry, M_Metal_Rusted). This makes keyword matching reliable.

🔊 Audio Asset Organization

Organize sounds by surface type, not by character. Use folders like /Audio/Sonant/Surfaces/Grass/ containing Walk, Run, Land, Impact subfolders.

🧪 Testing Workflow

Use the included demo generators (ASonantDemoGenerator, ASonantAutoShowcase) to test surface configurations before implementing in your main level.

⚖️ Physics Material Strategy

Use Physical Materials for final polish on critical surfaces. Start with keyword matching for rapid prototyping, then refine with Physical Material overrides.

🔇 The Silence Threshold

The 50.0 force threshold for impacts exists for good reason—micro-collisions from physics jitter create noise. Don't lower this without careful testing.

Troubleshooting

🔇 No Sound Playing At All

Symptoms: Complete silence from Sonant functions.

  • Verify AudioModulation plugin is enabled in Project Settings
  • Check that a SonantConfig Data Asset exists and is assigned in Project Settings > Sonant Audio
  • Ensure the Subsystem is being accessed correctly: Get Game Instance -> Get Subsystem (Sonant Subsystem)
  • Check the Output Log for yellow warnings about missing config
  • Verify your Sound Cues are valid and not reporting errors

🎵 Wrong Sound Playing

Symptoms: Footsteps sound like a different material.

  • Check if a Physical Material is assigned to the mesh—Physics Map overrides Keyword Map
  • Verify your material name contains the keyword (case-sensitive in some engine versions)
  • Check if the mesh has proper collision data for sub-material detection
  • Clear the material cache (restart PIE) if you've changed material names
  • Verify the default surface isn't being used (add logging or check in debugger)

🌊 Reverb Not Changing

Symptoms: Reverb stays the same regardless of room size.

  • Ensure your Sound Control Bus Mix is correctly configured with a Reverb Submix Effect
  • Verify the AudioModulation plugin is enabled
  • Check that Reverb Settings array in SonantConfig has entries
  • Ensure collision exists on Visibility channel for raycasts to hit
  • Check the Max Room Radius values—larger rooms must have larger values
  • Verify the player pawn is valid and has a controller

💥 No Audio on Impact

Symptoms: Physics collisions make no sound.

  • Enable Simulation Generates Hit Events on the mesh component
  • Verify the impact force exceeds 50.0 (add Print String to check Normal Impulse size)
  • Check that collision is properly set up (not just overlap)
  • Ensure the hit surface has a valid material assigned
  • For destructible meshes, check that impact data is being passed correctly

🏔️ Atmosphere Not Applying

Symptoms: Entering zones doesn't change the audio mix.

  • Verify the Atmosphere Tag matches an entry in SonantConfig's Atmospheres map
  • Check that the SonantVolume component is actually overlapping the player
  • Ensure the priority is set correctly (higher number = higher priority)
  • Verify the Sound Control Bus Mix asset is valid and activatable
  • Check if multiple overlapping zones are conflicting (check ActiveAtmosphereCounts in debugger)

🐌 Performance Issues

Symptoms: Frame drops when using Sonant.

  • Check for excessive raycasts—disable auto-reverb if using many manual zones
  • Profile with stat game to see if UpdateReverb is expensive
  • Reduce the frequency of footstep events (don't call every frame)
  • Ensure material cache isn't growing unbounded (should stabilize after initial area exploration)
  • Check for redundant subsystem calls in Blueprints

🎨 Material Not Detected

Symptoms: Default sound plays for custom materials.

  • Verify the material instance's PARENT name contains the keyword (not just the instance name)
  • For complex meshes, ensure collision face index is being read (requires detailed collision)
  • Check that the material is actually applied to the rendered mesh, not just a duplicate
  • Verify the Static Mesh has "Use Complex Collision As Simple" disabled for face-index detection
  • Use show collision console command to visualize traces

✅ Debug Checklist

If you're still stuck, verify these in order:

  1. Plugin enabled and editor restarted
  2. SonantConfig asset created and assigned
  3. GameplayTags registered (if using custom tags)
  4. Sound Cues valid and audible
  5. Trace channels hitting correct collision
  6. Subsystem accessible from your Blueprint
  7. No errors in Output Log related to Sonant

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

Sonant includes a comprehensive demo system that showcases all features without requiring custom audio assets.

No .Wav Files Needed! The demo uses Unreal Engine's built-in sounds as placeholders. You can add your own audio later.

Demo Components

Surface Showcase

5 platform types (Grass, Metal, Stone, Wood, Glass) with color-coded materials and automatic surface detection.

Impact Range

Physics projectiles demonstrating light, medium, and heavy impact detection with force-based scaling.

Atmosphere Zones

3 interactive zones (Outdoor, Cave, Underwater) showcasing priority-based atmosphere mixing.

Reverb Rooms

4 rooms of increasing size (Closet, Room, Hall, Cavern) demonstrating auto-reverb detection.

Quick Setup (5 Minutes)

1 Enable Plugin

Copy Sonant folder to Plugins/, enable in Edit > Plugins, restart.

2 Create Config

Right-click > Miscellaneous > Data Asset > SonantConfig. Name it DA_Sonant_Demo.

3 Configure Surfaces

Add 5 Keyword Map entries: Grass, Metal, Stone, Wood, Glass. Point each to engine notification sounds.

4 Register Config

Project Settings > Sonant Audio > Main Config = DA_Sonant_Demo.

5 Run Demo

Drag ASonantFeatureDemo into level, assign basic shapes, press Play!

Demo Controls

Key Action Result
1-5 Test Surface Play footstep sound for specific surface
Q Light Impact Spawn low-force projectile
E Heavy Impact Spawn high-force projectile
R Cycle Surface Test next surface type
T Print Info Debug current surface detection

Adding Your Own Audio

Once the demo works with placeholder sounds:

  1. Import your .wav files to /Game/Audio/Sonant/
  2. Create Sound Cues with Random nodes for variation
  3. Update DA_Sonant_Demo to reference your Sound Cues
  4. Fine-tune Volume and Pitch Randomization per surface

Free Audio Resources

See QuickStart_Demo.md and DemoSetupGuide.md in the Resources/Docs folder for complete setup instructions.