안녕하세요, 개발자 여러분! 오늘은 PC에서 Unreal Engine Blueprinting을 사용하여 네트워크 연결된 데모 내부에 비디오 파티 채팅 기능을 구현해 보겠습니다.
Unreal Engine은 가장 강력한 실시간 3D 콘텐츠 제작 플랫폼으로, 가장 강력한 실시간 참여 플랫폼인 아고라와 결합되어 더욱 강력해졌습니다. Unreal Engine은 Fortnite, Gears of War, PUBG와 같은 게임의 핵심 엔진으로 잘 알려져 있습니다. 그러나 언리얼은 놀라운 건축 시각화, 3D 콘텐츠를 강화한 라이브 방송, 그리고 훨씬 더 많은 것을 만들기 위해 사용됩니다!
아고라를 사용하면 미래의 디지털 플레이그라운드에 비디오 파티 채팅을 통합할 수 있으며, VR을 통해 고객과 새로운 꿈의 집을 함께 탐험하는 부동산 중개인과 고객을 실시간으로 연결하거나, 아고라의 방송 기능을 활용해 차세대 토크쇼에서 라이브 팬들과 상호작용할 수 있습니다.
언리얼과 아고라를 결합하면, 이제 언리얼 엔진으로 손수 제작된 디지털 세계 내에서 전 세계의 사람들이 상호작용할 수 있게 됩니다!
아고라의 실시간 상호작용을 구현하기 위해, 두 플레이어가 특수 플랫폼에 들어서면 아고라 채널에 연결됩니다. 이후 플레이어를 로컬 네트워크를 통해 동일한 레벨에 연결하여 네트워크 기반 멀티플레이어 게임을 시뮬레이션합니다.
이 데모는 두 플레이어를 동일한 레벨에 연결하여 네트워크 게임이 어떻게 보일 수 있는지 보여주는 필수 요소를 표시합니다. 그러나 단일 PC(또는 Mac)만 사용할 경우, Agora 웹 예제 쇼케이스를 사용하여 2인용 Agora 통화를 시뮬레이션해야 합니다.
현재 Agora는 Unreal Engine 버전 4.23–4.25에서 지원됩니다.
이 데모에는 4.25 버전을 사용하는 것을 권장합니다.
아고라나 Unreal에 완전히 처음이라면 아래 링크를 따라 적절한 다운로드/가입 안내를 확인할 수 있습니다.
또한 이 템플릿 프로젝트를 사용하는 것을 권장합니다. 이 프로젝트에는 설치된 아고라 SDK와 함께 작동하는 아고라 예제가 포함되어 있습니다. 플러그인 링크는 다음과 같습니다.
설치
다음 단계를 따라 아고라 플러그인을 프로젝트에 통합하세요.
- 플러그인을 [your_project]/Plugins 폴더로 복사합니다.
- [your_project]/Source/[project_name]/[project_name].Build.cs 파일의 Private Dependencies 섹션에 플러그인 의존성을 추가합니다.
PrivateDependencyModuleNames.AddRange(new string[] { “AgoraPlugin” });. - Unreal Engine을 재시작합니다 (실행 중일 경우).
- 편집 -> 플러그인으로 이동합니다. 프로젝트 -> 기타 카테고리를 찾아 플러그인이 활성화되어 있는지 확인합니다.
이 프로젝트를 사용하기로 결정하셨다면, 프로젝트에 ThirdPerson 콘텐츠 팩을 설치해야 합니다. 이를 위해 Unreal 엔진을 열고, 콘텐츠 브라우저 내에서 “새로 추가” 버튼을 클릭합니다. 첫 번째 항목인 “기능 또는 콘텐츠 팩 추가…”를 클릭한 후 Third Person을 선택합니다.
이 작업을 완료한 후 설정 > 프로젝트 설정 > 맵 및 모드로 이동하여 편집기 시작 맵과 게임 기본 맵을 ThirdPersonExampleMap으로 설정하고 기본 파우너를 ThirdPersonCharacter로 설정합니다.
Agora 플러그인이 설치된 Unreal 프로젝트를 통해 Agora의 네트워크에 접근할 수 있게 되었습니다. 이는 음성과 비디오를 위해 기본부터 구축된 사설 VIP 네트워크입니다!
아고라 설정
BP_Party 위젯
이제 채널 내 2명의 플레이어로부터 Agora 비디오 피드를 렌더링하는 논리를 설정할 차례입니다.
블루프린트 폴더 내부를 오른쪽 클릭하고 “사용자 인터페이스 > 위젯 블루프린트”로 이동하여 이름을 BP_PartyWidget로 지정합니다.
캔버스에 두 개의 이미지를 드래그 앤 드롭한 후 각각 Player1Video와 Player2Video로 이름을 지정합니다. 예를 들어:
원하는 크기와 위치로 조정할 수 있습니다. 다음은 제가 사용한 속성입니다 — Player2Video의 PositionX 속성을 “300”로 설정하여 균일하게 맞췄습니다.
마지막으로, 새로운 위젯 블루프린트의 이벤트 그래프로 이동하여 “AgoraEngine”이라는 이름의 ‘Agora’ 유형 변수를 생성하고 이 커스텀 이벤트를 추가합니다:
“assign on local frame received”를 검색하세요 — 이 작업은 필요한 두 개의 노드를 모두 생성합니다.
이 이벤트는 새로운 아고라 프레임이 수신될 때마다 해당 프레임을 렌더링하고 이미지를 출력하여 위젯 이미지를 동영상으로 변환합니다.
동영상을 렌더링하기 위해 Agora 엔진을 설정하고, 새로운 플레이어가 참여할 때 호출될 콜백을 생성하며, 플레이어가 파티에 참여하는 모습을 시뮬레이션합니다.
ThirdPersonCharacter 이벤트 그래프를 열고 블루프린팅을 시작해 보겠습니다. 다음은 ThirdPersonCharacter 초기화의 고수준 개요입니다. BP_PartyWidget 유형의 변수 “PartyWidget”, Agora 유형의 변수 ‘AgoraEngine’, 그리고 “DefaultChannel”과 “CurrentChannel”이라는 두 개의 문자열 변수를 생성합니다.
먼저 BP_PartyWidget를 추가하여 로컬 비디오 피드와 다른 원격 플레이어의 피드를 확인할 수 있도록 합니다. “UpdateChannel”은 나중에 생성할 사용자 정의 이벤트입니다. 현재는 이벤트를 생성하고 빈 상태로 두세요. 이 이벤트는 EventBeginPlay에서 호출할 것입니다.
이미지를 숨겨두겠습니다. 원격 또는 로컬 비디오가 들어오고 있다는 콜백이 발생할 때까지 기다립니다.
다음으로 Agora 엔진을 초기화하고 기본 채널에 참여합니다.
그러면 기본 채널 이름 내에서 로컬 비디오 피드를 확인할 수 있지만, 다른 사용자는 해당 채널에 참여할 수 없습니다.
마지막으로, 로컬 및 원격 사용자의 참여를 등록하는 콜백을 생성하고, Agora 비디오 피드를 렌더링하기 위해 BP_PartyWidget 이미지를 초기화합니다.
BP_PartyJoiner
BP_PartyJoiner는 플레이어를 동일한 Agora 채널에 연결하는 사용자 정의 액터입니다. 이 액터는 플레이어가 그 위에 들어서면 해당 플레이어의 현재 채널 이름을 변경하고 해당 플레이어를 Agora 채널에 연결하는 플랫폼 역할을 합니다.
Actor 유형의 새로운 Blueprint 클래스를 생성하고 이름을 BP_PartyJoiner로 지정합니다. DefaultSceneRoot에 Box Collision과 가시성을 위해 Cube 컴포넌트를 추가합니다(Box Collision보다 작게 설정해야 합니다). ChannelName이라는 이름의 string 유형 변수를 생성합니다.
마지막으로 두 개의 이벤트를 생성하고 현재는 빈 상태로 두어 나중에 연결할 수 있도록 합니다.
BoxCollision 구성 요소를 선택하고 세부 정보 패널에서 아래로 스크롤하여 OnBeginOverlap 및 OnEndOverlap의 녹색 플러스 상자를 클릭합니다.
아고라 플레이어 파티
이제 플레이어 채널 이름을 조정하는 논리를 생성하여 각 플레이어가 동일한 Agora 채널에 연결되도록 하겠습니다.
ThirdPersonCharacter를 열고, Default 및 Current Channel 변수의 세부 정보 패널에서 “Replication” 필드를 Replicated로 설정합니다. 이 설정은 변수를 네트워크에 노출시켜 모든 플레이어가 서로의 채널 이름을 동일하게 인식할 수 있도록 합니다.
현재 채널은 참여하는 파티에 따라 변경되고 이동하며, 기본 채널은 파티 채팅을 떠나고 싶을 때 사용하는 고유한 채널로 사용됩니다.
채널을 변경하려면 Unreal Engine 복제 시스템과 네트워크에 노출되는 사용자 정의 이벤트를 생성합니다. 표준 사용자 정의 이벤트를 생성하면 결과는 개별 클라이언트에 국한되어 공유되지 않습니다.
먼저 UpdateChannel 이벤트부터 시작하고 ThirdPerson Character 내의 이벤트 그래프로 이동합니다.
오른쪽 클릭 후 “custom event”를 입력하고 이벤트 이름을 “UpdateChannel”로 지정 후 Enter 키를 누릅니다.
두 개의 이벤트를 더 생성합니다. 하나는 ‘ServerUpdateChannel’, 다른 하나는 “MultiUpdateChannel”로 이름 지정합니다.
서버 업데이트 채널 노드를 클릭한 후 세부 정보 패널 > 그래프 > 복제에서 드롭다운 상자를 “서버에서 실행”로 설정합니다.
멀티 업데이트 채널에 대해 동일한 작업을 수행하지만, 멀티캐스트를 선택합니다. 각 노드의 세부 정보 > 입력에서 “+ 매개변수 추가” 버튼을 클릭하고 새로운 문자열 이름으로 NewChannel을 추가합니다. 디버그 목적으로 print 문장을 포함했지만, 필요에 따라 제거할 수 있습니다.
UNREAL 팁:
이 튜토리얼에서는 Unreal의 복제 시스템을 자세히 설명하는 것은 범위를 벗어납니다 — 이 UE4 네트워크 컴펜디움은 좋은 시작점입니다 — 그러나 기본적인 이해는 다음과 같습니다:
Unreal의 네트워크는 서버-클라이언트 모델입니다. 한 서버가 여러 클라이언트를 제어하며 모든 네트워크화된 보편적인 변경을 수행하며, 클라이언트는 자신의 로컬 게임에만 변경을 가할 수 있습니다.
특정 클라이언트의 채널 이름을 변경하고 다른 클라이언트가 해당 변경 사항을 인식하도록 하려면 서버에서 해당 변경을 수행해야 합니다.
채널을 업데이트하는 이벤트를 호출할 때 먼저 확인합니다:
권한이 있나요? (서버인가요?),
예 — 모든 클라이언트에게 이 이벤트를 실행하도록 지시합니다 (멀티캐스트 이벤트 실행).
아니면 — 서버에게 모든 클라이언트에게 이 이벤트를 실행하도록 지시합니다(서버 이벤트를 실행하면, 이는 다시 멀티캐스트 이벤트를 적절히 실행합니다).
이 패턴을 사용하면 로컬로 제어되는 클라이언트만이 아닌 모든 클라이언트의 플레이어에 변경 사항을 적용할 수 있습니다. 채널을 기본 문자열로 재설정하기 위해 ResetChannel 이벤트를 생성할 것입니다.
마지막으로 플레이어가 새로운 채널에 참여할 수 있는 이벤트를 생성합니다.
BP_PartyJoiner로 돌아가서 빈 오버랩 이벤트를 채워넣어 보겠습니다.
테스트
단일 플레이어와 웹 예제 데모를 통해 빠르게 테스트해 보겠습니다! 독립 실행형 빌드를 만드는 방법을 모르신다면 아래로 스크롤하여 “최종 테스트” 섹션으로 이동하세요.
이 테스트는 다른 플레이어의 파티에 참여한 것처럼 Agora 기능이 정상적으로 작동하는지 확인하기 위한 것입니다.
웹 예제 데모에서 Unreal 프로젝트에 사용 중인 appID와 연결할 채널 이름을 입력하세요.
다음 섹션 “네트워크 설정”에서는 동일한 언리얼 레벨에 두 명의 고유한 플레이어를 배치하는 방법을 보여드리며, 이 데모를 기반으로 Agora SDK와 함께 작동하는 네트워크 기능을 구현할 수 있는 플랫폼으로 활용할 수 있도록 안내합니다!
네트워크 설정
다음으로 기본 Unreal 네트워크 설정을 진행합니다. 이 설정은 가장 기본적인 네트워크 구성으로, 특수 UI나 로비 기능은 제외됩니다. 이 네트워크의 목적은 동일한 레벨 내 두 플레이어를 표시하는 것입니다. 이 기능을 제외하고도 데모를 테스트할 수 있지만, 다른 기능과 결합된 Agora 실시간 상호작용을 테스트하려면 이 설정을 권장합니다!
더블 클릭하여 열기, 그리고 두 개의 버튼을 생성합니다. 하나는 “HostButton”, 다른 하나는 “JoinButton”으로 이름 지정합니다.
호스트 버튼에 클릭 이벤트를 할당하려면, ‘Designer’ 뷰에서 호스트 버튼을 클릭한 후 세부 정보 패널에서 아래로 스크롤하여 “On Clicked”의 녹색 플러스 아이콘을 클릭합니다.
결합 버튼에도 동일한 작업을 수행합니다. “Graph”를 클릭하여 이벤트 그래프로 이동합니다. 여기에서 기본 네트워크 노드를 설정할 것입니다. OnClicked (HostButton) 노드에서 다음과 같이 설정합니다:
우리는 아직 “온라인” 레벨을 만들지 않았으며, 곧 바로 그 작업을 진행하겠습니다. 다음으로 OnClicked (JoinButton)을 다음과 같이 설정하세요:
다행히도 Unreal에는 많은 내장 네트워크 기능이 있으며, 이 모든 것이 두 명의 플레이어를 같은 레벨에 배치하는 데 필요합니다!
이것은 네트워크의 매우 간소화된 버전이지만, 이 튜토리얼의 범위 내에서 목적에 맞게 작동합니다.
이 기능을 테스트하기 전에 ThirdPersonExampleMap 뷰로 돌아가세요. 콘텐츠 폴더 내에서 “Ctrl” 키를 누른 상태에서 ‘N’ 키를 눌러 새로운 레벨을 생성한 후 “Default”를 선택하고 이름을 “Online”으로 지정하세요.
ThirdPersonExampleMap으로 돌아가서, 새로운 에디터 창에서 플레이할 때 “Net Mode: Play As Client”로 설정하고, 2명의 플레이어를 전용 서버에서 실행하도록 온라인 설정을 조정하세요.
다시 드롭다운 메뉴를 클릭한 다음 “고급 설정…”을 클릭합니다. 아래로 스크롤하여 “멀티플레이어 옵션”을 찾아 “서버에 자동 연결” 체크 상자를 해제합니다.
네트워크 위젯의 논리를 구현했습니다. 이제 실제로 위젯을 생성하고 뷰포트에 추가해야 합니다.
ThirdPersonCharacter 내부의 이벤트 그래프로 이동합니다. 새로운 커스텀 이벤트인 CreateNetworkWidgets를 생성합니다(빈 그래프를 오른쪽 클릭하고 “Custom Event”를 입력한 후), 다음 노드를 다음과 같이 연결합니다:
마지막으로, 레벨 블루프린트 안으로 들어가세요.
그리고 방금 생성한 이벤트인 CreateNetworkWidgets를 모든 사용 가능한 플레이어에 다음과 같이 호출합니다:
이렇게 설정했습니다. ThirdPersonExampleMap 레벨로 진입하면 로컬 네트워크를 호스트하거나 참여할 수 있는 UI가 표시됩니다. Online 레벨로 진입하면 해당 UI 위젯이 표시되지 않습니다.
최종 테스트!
씬에 이미 배치된 ThirdPersonCharacter를 삭제한 후 새 에디터 창에서 플레이를 클릭하세요.
파티 조이너(PartyJoiner)로 달려가면, print 문장이 두 클라이언트 모두에서 새로 업데이트된 채널이 일치함을 표시해야 합니다.
프로젝트를 테스트하려면 독립 실행형 빌드를 만들어야 합니다. 이를 위해 파일 > 프로젝트 패키징 > PC(네트워크 기능을 제외하려면 Mac)로 이동합니다.
Mac으로 빌드한 경우, 완료된 프로젝트를 오른쪽 클릭하고 “패키지 내용 표시”를 선택한 후 Info.plist 파일을 열고 다음 항목을 추가합니다.
그런 다음 빌드를 열고 시작할 수 있습니다!
다시 한 번 정리하자면,
- 우리는 Unreal의 “Sessions”를 사용하여 두 명의 플레이어가 동일한 레벨에 참여하도록 설정하여 멀티플레이어 게임을 시뮬레이션합니다.
- BP_PartyJoiner 패드를 통과하면 각 클라이언트에 선택한 PartyJoin 채널 이름을 일관되게 표시합니다.
- PartyJoiner를 터치하면 기본 Agora 채널을 떠나 PartyJoiner 블루프린트에 지정된 새로운 채널에 가입합니다.
- 해당 채널에 가입한 후, PartyJoiner 채널 이름을 사용하여 Agora Web Example Showcase를 통해 다른 Agora 인스턴스를 연결하고, 게임 UI에 두 플레이어의 비디오 피드가 렌더링되는 모습을 확인합니다.
AGORA 주의사항:
같은 컴퓨터에서 Unreal을 사용해 두 개의 Agora 클라이언트를 연결하면, 두 클라이언트가 웹캠에 동시에 접근하려다 보니 한 개의 비디오 피드가 멈출 수 있습니다. 이 문제를 해결하려면 두 대의 별도 PC를 사용하거나, 휴대폰에서 Agora 데모를 사용하세요.
그럼에도 불구하고, Unreal을 사용해 비디오 참여를 통해 플레이어를 연결하는 것이 얼마나 간단하고 직관적인지 확인할 수 있습니다. 단순히 같은 이름의 채널에 플레이어를 연결하면 바로 시작할 수 있습니다!
질문, 의견, 또는 다른 언리얼 튜토리얼에 대한 아이디어가 있다면 아래로 연락해 주세요.
