Version

menu_open
Wwise Unreal Integration Documentation
Spatial Audio Blueprint Components

So far, we have built everything directly in our level, using prebuilt actors or adding components to individual actor instances. It's also possible to use the various spatial audio components to construct a Blueprint actor that can be replicated throughout the level. In this section we will build a replica of the structure from section Unreal Project Preparation, using a Blueprint class so that it can be easily added or spawned throughout the world.

Note:
The Preparation for the Spatial Audio Tutorials must be completed prior to starting this tutorial.

Setting Up a Blueprint Class

AkLateReverbComponent and AkRoomComponent rely on containment tests to check whether a given game object position lies within their parent PrimitiveComponent. Simple collision is used for this check. You should therefore use a parent PrimitiveComponent that has simple collision. For example, you could use a box collision, sphere collision, or capsule collision component. If the PrimitiveComponent has no simple collision, the containment test will simply use the component bounds, which may be less accurate.

It is also possible to add simple collision to a mesh asset in Unreal (see Setting Up Collisions With Static Meshes). However, for complex meshes, such as those with doorways and openings, it is sometimes necessary to 'use complex collision as simple' in the collision settings for the mesh (see Simple versus Complex Collision). For example, this setting might be required to allow a character to enter a room through a doorway but still collide with the walls. When this setting is used, the containment tests for AkLateReverbComponent and AkRoomComponent will fail, as the simple collision will be ignored, and the mesh's full trimesh will be used. The simple collision tests used by AkLateReverbComponent and AkRoomComponent do not support trimeshes. For that reason, the recommended setup in a Blueprint class is to have a simple collision component as the parent when using AkLateReverbComponent component and AkRoomComponent. For example, the simple collision component could be a box, sphere, or capsule. If you have a specific mesh for a room or building, the simple collision component(s) could be added to the mesh as a child component(s).

Note:
  • It is possible to combine complex collision with simple collision by using two versions of the mesh. See Combining Simple and Complex Collision for an explanation on how this can be achieved.
  • We will use assets from the Unreal Demo Game available from the Wwise Launcher. To use these assets in your project, download the Unreal Demo Game and locate the wanted assets in the explorer under $<YourWwiseProjectsFolder>/WwiseDemoGame/Content. Then copy and paste the desired assets to the Content folder of your working project.
  1. In the content browser, right-click and select Blueprint Class.
  2. Select Actor as the base class, and call the new class 'SpatialAudioBP'.
  3. Double-click SpatialAudioBP to open the class, and click on the Viewport tab.
  4. Ensure the root component is selected and click Add Component > Static Mesh.
  5. Click on the new static mesh component and select the mesh in the Details panel.

    • In this example, the SpatialAudioDemoMesh used in section Unreal Project Preparation is selected.
    • If you use the SpatialAudioDemoMesh, you need to select SpatialAudioDemoMeshMaterial in the Materials section.
    Set the Mesh and Material of the Static Mesh Component
    Note:
    Automatic assignment of rooms to portals only works for convex meshes. Concave meshes (for example, L-shaped rooms) do not produce accurate portal room intersection.
  6. Add a Box Collision component for each of the individual rooms and doorways in the mesh. Name them BoxRoomLarge, BoxRoomSmall, BoxPortalInner, and BoxPortalOuter.

Repositioning Box Collision Components

At this point, all of the box collision components are positioned in the same place; on top of each other. We'll reposition, scale, and rotate them so that they align with the rooms and doorways. The easiest way to do this is to use the Orthographic view. (The following steps are specific to the SpatialAudioDemoMesh, but similar steps can be performed for other meshes.)

Note:
When aligning rooms and portals to the mesh in this tutorial, don't worry if they're not perfectly aligned or centered. Just be sure to roughly cover the correct areas. When designing a real environment, you can use the Transform section of the Details panel to input exact values.
  1. In the Viewport tab, click Perspective and change the view to Top.

    • You are now looking down on the scene from above and it's rendered using wireframe.
    Orthographic Top View
  2. Select BoxRoomLarge and move it down along the y-axis until it's in the middle of the large room in the mesh.
  3. Scale BoxRoomLarge along the x and y axes until its size matches the dimensions of the large room. (You can switch to scale by pressing R or selecting the Scale widget in the Viewport tab).

    Position and Scale Large Room on X and Y Axes
  4. Select BoxRoomSmall and scale it along the x and y axes until its size matches the dimensions of the small room.

    Position and Scale Rooms on X and Y Axes
  5. Select BoxPortalInner and zoom in on the wireframe until you see the extents of the inner doorway on the mesh.

    Locate Extents of the Doorway on the Wireframe Mesh
  6. Move BoxPortalInner to the middle of the doorway and then scale it along the x-axis such that it covers the extent of the doorway.

    Position and Scale Inner Portal Box to Cover the Doorway
  7. Select BoxPortalOuter and rotate it so that its local y dimension is pointing out of the doorway.

    Note:
    This is necessary because portals have front rooms and back rooms which are automatically assigned by detecting the closest intersecting room along the portal's y dimension. In the case of the BoxPortalOuter, the 'back' (in local coordinate space) will be connected to the small room in our mesh, and the 'front' will not be connected to any room.
  8. Rotate BoxPortalOuter around the z-axis by 90 degrees. This can be achieved by typing '90' into the z-axis Rotation text box in the Transform section of the Details panel.

    Rotate Outer Portal Box to Point its Local Y-Axis Out of the Door
  9. Move the BoxPortalOuter over the outer doorway and scale it so that it covers the extent of the door.
  10. In the top view, ensure all rooms and portals are aligned with the mesh, as shown:

    Rooms and Portals Correctly Aligned in Top View
  11. You now need to reposition and scale the box collision components on the z-axis. In the Viewport tab, click Top and change the view to Back.
  12. Select BoxRoomLarge and BoxRoomSmall and scale both along the z-axis so that they match the dimensions of the room.

    Scale Room Boxes on Z-Axis
  13. Select BoxPortalOuter and BoxPortalInner and move them down to the center of the doorways, then scale them along the z-axis so they match the dimensions of the doors.

    Position and Scale Portal Boxes on Z-Axis

Setting Up Rooms and Portals

We will now add AkRoom components to the rooms, and AkPortal components to the portals.

  1. One by one, select each of the box collision components and then select Add Component.
  2. For each box collision component, create a room or portal component (as appropriate) with a name similar to the parent. The result should be as shown:

    Add AkRoom Components to the Room Boxes and AkPortal Components to the Portal Boxes

    Note:
    Be sure to add the components to the correct parent. For example, when adding AkRoomLarge to the large room, make sure BoxRoomLarge is selected before clicking Add Component.

    AkRoomComponent and AkPortalComponent are generic components that can be added to any primitive component. See AkRoomComponent and AkPortalComponent for more information.

  3. To confirm that the portals have valid placement, select the Visualize Rooms and Portals option in the Wwise User Settings.

    Visualize Rooms and Portals option in the Wwise User Settings
  4. Lines are now drawn between connected rooms and portals. If portals have invalid placement, they will be visualized in red.

    Portal Room Connections Visualized in the Viewport
    Note:
    A portal has invalid placement if it is not connected to any room, or if the same room is connected to both sides. See AkPortalComponent for further information.
  5. Clear Visualize Rooms and Portals in the Wwise User Settings.

Adding Geometry and Late Reverb

The last two items to add to the Blueprint class are AkGeometry and AkLateReverb components.

  1. Add an AkGeometry component to the static mesh component.
  2. Select the AkGeometry component and in the Details panel, under Geometry, set the Mesh Type to Static Mesh.
  3. Add an AkLateReverb component to the BoxRoomLarge box collision component.

    AkGeometry and AkLateReverb Added to the Blueprint Class
  4. Select the AkLateReverb component.
  5. In the Details panel, set the Aux Bus to LargeRoom.

Verifying your Setup

The Blueprint class is now ready to use. We can drag an instance of the class into the world.

  1. Drag an instance of SpatialAudioBP from the content browser into the spatial audio demo map.
  2. Position it beside the existing building.

    An instance of the Blueprint Class Added to the World
  3. Remote connect Wwise, and play in editor.
  4. Click the mouse to play the outside sound.
  5. In the Game Object Profiler layout in Wwise, confirm that the geometry of the new Blueprint class is correctly registered, and that rays reflect correctly from this geometry.
  6. Confirm that rays pass through the portals correctly in the new Blueprint structure.

    Spatial Audio Paths Correctly Interacting with the New Blueprint Class Instance
  7. To test the late reverb component, you must add a sound and position it within the large room in our SpatialAudioBP instance. Right-click on the existing Play_Outside AkAmbientSound actor in the world and duplicate it.
  8. Rename the duplicate to 'Play_LargeRoom_BP'. (You could also detach Play_LargeRoom_BP from Button_Outside in the World Outliner hierarchy, by dragging Play_LargeRoom_BP on top of Button_Outside.)
  9. Move Play_LargeRoom_BP inside the large room of the SpatialAudioBP instance.
  10. Open the Level Blueprint and add logic to play the Play_LargeRoom_BP sound when the B key is pressed (see Unreal Project Preparation).

    Logic in the Level Blueprint to Play the New Sound Using the B Key
  11. Compile and save the Level Blueprint.
  12. Play the level in the editor.
  13. Press B to play the new sound.
  14. Walk into the large room in the SpatialAudioBP building. You can hear the reverb applied to the sound.

Combining Simple and Complex Collision

This section shows how simple collision and complex collision can be combined for the same mesh, such that Spatial Audio containment tests are performed using the simple collision, and Unreal queries make use of the complex collision.

