使用 Wwise Unity 集成

该集成提供了一些组件，这些组件可以直接满足最常见的应用场景下的使用需求，而不需要编程。

• AkAmbient
  Use this component to attach a Wwise Event to any object in a scene. The sound can be started at various moments, dependent on the selected Unity trigger. This component is more useful for ambient sounds (sounds related to scene-bound objects) but could also be used for other purposes. Since AkAmbient has AkEvent as its base class, it features the play/stop, play multiple, stop multiple and stop all buttons for previewing the associated Wwise event. . 请参阅 如何与 inspector 一起使用 AkAmbient 。
  
• AkAudioListener
  Add this script on the game object that represent a listener. This is normally added to the Camera object or the Player object, but can be added to any game object when implementing 3D busses. isDefaultListener determines whether the game object will be considered a default listener - a listener that automatically listens to all game objects that do not have listeners attached to their AkGameObjListenerList's.
  
• AkBank
  Loads and unloads a SoundBank at a specified moment. Vorbis sounds can be decompressed at a specified moment using the decode compressed data option. In that case, the SoundBank will be prepared.
  
• AkEmitterObstructionOcclusion
  Obstructs/Occludes the emitter of the current game object from its listeners if at least one object is between them.
• AkEnvironment
  Use this component to define a reverb zone. This needs to be added to a collider object to work properly. 如何通过 inspector来使用 AkEvironment 和 AkEvironmentPortal（混响区域）.
  
• AkEnvironmentPortal
  Use this component to define an area that straddles two different AkEnvironment's zones and allow mixing between both zones. 如何通过 inspector来使用 AkEvironment 和 AkEvironmentPortal（混响区域）.
  
• AkEvent
  辅助类知道一个 Wwise 事件，以及何时在 Unity 中触发它。请参阅 如何与 inspector 一起使用 AkAmbient 。
  
• AkGameObj
  This component represents a sound object in your scene tracking its position and other game syncs such as Switches, RTPC and environment values. You can add this to any object that will emit sound, and it will be added to any object that an AkAudioListener is attached to. Note that if it is not present, Wwise will add it automatically, with the default values, to any Unity Game Object that is passed to Wwise.
  
• AkRoom
  An AkRoom is an enclosed environment that can only communicate to the outside/other rooms with AkRoomPortals.
  
• AkRoomPortal
  Loads and unloads a SoundBank at a specified moment. Vorbis sounds can be decompressed at a specified moment using the decode compressed data option. In that case, the SoundBank will be prepared.
  
• AkEmitterObstructionOcclusion
  Obstructs/Occludes the spatial audio portal of the current game object from the spatial audio listener if at least one object is between them.
  
• AkSpatialAudioEmitter
  Add this script on the GameObject which represents an emitter that uses the Spatial Audio API.
  
• AkSpatialAudioListener
  Add this script on the game object that represent a listener. This is normally added to the Camera object or the Player object, but can be added to any game object when implementing 3D busses. isDefaultListener determines whether the game object will be considered a default listener - a listener that automatically listens to all game objects that do not have listeners attached to their AkGameObjListenerList's.
  
• AkState
  This will call AkSoundEngine.SetState() whenever the selected Unity event is triggered. For example this component could be set on a Unity collider to trigger when an object enters it.
  
• AkSurfaceReflector
  This component will convert the triangles of the GameObject's geometry into sound reflective surfaces.
  
• AkSwitch
  This will call AkSoundEngine.SetSwitch() whenever the selected Unity event is triggered. For example this component could be set on a Unity collider to trigger when an object enters it.
  

参见:

Wwise Picker

这个集成还提供了一些类，适用于常见场景以外的大多数应用场景，需要极少量的编程：

• AK.Wwise.AuxBus
  This type represents an auxiliary send in the Master-Mixer Hierarchy.
  
• AK.Wwise.Bank
  This type can be used to load/unload SoundBanks.
  
