Troubleshooting Acoustic Ray Tracing for Unreal

The following are some known issues and how to troubleshoot them.

The Meta XR Audio Room Acoustic Properties component affects only “Shoebox room” mode. Shoebox Room is the basic reverb that is used as a fallback when no geometry has been loaded or if you select Shoebox Room as the Acoustic Model in the Meta XR Acoustic Project Settings.

Add an acoustic map point around the boundary between the two spaces to smooth the change.

Add points or additional surfaces around the area. This issue can be the result of raytracing having nothing to reflect upon during baking.

Meta XR Acoustic components do not work in the blueprint editor because the editor decouples the component from everything. The components do still work in the regular details pane, you just can’t adjust the settings or activate the proper behavior from the blueprint editor. This is because the plugin is prebaked and doesn’t support real time changes. The one exception is that Meta XR Acoustic Control Zone can be controlled in real time.

Check that your .xrageo and .xramap files are up to date. Likely the files are stale and rebaking them will resolve this issue.

Check that there is no scale being applied to your map. If there is, an error will be generated in the output log. Acoustic Maps do not support being scaled.

The most common cause for this is that the .xrageo and .xramap files didn’t get included in the built APK. See “Why is my built APK missing the .xrageo and .xramap files?”.

The Meta XR Audio visualizers are useful for validating you work while setting up a project. However, during runtime or for non-audio teams working on the game, it may be preferred to not see these visualizers. To do so navigate to the Show button in the editor and enable or disable whichever Meta XR components you’d like.

Due to Unreal’s plugin setup, stereo sounds do not get processed by the spatializer plugin. Make sure to use only mono sources when the intention is to be processed by Acoustics.

Unreal requires you to add special instructions to copy non-Asset files from the Content directory to the final APK. By default the SDK will save all the baked files to a “MetaXRAcoustics” sub folder within the Content directory. The following code is based on using this default. If you save your files elsewhere, adjust these lines to account for your alternate path. Unreal can be told which additional folders to package by adding the following lines to Config > DefaultGame.ini

+DirectoriesToAlwaysCook=(Path="/Game/MetaXRAcoustics")
+DirectoriesToAlwaysStageAsUFS=(Path="MetaXRAcoustics")

Wwise may have line-of-sight occlusion enabled automatically. This should be disabled while using Meta XR Acoustics. To do so, go to Unreal Engine Project Settings and set Obstruction Occlusion > Refresh Interval to 0.0.

When using Perforce for your Unreal engine project version control, there is a chance that the baked audio files (.xramap/.xrageo) will not load correctly. Perforce has a system for defining the asset types of the files you are tracking. The 2 primary asset types are Text and Binary. Baked maps and baked geometry files (.xramap/.xrageo) are Binary files.

Note: When you track these files, make sure the asset type is marked binary.

Due to .xramap/.xrageo files being non-standard file formats, Perforce can mark these files as Text. If this happens, perforce can store these files on the perforce server incorrectly. This can result in the components failing to load these files. Review the perforce documentation for more information: https://help.perforce.com/helix-core/quickstart/current/Content/quickstart/admin-create-typemap.html⁠

You can manually change the asset type with the perforce CLI or UI. However, it is usually best to use a typemap so the asset type is properly marked in an automated way.

While developing your project, you may want to set defaults for the Console Variables (CVars) that are used to visualize the various audio object gizmos (such as Acoustic Geometry and Acoustic Map). Below are two different methods for saving defaults for your CVar’s.

Editing DefaultEditor.ini:

You can add your console variable defaults in {PROJECT_PATH}/Config/DefaultEditor.ini.

[ConsoleVariables]
MetaXRAudioGizmos=1
MetaXRAudioGizmos.Shoeboxes=1
MetaXRAudioGizmos.Geometries.EditorTime=1
MetaXRAudioGizmos.Geometries.EditorPlaymode=1
MetaXRAudioGizmos.Maps=1
MetaXRAudioGizmos.ControlZones=1

Edit DefaultEditor.ini because the above CVar’s are editor-only. However, you can do the same thing with other CVar’s that run in builds by editing DefaultEngine.ini. This method is best when you want to track CVar’s in version control.

If you prefer this to be developer specific (not tracked in version control) then you add the same console variable snippet above in file: {PROJECT_PATH}/Saved/Config/WindowsEditor/Editor.ini

NOTE: if you delete the saved folder then your defaults will be lost.

The above 2 methods are not the only way to save CVar defaults. This is not meant to be a comprehensive guide to CVar’s.

Review specific details about each component related to Acoustic Ray Tracing below: