언리얼 엔진(UE) 은 Visual Studio 에서 Android Game Development Extension(AGDE) 플러그인 을 통한 디버깅을 지원합니다. 이 플러그인을 사용하면 Android Studio 환경으로 전환하지 않아도 Visual Studio에서 Android 프로젝트에 필요한 디버깅 및 프로파일링 툴을 사용할 수 있습니다. 이는 Windows 사용자가 UE에서 Android 프로젝트를 진행할 때 권장되는 디버깅 환경입니다.
이 가이드는 해당 플러그인을 다운로드 및 활성화하는 방법과 사용할 때 유용한 리소스 링크를 안내합니다.
AGDE 다운로드 및 설치
AGDE 플러그인을 설치하려면 작업할 프로젝트의 솔루션을 설치하고 다음 단계를 따르세요.
-
Visual Studio 2022 가 설치되었으며 언리얼 엔진의 디폴트 Visual Studio 버전으로 사용하고 있는지 확인합니다.
-
Android 개발자 페이지에서 AGDE 플러그인을 다운로드합니다. 현재 UE 버전에는 AGDE 23.1 82 이상 버전이 필요합니다.
-
Visual Studio에 AGDE 플러그인을 설치합니다.
-
프로젝트의 .uproject 파일을 찾아 우클릭하여 컨텍스트 메뉴를 연 다음, 프로젝트 파일 생성(Generate Project Files) 을 눌러 Visual Studio 솔루션을 재생성합니다.
새 솔루션 파일에서는 기본적으로 플러그인이 활성화되어 있습니다.
JDK 환경 변수 검증
언리얼 엔진 5.3부터 AGDE와 언리얼 엔진 모두 JDK의 타깃 버전으로 OpenJDK 17.0.6 2023-01-17 이 필요합니다. 새로 설치한 Android Studio와 언리얼 엔진 5.3 이상 버전을 사용하는 경우 UE의 Android SDK 설치 프로세스에서 이 버전의 JDK를 자동으로 설치하기 때문에 추가 작업이 필요하지 않습니다. 이전 버전의 UE에서 마이그레이션하는 경우 다음 단계를 따르세요.
-
시스템 세팅(System Settings) 을 열고 환경 변수(Environment Variables) 를 클릭합니다.
-
AGDE_JAVA_HOME이라는 환경 변수가 있으면 삭제합니다. -
JAVA_HOME이C:\Program Files\Android\Android Studio\jbr을 가리켜야 합니다.
이전 버전 언리얼 엔진의 설치를 유지해야 하는 경우 Android SDK 및 NDK 설정을 읽고 UE에서 SDK 경로를 수동으로 타기팅하는 방법을 알아보세요. 이전 버전의 언리얼 엔진을 사용 중인 경우 해당 버전의 문서를 참조하세요.
AGDE로 프로젝트 실행
AGDE는 Android 디바이스에서 디버깅 또는 언리얼 엔진 애플리케이션과의 연결이 가능합니다. 이를 위해 Visual Studio에서 몇 가지 환경설정 옵션을 설정해야 하고, Android 프로젝트의 코드를 컴파일할 수 있지만 콘텐츠를 쿠킹할 수 없으므로 AGDE 사용 전에 APK를 패키징해야 합니다. 다음 단계를 따라 디바이스에서 프로젝트를 실행합니다.
-
BuildCookRun 명령을 사용하여 Android에 맞춰 프로젝트를 패키징합니다. 언리얼 에디터 에서 턴키(Turnkey) 또는 플랫폼(Platforms) 드롭다운을 사용할 수도 있습니다.
쿠킹 및 패키징 프로세스에 관한 자세한 정보는 빌드 작업 및 콘텐츠 쿠킹을 참조하세요.
-
프로젝트의 Visual Studio 솔루션을 엽니다.
-
솔루션 구성(Solution Configuration) 을 DebugGame 으로 설정하고 솔루션 플랫폼(Solution Platform) 을 Android 로 설정합니다.
-
USB 케이블을 사용하여 테스트할 Android 디바이스를 컴퓨터에 연결합니다. 디바이스에서 USB 디버깅 권한 또는 컴퓨터의 디바이스 데이터 액세스 권한 부여를 요청하는 경우 권한을 부여합니다.
USB 연결을 사용할 때 컴퓨터의 케이블과 포트 모두 데이터를 지원해야 합니다.
-
프로젝트를 빌드 및 디버깅하는 버튼에 디바이스의 이름이 표시될 것입니다. 버튼을 클릭하거나 F5 를 눌러 디버깅을 시작합니다. 디버거 실행을 기다려야 할 수 있습니다.
SIGILL 오류가 발생하면 F5를 눌러 오류를 건너뛰고 AGDE를 계속 실행하세요.
프로젝트가 디바이스에서 빌드 및 실행되고, Windows 애플리케이션에서와 마찬가지로 Visual Studio의 디버깅 툴을 사용할 수 있습니다.
애플리케이션에 AGDE 연결
언리얼 엔진 애플리케이션의 실행 중인 인스턴스에 연결하려면 다음 단계를 따르세요.
-
툴바의 디버그(Debug) 드롭다운을 클릭하고 프로세스에 연결(Attach to Process) 을 클릭합니다.
-
연결 유형(Connection Type) 을 Android Game Development Extension 으로 설정합니다.
-
연결 대상(Connection Target) 드롭다운을 클릭하고 디바이스 항목을 클릭합니다.
-
애플리케이션에 대한 프로세스를 선택하고, 연결(Attach) 을 클릭합니다.
문제 해결
이 섹션에서는 AGDE로 디버깅 시 발생할 수 있는 문제를 수정하고 해결하는 팁을 제공합니다.
Android 14 디바이스의 어서트 수정
Android 14 디바이스에서 실행 시 AGDE가 어서트를 발생시킬 수 있습니다. 이 어서트를 수정하려면 다음 단계를 따릅니다.
-
Visual Studio에서 프로젝트의 환경설정 프로퍼티(Configuration Properties) 를 열고 디버깅(Debugging) 을 클릭합니다.
-
LLDB Post Attach 명령에 다음을 추가합니다.
LLDB Post Attach 명령
process handle --pass true --stop false --notify true SIGBUS
환경설정 프로퍼티 > 디버깅에서 LLDB Post Attach 명령에 위의 텍스트를 입력합니다.
추가 정보
AGDE의 기능에 대한 추가 정보는 다음 문서를 참조하세요.