• AK.Wwise.CallbackFlags
  This type represents the values of the flags used when posting an Event with a callback.
  
• AK.Wwise.Event
  This type can be used to post Events to the sound engine.
  
• AK.Wwise.RTPC
  This type can be used to set game parameter values to the sound engine.
  
• AK.Wwise.State
  This type can be used to set Wwise States.
  
• AK.Wwise.Switch
  This type can be used to set Switch values on gameobjects.
  
• AK.Wwise.Trigger
  This type can be used to post triggers to the sound engine.
  

参见:

Wwise Types

如何将 Wwise 声音添加到游戏对象上

共有四种方法可以将声音添加到您的游戏中：

• 使用 Wwise Picker.在所有将声音添加到一个对象的方法中，该方法是最简单的。将一个 Event 从 Wwise Picker 窗口拖动到 Unity Viewer 或者 Inspector 中的一个对象上。这样将自动在目标 Game Object 上创建一个 AkAmbient 组件。
• 使用 Add Component 菜单。 将 AkAmbient 或者 AkEvent 组件添加到任意 Unity Game Object 上。
• 使用 Wwise Types。 从 C# 脚本中随时调用 AK.Wwise.Event.Post()。
• 使用脚本。 从 C# 脚本中随时调用 AkSoundEngine.PostEvent()。

如何与 inspector 一起使用 AkAmbient

• AkAmbient:
  
  • Trigger On（触发时机为）：
    提供一张 Unity 事件列表，这些 Unity 事件可以触发您的 Wwise 事件。您可以使用的不止这些事件。您可以随时触发事件，方法是在代码的任何位置调用 AkSoundEngine.PostEvent。您也可以自己编写触发器代码，这样您的触发器会出现在您同事可使用的列表中。请参阅 为 Wwise Events 添加新的 Trigger。 。
  • Event Name（事件名称）:
    指定当前 Wwise 事件的名字。如果要选中一个事件，点击当前事件的名字，以打开事件选择窗口。接下来，您可以点击某个事件然后点击 Ok 按钮，也可以双击事件来选中它。您也可以从 Wwise picker 中拖动一个事件，然后在当前事件的名字上松手，这样也可以选中一个新事件。
    
  • Action On Event（定义事件动作）：
    允许用户从 Unity 中直接覆盖在 Wwise 中定义的一些事件参数。这样可以复用现有事件，而不用创建新的事件。
    
    • Action On Event Type（事件动作类型）：
      不沿用事件类型。
    • Curve Interpolation（曲线插值）:
      不沿用插值曲线。
    • Fade Time（淡变时间）:
      不沿用声音的淡变时间。
  • Use Callback（使用回调）:
    提供一种简单的方法使游戏对象对事件回调作出反应。
    • Game Object：
      会接受回调的游戏对象。如果要选中一个游戏对象，将它从层级结构中拖放到游戏对象区域。
    • Callback Function（回调函数）:
      这个函数即是在回调发生时会被 Game Object 调用的函数。为了选中这个函数，要在 Callback Function 的文本字段中输入它的名字。
      为了起效果，Game Object 必须在它的一个组件中定义 Callback Function。
      函数的定义必须是 void FunctionName(AkEventCallbackMsg in_info)。
    • Callback Flags（回调标志）:
      选中一个标志，其中该标志指明了 Callback Function 在什么时候会被调用。可以一次选中多个标志。如果想了解各个标志的更多信息，请参阅 Wwise SDK 文档 中的 AkCallbackType 枚举量。
  • Play / Stop:
    可用于在 Edit 模式下预览 Wwise 事件。
  • Stop All:
    停止当前播放的所有 Wwise 事件。
  • Position Type（定位类型）：
    定义事件的位置将被发送到音频引擎的方式。
    • Simple_Mode（简单模式）：
      事件的位置将与它依附的游戏对象相同。
    • Large_Mode（大型模式）：
      事件可以有多个位置，这些位置由一组点来定义。您可以通过点击 Add 按钮在AkAmbient Tool Bar 中添加一个点。接下来您可以通过四处拖动点的方式来移动各个点。当声音同时来自多个位置时，这种模式是很有用的。海洋中水的声音就是一个很好的例子。
    • MultiPosition_Mode（多重定位模式）：
      这种模式使我们能够对使用同一个事件的所有 AkAmbient 的实例，只使用某个声音的一个实例，这样是为了节约内存。
      所有使用该模式的 AkAmbient 实例，如果都使用同一个事件，那么会自动被检测到，并且会实际使用同一个声音实例，而不是多次加载相同的声音。
      注意到，所有该模式下使用同一事件的 AkAmbient 实例，会采用同样的 Unity 触发器（见 AkEvent 中的 Trigger On）。因此，如果改变其中一个 AkAmbient 的触发器，则将会自动改变同一事件其它 AkAmbient 的触发器。
    • Show Attenuation Sphere（显示衰减范围）:
      显示了一个范围，它定义了能听到事件所播放的声音的空间。
      为了起效果，您必须启用 Wwise 工程中 SoundBank 设置里的 Max Attenuation（Project->Project Settings->Soundbanks->Max attenuation）
      
      • Dont_Show（不显示）：
        不显示任何衰减范围。
      • Current_Event_Only（只显示当前事件）：
        显示在当前模式下调用 AkSoundEngine.PostEvent 之后，播放的所有声音的衰减范围。
        如果在 Simple_Mode 之下，那么只有该游戏对象上的声音的衰减范围会显示出来。
        如果在 Large_Mode之下，那么每个点都会显示一个衰减范围。
        如果在 MultiPosition_Mode 之下，那么对于同一事件 MultiPosition_Mode 中每隔一个 AkAmbient 显示其衰减范围。
      • All_Events（所有事件）：
        为场景中所有 AkAmbient 实例显示衰减曲线。

在 Unity Timeline 中使用 Wwise

在 Unity 的 Timeline 中，可使用自定义 Wwise Track 来触发 Wwise 事件，并设置 Wwise RTPC 值。

参见:

Wwise Timeline Integration

如何通过 inspector来使用 AkEvironment 和 AkEvironmentPortal（混响区域）

在 Wwise 中，Reverb Zone（混响区域）被称为 Environment（环境）或者 Auxiliary Sends（辅助发送）。Reverb Zone 并不局限于混响效果，而且它是在 Wwise 工程中定义的。

AkEnvironment 组件包含一个非常简单的环境区域。您可以在任何类型的碰撞体上附加一个 AkEnvironment。如果想将一个 AkEnvironment 添加到您的场景：

• 使用 Wwise Picker。 这是最简单的添加 AkEnvironment 的方式。将某个 AuxBus 从 Wwise Picker 窗口拖到 Unity Viewer 或者 Inspector 的一个对象上。这将自动在目标 Game Object 上创建一个 AkEnvironment 组件。
• 使用 "Add Component" 菜单。 将一个 AkEnvironment 组件添加到任意 Unity Game Object。从 Inspector 的选择器中选择需要的环境。
• 使用脚本。 您可以在任意时间从 C# 脚本调用 AkSoundEngine.SetGameObjectAuxSendValues()。

我们还有一些门户（portal）可以用来合并两个环境的影响。这两个环境中每个环境对效果的贡献都是和它们与游戏对象间距离相关的。
如果游戏对象站在两个房间之间，或者站在连接两个环境的隧道中，那么这种功能是很有用的。

• 如果想添加一个环境门户到您的工程中，请前往 Unity 菜单栏中的 GameObject->Wwise->Environment Portal。

如果想使用环境和环境门户，您需要一个游戏对象和能觉察到环境的（environment aware） AkGameObj 组件。
AkEnvironmentPortal 会自动探测到和它重叠的 AkEnvironment 对象。重叠的环境将出现在门户 inspector 的两个选择列表中。如果有太多的环境与门户重叠， 您则可以选择让门户和哪些环境混合在一起。