Note:
This section is based on the 'SpatialAudioTutorialMap' and the assets found in the ComplexRoomDemo directory in the WwiseDemoGame project, which is available from the Audiokinetic Launcher. The pre-made mesh assets and a custom Blueprint class are used to combine simple collision and complex collision.

For complex meshes, such as those with doorways and openings, it is sometimes necessary to 'use complex collision as simple' in the collision settings for the mesh (refer to Simple versus Complex Collision). For example, this setting might be required to allow a character to enter a room through a doorway but still collide with the walls. When this setting is used, the containment tests for AkLateReverbComponent and AkRoomComponent fail because the simple collision is ignored and the mesh's full trimesh is used. The simple collision tests used by AkLateReverbComponent and AkRoomComponent do not support trimeshes.

One solution to this problem is to create two duplicates of the same mesh asset, using simple collision for one, and complex collision for the other. In the SpatialAudioTutorialMap, there is a complex room structure that demonstrates this technique.

To begin, test the complex room structure by playing in editor and walking around the building:

  1. Open the SpatialAudioTutorialMap in Unreal.
  2. Click Play in Editor.
  3. Press C to trigger the sound in the non-box-shaped building.
    The Non-Box-Shaped Room in the SpatialAudioTutorialMap
    Walk around the exterior of the building. The sound is occluded.

The rest of this tutorial demonstrates how the building structure is configured to handle simple collision for Wwise Spatial Audio containment tests, as well as complex collision for Unreal physics containment tests.

  1. In the context browser, browse to WwiseAssets/SpatialAudioDemo/ComplexRoomDemo.

    The ComplexRoomDemo Assets in the SpatialAudioTutorialMap

    This folder contains two Static Mesh assets: Building_Complex and Building_Simple.

  2. Open each of these assets and scroll to the collision settings in the Details Panel.

    Notice that they have different values for their respective Collision Complexity properties.

The Building_Complex mesh asset
The Building_Simple mesh asset

Building_Complex has Collision Complexity set to 'Use Complex Collision As Simple' which means Unreal will not generate any simplified geometry for this mesh, and will instead use the entire trimesh. This is what allows the character to walk through the doorway opening. Building_Simple has Collision Complexity set to 'Use Simple Collision As Complex' which means Unreal will generate simplified geometry and ignore the trimesh. This is what allows Spatial Audio to perform containment tests for room containment.

Note:
It is possible to set Collision Complexity to 'Simple And Complex'. However, this causes Unreal to use the simplified geometry for collision queries, which means the character cannot enter through the doorway opening. Instead, two identical meshes can be used - one with complex geometry and one with simple geometry.

The next step is to combine both meshes inside a custom Blueprint class.

  • Open the BuildingBP Blueprint.

This Blueprint uses two Static Mesh Components that are positioned right on top of one another.

Static Mesh Components in the BuildingBP Blueprint
For the StaticMesh_Complex component, the Building_Complex mesh is used
For the StaticMesh_Simple component, the Building_Simple mesh is used
StaticMesh_Simple Rendering Settings

For the StaticMesh_Simple component, 'Visible' is disabled and 'Hidden in Game' is enabled in the Rendering section. This is because this mesh is only used for its simplified geometry, so that containment tests can be made for Spatial Audio.

StaticMesh_Simple Collision Presets Settings

Also for the StaticMesh_Simple component, the Collision Presets property is set to 'Trigger'. The simplified geometry creates a barrier at the doorway opening. Using the 'Trigger' collision preset ensures the character and other game objects can freely move through the simplified geometry.

The StaticMesh_Simple Component has an AkRoom component and an AkLateReverb Component attached. This way, the simple collision of the Building_Simple mesh is used for room containment tests.

To allow for sounds to reflect and diffract on the BuildingBP's mesh, an AkGeometry Component needs to be added to one of the Static Mesh Components. In this solution, because we are also using Reverb Parameter Estimation, it is best to add it to the StaticMesh_Simple component. The AkLateReverb Component uses the Acoustic Textures of its sibling AkGeometry Component to calculate HF Damping. Setting the AkGeometry Component to Static Mesh sends the full complex geometry to Wwise Spatial Audio instead of its simple collision mesh.

Finally, a Box Collision Component with an AkPortal Component attached is used to add an acoustic portal to the doorway.

Portal in the BuildingBP Blueprint

A Point Light is also added to make the interior of the building visible.

Note:
  • When sending geometry to Wwise, there is a limitation that each edge can have no more than two triangles connected. Remember this when designing meshes to use with Spatial Audio.
  • When using the Game Object Profiler in Wwise, Room Extents will always be visualized as green cuboids, regardless of the geometry assigned to the room.
  • Adding simple collision to meshes in Unreal will only work correctly when the mesh is convex. For more complex mesh structures, it is best to try to approximate the mesh using simple collision geometry. Simple collision primitives can be added to the mesh from the Collision menu in the Static Mesh editor.
    Adding Collision Primitives to a Mesh Asset
    Refer to Setting Up Collisions With Static Meshes for further information.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise