User Guide (Version 1.13)

Obstructing and Occluding Sounds

This topic references tools and features that are legacy. If you want to use legacy tools in Lumberyard Editor, disable the CryEntity Removal gem using the Project Configurator or the command line. To learn more about legacy features, see the Amazon Lumberyard Legacy Reference.

Sound obstruction means that the direct path to the audio is blocked but the sound might still be audible due to the sound reflecting off the obstruction and other objects. Sound occlusion, on the other hand, refers to the degree to which sound is lost or affected by intervening objects. You can enable different obstruction and occlusion settings for the AudioTriggerSpot, AudioAreaEntity, and AudioAreaAmbience object types. Using these settings correctly helps you to create a game world where sound is realistically filtered and attenuated according to the surrounding environments.

You can set the SoundObstructionType property for the AudioTriggerSpot, AudioAreaEntity, and AudioAreaAmbience in their respective properties panels in the Rollup Bar. All audio object types default to Ignore as their SoundObstructionType setting.

Obstructing Sounds

Lumberyard uses raycasting, or ray-to-surface intersection testing, to get information about the objects with which the line intersects. If the occlusion value of a raycast's center ray differs from the average of the occlusion values of the outer rays from the same raycast, Lumberyard applies obstruction to the sound source. Therefore, obstuction is calculated only when the SoundObstructionType is set to MultipleRays on the object type, since a single ray does not provide enough information to differentiate between obstruction and occlusion.

Obstruction is applied to the sound after occlusion and in addition to it. If the center ray of a raycast has reached the listener without being blocked, and the outer rays are fully or partially blocked by game objects, then the obstruction value is set to zero and only the occlusion value is positive. In addition, obstruction is only applied to the dry signal; it has no effect on the signal sent to the environment auxiliary buses.

Obstruction is also affected by the distance of the raycasting entity to the listener. As the distance increases, the obstruction value decreases and the difference is transferred to the occlusion value. This reflects the fact that, with increasing distance, the contribution of the direct line-of-sight sound path in the overall sound perception becomes progressively smaller.

The console variable s_FullObstructionMaxDistance sets the maximum distance after which the obstruction value starts to decrease with distance. For example, s_FullObstructionMaxDistance = 5 means that, for the sources that are farther than 5 meters away from the listener, the obstruction value is lower than the actual value calculated from the raycast. In this case, an object 10 meters away has half the obstruction value of the similarly obstructed source located 5 meters away.

Sound Obstruction for Surface Types

You can define how much each different material type affects the sound passing through it. The sound_obstruction physics property is a value between 0 and 1. For each raycast from a sound source, the ray's occlusion value increases by the sound_obstruction value of each surface it intersects.

Values for each surface type can be set in the \Libs\MaterialEffects\SurfaceTypes.xml file. The exact effect that this value has on the audio content of your game is defined in your specific audio middleware.

For a material with sound_obstruction = 0.5, the maximum obstruction and occlusion value that is reached in the game is 0.5. Therefore, if the sound is fully occluded by one object with this surface type, the occlusion value passed to the middleware is 0.5. If the sound is also obstructed, the combined values of obstruction and occlusion would be summed to 0.5. However, their sum would never exceed this value, as it is defined as the maximum obstruction or occlusion value in the material's sound_obstruction property.

Occluding Sounds

Occlusion is applied to a sound source that is completely or partially hidden from the listener by the other game object(s).

A nonzero occlusion value is set for a sound source whenever at least one ray that is cast from that source encounters a surface with non-zero sound_obstruction value. The sound_obstruction values from the surfaces struck by the ray are accumulated, and the total values are averaged over time for each ray to produce this ray's occlusion value, as shown in the ray label enabled with s_DrawAudioDebug h flag. With the SingleRay selected for SoundObstructionType, the audio object occlusion value is equal to its only ray's occlusion value. With MultipleRays selected for SoundObstructionType, the audio object occlusion value is the average of the occlusion values for all the rays.

You can use the console variable command s_OcclusionMaxDistance to set a maximum distance beyond which the sound obstruction and occlusion calculations are disabled. For example, for s_OcclusionMaxDistance = 150, Lumberyard calculates the obstruction and occlusion values for every active audio object with SoundObstructionType set to SingleRay or MultipleRays, providing they are located within 150 meters of the sound's listener.


When Lumberyard performs a raycast, it calculates the occlusion and obstruction values either synchronously or asynchronously. In synchronous calculations, all occlusions of an individual ray are available immediately in the same frame as the one that requested the raycast. In asynchronous calculations, the individual ray data is received over the next few frames and processed once all of the rays have reported back. Synchronous raycasts are much more responsive, but they also require more processing resources and can hurt performance if a large number of raycasts are performed in a single frame. In order to save resources and avoid performance hits, Lumberyard switches between synchronous and asynchronous raycasts based on the distance between the sound source and the listener. For the sources close to the listener, Lumberyard uses synchronous raycasts to provide a maximum responsive environment. For sources further away, asynchronous raycasts are used.

Debugging Raycasts

The s_DrawAudioDebug console variable has three flags that show you the values calculated by the raycasts:

  • b – Shows text labels for active audio objects, including obstruction (Obst) and occlusion (Occl) value.

  • g – Draws occlusion rays.

  • h – Shows occlusion ray labels.