在 Wwise 中，只有 4 个环境可以同时处于活跃状态。这样 4 个环境按照如下方式选择：

• 连接到门户的环境和具有最高优先级的环境将被选择，直到我们选择了 4 个环境，或者直到没有环境连接到门户为止。
• 如果并没有 4 个选中的环境，我们将按照下面的方式来选择没有连接到门户的环境：
  • 选取最高优先级的环境，直到我们选满 4 个环境为止（如果没有设置 Default 和 Exclude Others 标志）。
  • 只有在没有选中其它环境的情况下，Default 才会被选中。
  • 如果您的游戏对象在有着 Exclude Others 标志的环境中，那么该环境将被选中，而其它所有环境将会被废弃。
    

• AkEnvironment 组件：
  只有 4 个环境可以同时处于活跃状态。
  • Priority（优先级）:
    定义一个环境的优先级。
    该数字越小，代表优先级越高。
    如果一个游戏对象处在多于 4 个环境中，只有具有最高优先级的 4 个环境会处于活跃状态（如果没有设置 Default 和 Exclude Others 标志）。
  • Default（Default）:
    一个默认环境，只有当它是唯一一个包含您游戏对象的环境时，才会处于活跃状态。
    如果您的游戏对象处于一个以上的默认环境中，那么只有具有最高优先级的默认环境会处于活跃状态。
  • Exclude Others（排除其它）：
    具有此标志的环境不能与其它环境重叠。
    如果您的游戏对象处于一个有着 Exclude Others 标志的环境中，那么其它所有环境将被废弃。
    如果您的游戏对象处于一个以上的有着 Exclude Others 标志的环境中，那么只有那个具有最高优先级的环境会处于激活状态。
  • AuxBus Name（辅助总线名）：
    指明当前 AuxBus 的名字。如果想选中一个 AuxBus，那么点击当前 AuxBus 的名字，以打开 AuxBus 选择窗口。接下来，您可以点击想选的 AuxBus 然后点击 Ok 按钮，或者双击来选中它。您也可以将想选的 AuxBus 从 Wwise Picker 拖放到当前 AuxBus 的名字上，以选中新的这个 AuxBus。

• AkEnvironmentPortal 组件：
  您可以在 Unity 中创建一个环境门户，方法是前往 GameObject->Wwise->Environment Portal。
  您可以在两个环境之间放置一个环境门户，当您的游戏对象在门户中时，门户就可以将两个环境的效果结合起来。为了生效，门户必须与这两个环境有交集。
  这两个环境中每个环境对效果的贡献都是和它们与游戏对象间距离相关的。游戏对象离环境越近，环境对最终效果的影响就越大。
  
  • Environment #1（环境一）：
    门户将自动检测与它有交集的所有环境。在这些环境中，放置在门户负面一侧（与选择的轴的方向相反）的那些环境将在下拉菜单中可用。 之所以采用按这种方式来给环境排序，是为了在运行时确定每个环境的贡献时减少所需的计算量。
  • Environment #2（环境二）：
    门户将自动检测与它有交集的所有环境。在这些环境中，放置在门户正面一侧（与选择的轴的方向相同）的那些环境将在菜单中可用。 之所以采用按这种方式来给环境排序，是为了在运行时确定每个环境的贡献时减少所需的计算量。
  • Axis（轴）：
    轴用来得出各个环境的贡献。
    例如，如果选择了 z 轴，那么沿着 x 轴移动对于各个环境的贡献没有任何影响。只有 z 轴上的移动才会对它们的贡献产生影响。
    注意到，轴在对象空间中。旋转门户的话，轴也会旋转。

参见:

• 集成环境和游戏定义的辅助发送
• AK::SoundEngine::SetGameObjectAuxSendValues

使用 C# 代码来控制声音引擎

大多数 Wwise SDK 函数可以通过 AkSoundEngine 类在 Unity 中使用。将它想象为 C++ 命名空间 AK::SoundEngine、AK::MusicEngine 等等的替代。想了解与原始 SDK 相比，API 绑定中所做的更改，请参考 API 变化和限制。 对于更复杂的情况，您需要从代码中调用 Wwise 函数。在 API 中，所有函数中的 GameObjectID 被Unity 风格的 GameObject 所替代。在运行时，这个 GameObject 中将自动添加一个 AkGameObj 组件，除非您之前已经手动添加过了。

对于 Event 和 Bank 使用数字 ID，而不是字符串。

原生 Wwise API 使用字符串或 ID 来触发 Wwise 工程中的事件和其它有名字的对象。您仍然可以在 C# 环境下这样做，方法是将文件 Wwise_IDs.h 转码为 Wwise_IDs.cs。点击 Assets > Wwise > Convert Wwise SoundBank IDs。为了完成上述操作，您需要安装 Python。

将 MIDI 发送到 Wwise

如需将 MIDI 发送到 Wwise，可为 AkMIDIPostArray 类的 AkMIDIPost 成员赋值，并调用以下任一方法：

• AkMIDIPostArray.PostOnEvent()
• AkSoundEngine.PostMIDIOnEvent()
• AK.Wwise.Event.PostMIDI()

以下是一个将 MIDI 消息发送到声音引擎的简单脚本：

public class MyMIDIBehaviour : UnityEngine.MonoBehaviour
{
    public AK.Wwise.Event SynthEvent;

    private void Start()
    {
        AkMIDIPostArray MIDIPostArrayBuffer = new AkMIDIPostArray(6);
        AkMIDIPost midiEvent = new AkMIDIPost();

        midiEvent.byType = AkMIDIEventTypes.NOTE_ON;
        midiEvent.byChan = 0;
        midiEvent.byOnOffNote = 56;
        midiEvent.byVelocity = 127;
        midiEvent.uOffset = 0;
        MIDIPostArrayBuffer[0] = midiEvent;

        midiEvent.byOnOffNote = 60;
        MIDIPostArrayBuffer[1] = midiEvent;

        midiEvent.byOnOffNote = 64;
        MIDIPostArrayBuffer[2] = midiEvent;

        midiEvent.byType = AkMIDIEventTypes.NOTE_OFF;
        midiEvent.byOnOffNote = 56;
        midiEvent.byVelocity = 0;
        midiEvent.uOffset = 48000 * 8;
        MIDIPostArrayBuffer[3] = midiEvent;

        midiEvent.byOnOffNote = 60;
        MIDIPostArrayBuffer[4] = midiEvent;

        midiEvent.byOnOffNote = 64;
        MIDIPostArrayBuffer[5] = midiEvent;

        SynthEvent.PostMIDI(gameObject, MIDIPostArrayBuffer);
    }
}

在 Unity 中使用 Audio Input 源插件

您可以通过 C# 脚本来调用 Audio Input 源插件。请参阅 Audio Input Source Plug-in from the Wwise SDK documentation.

以下是一个将测试音发送到 Audio Input 源插件的简单脚本：

public class MyAudioInputBehaviour : UnityEngine.MonoBehaviour
{
    public AK.Wwise.Event AudioInputEvent;
    public uint SampleRate = 48000;
    public uint NumberOfChannels = 1;
    public uint SampleIndex = 0;
    public uint Frequency = 880;
    private bool IsPlaying = true;

    // 通过该回调填充音频采样 – 此函数会在每一帧针对各声道调用。
    bool AudioSamplesDelegate(uint playingID, uint channelIndex, float[] samples)
    {
        for (uint i = 0; i < samples.Length; ++i)
            samples[i] = UnityEngine.Mathf.Sin(Frequency * 2 * UnityEngine.Mathf.PI * (i + SampleIndex) / SampleRate);

        if (channelIndex == NumberOfChannels - 1)
            SampleIndex = (uint)(SampleIndex + samples.Length) % SampleRate;

        // 返回 false 表示已无更多数据可提供。与此同时，会停止关联事件。
        return IsPlaying;
    }

