Wwise Unreal Integration Documentation

모듈 연결하기

Wwise Unreal 통합은 여러 모듈로 분리되어 있습니다. C++ 프로젝트 내에서 Wwise의 기능을 사용하려면 프로젝트의 빌드 파일(.Build.cs) 에서 이러한 모듈을 연결해야 합니다. 모듈을 빌드 파일에서 제거하면 해당 모듈을 비활성화할 수 있습니다.

다음 예시에서 프로젝트는 Core, CoreUOBject, Engine, InputCore, AkAudio, WwiseSoundEngine 모듈이 공용으로 포함됩니다. AkAudio와 WwiseSoundEngine은 Wwise 모듈입니다.

public class MyModule : ModuleRules
{
    public MyModule(ReadOnlyTargetRules Target) : base(Target)
    {
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "AkAudio", "WwiseSoundEngine" });
 
        // 기타 설정들
    }
}

이 경우 WwiseSoundEngine 모듈과 AkAudio 모듈의 기능을 사용할 수 있습니다. 모듈은 PublicDependencyModulesNames나 PrivateDependencyModulesNames에 있을 수 있습니다. 모듈에 대한 자세한 정보는 Unreal Engine 문서에서 확인할 수 있습니다.

모듈 개요

Unreal Wwise 통합은 다음 모듈로 구성됩니다.

AkAudio: 통합에서의 대부분의 사용자-상호작용 기능을 위한 루트 모듈입니다.
AkAudioMixer: 프로젝트에서 오디오 출력과 오디오 서브믹스를 Unreal 오디오 컴포넌트에서 Wwise 프로젝트의 믹서로 연결할 수 있게 해줍니다.
AudiokineticTools: Implements editor-specific tools and utilities like the Wwise Browser.
WwiseFileHandler: Wwise Sound Engine에 미디어, SoundBank, Wwise Location Resolver, I/O Hook의 요청을 처리하는 기능 및 필요한 외부 음원을 제공합니다.
WwiseProjectDatabase: Wwise 프로젝트에서 생성된 SoundBank의 현재 상태에 관한 메모리 기반 데이터베이스 뷰를 제공합니다.
WwiseResourceCooker: WwiseObjectInfo 구조 를 쿠킹된 구조체로 변환하고 필요한 리소스를 스테이징 폴더에 복사합니다.
WwiseResourceLoader: 모든 Wwise 에셋 유형에 필요한 모든 리소스의 로드/언로드를 처리합니다.
WwiseSoundEngine: Wwise Sound Engine API와 Unreal 프로젝트 사이의 다리 역할을 합니다.

통합에서의 모듈의 종속성은 다음 그림에 설명되어 있습니다.

Wwise Unreal Integration 오버라이드하기

통합에서 WwiseSoundEngine, AudiokineticTools, AkAudio를 제외한 모든 모듈은 상속을 통해 확장이 가능하도록 설계되었습니다. 이러한 모듈의 대부분의 기능은 가상이기 때문에 개발자가 이를 오버라이드하고 프로젝트에 가장 적합하도록 해당 작동 방식을 변경할 수 있습니다. 모듈을 오버라이드하려면 새로운 모듈을 만들고 오버라이드하려는 모듈을 상속하는지 확인해야 합니다. 그런 다음 원하는 함수를 오버라이드 합니다. 새로운 모듈을 사용하려면 다음과 같이 해당 모듈이 게임의 Build.cs에 포함되고 DefaultEngine.ini에 추가되었는지 확인하세요.

[Audio]

WwiseFileHandlerModuleName=WwiseSimpleExternalSource

<tt>WwiseSimpleExternalSource</tt> 모듈은 모듈을 오버라이드하는 예시를 보여줍니다. 이 모듈은 Data 테이블이 있는 외부 음원를 처리하기 위해 WwiseFileHandler 모듈을 오버라이드합니다.

C++를 사용해서 AkComponent 생성하기

C++를 사용하여 새로운 AkComponent를 생성할 경우 이 컴포넌트를 상위 계층 컴포넌트에 반드시 연결해야 합니다. API가 의도한 대로 작동하려면 AkComponent가 필요합니다. 다음 섹션은 AkComponent를 추가하는 방법의 예시를 제공합니다.

Unreal 프로젝트에서 Wwise API 사용하기

Wwise Unreal 통합을 통해 Wwise API를 사용할 수 있습니다. 대부분의 함수는 WwiseSoundEngine 모듈이나 AkAudio 모듈을 통해 호출할 수 있습니다.

WwiseSoundEngine 모듈

WwiseSoundEngine 모듈은 대부분의 SoundEngine API 작업에 대한 하위 레벨 접근을 제공합니다. 다음 예시와 같이 WwiseSoundEngine 모듈을 사용하면 API 함수에 안전하게 바로 접근할 수 있습니다.

#include "AkAudioEvent.h"
#include "AkComponent.h"
#include "Wwise/LowLevel/WwiseLowLevelSoundEngine.h"
 
void PostEventSoundEngine(UAkAudioEvent* Event, AActor* GameObject)
{
    
    if (auto* SoundEngine = IWwiseSoundEngineAPI::Get())
    {
        if(Event && GameObject)
        {
            TArray<UAkComponent*> Array;
            GameObject->GetComponents<UAkComponent>(Array);
            //The Actor doesn't have an AkComponent attached. 이 컴포넌트는 해당 액터에서 사운드를 방사하려는 경우에 필요합니다.
            if (Array.Num() == 0)
            {
                //PostEvent doesn't load the event. The Event needs to be loaded beforehand.
                if (!Event->IsLoaded())
                {
                    Event->LoadData();
                }
 
                auto* AkAudioComponent = NewObject<UAkComponent>(GameObject);
                AkAudioComponent->SetupAttachment(GameObject->GetDefaultAttachComponent());
                Array.Add(AkAudioComponent);
                AkAudioComponent->RegisterComponent();
            }
 
            SoundEngine->PostEvent(Event->GetWwiseShortID(), Array[0]->GetAkGameObjectID());
        }
    }
}

이 코드는 해당 액터에 Event를 게시합니다. 해당 액터에 반드시 UAkComponent를 추가해서 Wwise에 등록해야 합니다. WwiseSoundEngine 모듈에서 자동으로 Event가 실행되지 않기 때문에 Event도 반드시 로드해야 합니다.

참고: 2022.1 이전 버전의 통합에서는 동일한 동적 라이브러리에서 API에 접근해야 했기 때문에 AkAudio 모듈 외부의 코드에 접근하는 것이 불가능했습니다.

AkAudio 모듈

AkAudio는 통합에서의 대부분의 사용자-상호작용 기능을 위한 루트 모듈입니다. 이 모듈은 Unreal Component를 사용해서 WwiseSoundEngine 모듈이 할 수 있는 대부분의 작업을 수행할 수 있습니다. 여기에는 통합에서사용하는 에셋 유형 및 컴포넌트에 대한 클래스가 담겨 있습니다. SoundEngine을 직접 호출하는 대신 AkAudioDevice는 WwiseSoundEngine API의 일반적인 사용을 래핑(wrap)하는 많은 도우미 함수(helper function)를 제공합니다. 이러한 도우미 함수는 API를 사용하는 데 필요한 리소스가 로드되었는지 확인하며 더 많은 정보를 로깅합니다.

다음 코드는 이전 예시와 마찬가지로 주어진 액터에 Event를 게시할 뿐만 아니라 AkComponent 연결과 Event 로딩도 처리합니다.

#include "AkAudio.h"
 
void PostEvent(UAkAudioEvent* Event, AActor* GameObject)
{
    if (FAkAudioDevice::Get())
    {
        FAkAudioDevice::Get()->PostAkAudioEventOnActor(Event, GameObject);
    }
}

더 많은 예시 코드는 WwiseDemoGame의 WwiseDemoGame/WwiseCodeExample에서 찾을 수 있으며 WwiseDemoCodeExampleMap에서 시험해 볼 수 있습니다.

디버그 기능

로깅

통합의 각 모듈에는 독립적인 로그 상세 수준(independent log verbosity level)이 있습니다. 이 수준은 효율적으로 디버그할 수 있게 도와줍니다. 오류가 발생하면 오류를 만들어낸 모듈을 찾은 다음 해당 모듈 로그의 디테일 정도를 Verbose나 VeryVerbose로 설정해서 오류가 발생한 이유를 더 잘 이해할 수 있습니다. . DefaultEngine.ini 파일의 Core.Log 섹션에서 각 모듈의 상세 수준을 변경할 수 있습니다. 또한 모든 모듈에서는 기본적으로 활성화되는 LogWwiseHints라는 특수한 로깅 범주가 있는데, 이 범주는 더 이상 사용되지 않는 기능이나 기타 나쁜 습관을 사용하는 것에 관해서 경고합니다.