    // 通过该回调设置音频格式 - 在请求提供样本之前会调用此函数一次。
    void AudioFormatDelegate(uint playingID, AkAudioFormat audioFormat)
    {
        // Channel configuration and sample rate are the main parameters that need to be set.
        audioFormat.channelConfig.uNumChannels = NumberOfChannels;
        audioFormat.uSampleRate = SampleRate;
    }

    private void Start()
    {
        // The AudioInputEvent event, that is setup within Wwise to use the Audio Input plug-in, is posted on gameObject.
        // 调用 AudioFormatDelegate 一次，并在每一帧调用 AudioSamplesDelegate 一次，直到返回 false。
        AkAudioInputManager.PostAudioInputEvent(AudioInputEvent, gameObject, AudioSamplesDelegate, AudioFormatDelegate);
    }

    // 可通过其他脚本调用此方法以停止回调
    public void StopSound()
    {
        IsPlaying = false;
    }

    private void OnDestroy()
    {
        AudioInputEvent.Stop(gameObject);
    }
}

在 Unity 中应用自定义定位

在默认情况下，会将 AkGameObj 组件关联到特定的 Unity gameObject ，并使用其变换功能（可选偏置）进行全面定位。这对很多游戏（如第一人称射击游戏）来说基本上就够了。不过，对于采用自定义镜头角度的游戏（如各种第三人称游戏）来说，假如只是简单地将音频听者关联到单个游戏对象（如 Unity 中的主镜头），定位的距离衰减和空间化这两个方面可能会不好协调。其他游戏可能还要给玩家提供别的自定义定位体验。

为此，AkGameObj 组件类允许用户重写定位。通过 GetPosition()、 GetForward() 和 GetUpward() 这三种虚方法，用户可选择继承 AkGameObj 的子类，并使用这些子类组件来灵活地自定义任意数量 Unity gameObject 的定位。

这里有一个简单的示例，展示了如何使用自定义组件来重写默认的 AkAudioListener 行为。对这个整合了 Wwise 的第三人称游戏项目，可移除现有的 AkAudioListener 及其关联的 AkGameObj 。然后，将以下脚本关联到 MainCamera 对象，并关联 AkAudioListener 。最后，指定音频听者位置所要跟随的目标 gameObject （如玩家角色）。如此一来，所有发声体的距离衰减都会将所选目标 Unity gameObject 的位置作为听者位置（画面内的距离听者），而所有发声体的朝向仍会将主镜头朝向作为听者朝向（画面外的朝向听者）。

#if !(UNITY_DASHBOARD_WIDGET || UNITY_WEBPLAYER || UNITY_WII || UNITY_WIIU || UNITY_NACL || UNITY_FLASH || UNITY_BLACKBERRY) // Disable under unsupported platforms.

//
// Copyright (c) 2017 Audiokinetic Inc. / All Rights Reserved
//

using UnityEngine;
using System;
using System.Collections.Generic;


[AddComponentMenu ("Wwise/AkGameObj3rdPersonCam")]
[ExecuteInEditMode] // 需要通过 ExecuteInEditMode 来正确维护 isStaticObject 的状态。
public class AkGameObj3rdPersonCam : AkGameObj
{
    public Transform target;            // 指定此镜头所要跟随的位置。用户可在 Inspector 中将其指定为玩家角色的 Unity gameObject。

    
    // 将镜头位置设为玩家位置，据此处理距离衰减。
    public override Vector3 GetPosition ()
    {
        return target.GetComponent<AkGameObj> ().GetPosition ();
    }

}
#endif // #if !(UNITY_DASHBOARD_WIDGET || UNITY_WEBPLAYER || UNITY_WII || UNITY_WIIU || UNITY_NACL || UNITY_FLASH || UNITY_BLACKBERRY) // Disable under unsupported platforms.