사용할 수 있는 상세 수준은 다음과 같습니다.

Fatal: 프로그램 실행을 계속할 수 없거나 진행해서는 안 되는 경우 크래시를 일으킵니다. 예를 들어, 필요한 플러그인 모듈이 로드되지 않았을 수 있습니다.
Error: 오디오가 작동하지 않는 경우 게임을 패키징을 할 수 없게 만듭니다.
Warning: 예측하지 못한 동작을 일으킬 수 있지만 치명적이지 않은 기능에 관한 경고를 나타냅니다. 원한다면 패키징을 방지할 수도 있습니다.
Display: 모듈 초기화에 관한 정보를 기록하고 Commandlet 정보를 제공합니다.
Log: 다양한 중요 작업을 기록합니다.
Verbose: 모듈이 수행하는 모든 작업을 기록합니다.
VeryVerbose: 모듈이 수행하는 각 작업의 모든 단계를 기록합니다.

다음 예시에서 각 모듈과 관련된 상세 수준을 알아 볼 수 있습니다.

[Core.Log]
 
LogAkAudio=Verbose
LogAkAudioMixer=Verbose
LogAudiokineticTools=Log
LogWwiseAudioLink=Verbose
LogWwiseConcurrency=Verbose
LogWwiseFileHandler=Verbose
LogWwiseHints=Warning
LogWwiseResourceLoader=Warning
LogWwiseResourceCooker=Log
LogWwiseProjectDatabase=Log
LogWwiseSimpleExtSrc=Error

상세 수준(verbosity level)에 대한 자세한 내용은 Unreal Engine 문서에서 확인할 수 있습니다.

Stat

통합에는 디버깅에 도움이 되는 다음 Stat이 포함되어 있습니다.

AkAudioDevice: Post Event Async 호출에 관한 정보를 기록합니다.
AkSoundBankGenerationSource: SoundBank 생성과 관련된 WAAPI 호출을 기록합니다.
WwiseConcurrency: Logs information about memory used to manage multi-threading.
WwiseFileHandler: 로드된 미디어, SoundBank, 외부 음원에 대한 정보를 기록합니다.
WwiseFileHandlerLowLevelIO: 스트리밍 사운드에 대한 정보를 기록합니다.
WwiseMemory: Logs information about memory usage.
WwiseObstructionOcclusion: Logs information about obstruction and occlusion calculations.
WwiseProjectDatabase: Logs information about memory used by the WwiseProjectDatabase module.
WwiseResourceLoader: 참조된 AkType에 관한 정보를 기록합니다.
WwiseSoundEngine: API 호출에 관한 정보를 기록합니다.

이러한 정보에 접근하려면 Unreal Viewport 옵션에서 필요한 Stat을 선택하세요.

Stat에 대한 자세한 정보는 Unreal Engine 문서을 참고해 주세요.

Packaging Requirements

When you package your Unreal project, the assets are "tree-shaken." In other words, Unreal assets that represent Wwise objects are automatically included if they are referenced either by another packaged asset or by a packaged map. If they are, any associated SoundBanks and media files are copied into the built package. Any Wwise Unreal assets that do not satisfy one of these conditions are not included.

This packaging approach is efficient, but in certain cases some Wwise Unreal assets might be improperly excluded, which can cause errors. The following scenarios can cause this type of problem:

The project uses Wwise Unreal assets that are not directly referenced by packaged maps.
The project uses Events that are posted by string or from code.

If one of these scenarios applies to your project, you must therefore ensure that either the asset is directly referenced by a map, or ensure that the required assets are manually loaded. To manually add assets, add the containing directory to the project's Additional Asset Directories to Cook in the Project Settings. Refer to Project Section of the Unreal Project Settings for more information.

이 페이지가 도움이 되었나요?

지원이 필요하신가요?

질문이 있으신가요? 문제를 겪고 계신가요? 더 많은 정보가 필요하신가요? 저희에게 문의해주시면 도와드리겠습니다!

지원 페이지를 방문해 주세요

작업하는 프로젝트에 대해 알려주세요. 언제든지 도와드릴 준비가 되어 있습니다.

프로젝트를 등록하세요. 아무런 조건이나 의무 사항 없이 빠른 시작을 도와드리겠습니다.

Wwise를 시작해 보세요

Wwise Unreal 통합

Unreal Engine C++ 프로젝트