Android에서 UAAL(Unity as a Library) 활용 가이드

Android에서 UAAL(Unity as a Library) 활용 

목차

1. UAAL 개요
2. 개발 환경 설정
3. Unity 프로젝트 설정
4. Android 프로젝트 통합
5. Gradle 설정
6. 매니페스트 설정
7. 코드 구현
8. 문제 해결
9. 참고 자료

---

UAAL 개요

UAAL(Unity as a Library)은 Unity 프로젝트를 Android 네이티브 애플리케이션에 라이브러리 형태로 통합하는 기술입니다. 이를 통해 기존 Android 앱에서 Unity로 개발된 게임이나 3D 콘텐츠를 실행할 수 있습니다.

주요 특징

• Android 네이티브 앱에서 Unity 콘텐츠 실행
• 버튼 클릭 등의 이벤트를 통한 Unity 화면 전환
• 두 플랫폼 간의 데이터 교환 가능
• 독립적인 프로세스 실행으로 안정성 확보

활용 사례

• 게임 기능이 포함된 일반 앱
• AR/VR 기능 통합
• 3D 시각화 도구
• 교육용 인터랙티브 콘텐츠

---

개발 환경 설정

Unity 설치 및 플랜 선택

Unity 공식 웹사이트에서 설치 시 다음과 같은 플랜을 선택할 수 있습니다:

• 학생: 전문가나 창업에 사용하는 툴과 워크플로에 대해 알아보세요
• 개인: Unity 무료 버전으로 제작을 시작하세요
• Unity Learn: 전문가가 진행하는 Live 세션과 온디맨드 교육을 활용해보세요

필수 요구사항

1. Unity 설치
   • Unity 공식 웹사이트(https://unity.com/kr)에서 다운로드
   • Personal 플랜 선택 후 설치
2. Android NDK 설치
   • IL2CPP 빌드에 필요
   • Android Developer 사이트에서 다운로드
   • NDK 경로 설정 필요
3. 필요 리소스
   • Unity-Technologies/uaal-ar-example GitHub 프로젝트
   • 안드로이드 기본 프로젝트
   • 유니티 프로젝트

Unity Hub 프로젝트 관리

Unity Hub에서 UnityProject를 생성하고 관리할 수 있습니다.

---

Unity 프로젝트 설정

Unity 에디터 환경

Unity 2019.3.4f1 버전에서 UAAL 프로젝트를 설정하는 화면입니다. 좌측 Hierarchy에서 씬 구조를 확인할 수 있습니다.

API 레벨 설정

Unity에서 Android 빌드 설정 시 중요한 API 레벨 구성:

주요 설정사항:

• 현재 선택: Android 7.0 'Nougat' (API level 24)
• 문제: API 레벨 19로 설정되어 있을 때 호환성 오류
• 해결: Minimum API Level을 19에서 24로 업데이트

빌드 오류 해결

일반적인 오류:

BuildFailedException: ARCore Required apps require a minimum SDK version of 24. Currently set to AndroidApiLevel19

해결 방법:

1. Player Settings → Other Settings → Minimum API Level 확인
2. API Level을 24 이상으로 설정
3. 프로젝트 다시 빌드

Unity 프로젝트 내보내기

1. File → Build Settings
2. Platform을 Android로 설정
3. Export Project 체크
4. 적절한 경로에 프로젝트 내보내기

---

Android 프로젝트 통합

프로젝트 구조 설정

UAAL 예제 프로젝트는 다음과 같은 구조를 가집니다:

• AndroidProject: 메인 Android 애플리케이션
• UnityProject: Unity 콘텐츠
• XcodeProject: iOS 지원 (선택사항)
• docs: 문서 폴더

Android 프로젝트 파일 구조

빌드된 Android 프로젝트에는 다음 파일들이 포함됩니다:

• build.gradle: 프로젝트 빌드 설정
• gradle.properties: Gradle 속성
• local.properties: 로컬 환경 설정
• settings.gradle: 모듈 설정
• unityLibrary: Unity 라이브러리 폴더

Unity 테스트 프로젝트 구조

Unity 테스트 앱 프로젝트 구조:

• app: 메인 애플리케이션 모듈
• gradle: Gradle 관련 파일들
• unityLibrary: Unity 라이브러리 모듈

Android Studio 프로젝트 트리

Android Studio에서 확인할 수 있는 프로젝트 구조:

• app 모듈과 unityLibrary 모듈이 분리되어 있음
• Java 소스 코드는 com.example.unity_test 패키지 하위에 위치
• MainActivity 클래스가 메인 진입점

---

Gradle 설정

settings.gradle.kts 설정

rootProject.name = "unity_test"
include(
    ":app",
    ":unityLibrary"
)

종속성 오류 해결

일반적인 종속성 오류들:

• android.arch.lifecycle.runtime-1.0.0 누락
• com.android.support.support-core-utils-26.1.0 누락
• com.google.android.gms.play-services-base-16.0.1 누락

UnityLibrary build.gradle 설정

중복 AAR 파일 처리를 위한 종속성 설정:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation(name: 'exoplayer-core', ext:'aar')
    implementation(name: 'UnityARCore', ext:'aar')
    // 중복 종속성들은 주석 처리
    // implementation(name: 'android.arch.lifecycle.runtime-1.0.0', ext:'aar')
    // implementation(name: 'com.android.support.support-core-utils-26.1.0', ext:'aar')
}

NDK 설정

Using Android NDK version 21.3.6528147 (Recommended version: 23.1)

NDK 경로 설정:

android {
    ndkPath = "path/to/your/ndk"
}

빌드 성공

성공적인 빌드 결과:

BUILD SUCCESSFUL in 22s
56 actionable tasks: 15 executed, 41 up-to-date

Gradle Scripts 구조

프로젝트의 Gradle Scripts 구조:

• build.gradle.kts (Project: unity_test)
• build.gradle.kts (Module :app)
• build.gradle (Module :unityLibrary)
• proguard-rules.pro

---

매니페스트 설정

UnityPlayerActivity 설정

<activity android:name="com.unity3d.player.UnityPlayerActivity"
    android:theme="@style/UnityThemeSelector"
    android:process=":Unity"
    android:screenOrientation="fullUser"
    android:launchMode="singleTask"
    android:configChanges="mcc|mnc|locale|touchscreen|keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize|fontScale|layoutDirection|density">
    <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
    <meta-data android:name="notch_support" android:value="true" />
</activity>

주요 설정사항:

• android:process=":Unity": Unity 독립 프로세스 실행
• Intent Filter는 제거하여 중복 앱 방지
• 메타데이터로 Unity 활동 식별

---

코드 구현

MainActivity 기본 구조

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val intent = Intent(packageContext: this, UnityPlayerActivity::class.java)
    }
}

Android Studio 레이아웃 설정

Activity Main XML 레이아웃:

Unity 임포트 및 Activity 설정

import com.unity3d.player.UnityPlayerActivity

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val intent = Intent(packageContext: this, UnityPlayerActivity::class.java)
    }
}

종속성 설정

dependencies {
    implementation(project(":unityLibrary"))

    implementation("androidx.core:core-ktx:1.9.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("com.google.android.material:material:1.10.0")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")

    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.5")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1")
}

완전한 MainActivity 구현

class MainActivity : ComponentActivity() {
    lateinit var unityIntent: Intent

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Unity 앱 인텐트 생성
        unityIntent = Intent(this, UnityPlayerActivity::class.java)

        val button = findViewById<Button>(R.id.button_start)
        button.setOnClickListener {
            startActivity(unityIntent)
        }
    }
}

Unity와의 메시지 통신

UnityPlayer 클래스를 사용하여 Unity 게임 오브젝트에 메시지를 전송할 수 있습니다:

// Unity 게임 오브젝트에 메시지 전송
// 필요한 매개변수:
// - 타겟 게임 오브젝트
// - 스크립트 메서드 이름
// - 파라미터 (문자열)
UnityPlayer.UnitySendMessage("GameObjectName", "MethodName", "parameter")

---

문제 해결

일반적인 오류와 해결책

1. API 레벨 호환성 문제

증상: Unity 프로젝트 내보내기 시 API 호환성 오류

해결: Minimum API Level을 19에서 24로 업데이트

2. Gradle 빌드 오류

증상: unityStreamingAssets 속성을 찾을 수 없음

해결:

// gradle.properties에 추가
org.gradle.parallel=true
unityStreamingAssets=

3. 중복 종속성 오류

증상: 빌드 시 중복 클래스 에러

해결: unityLibrary/libs 폴더에서 중복 AAR 파일 제거

4. NDK 경로 설정 문제

증상: IL2CPP 빌드 실패

해결:

• Android NDK 다운로드 및 설치
• build.gradle에서 NDK 경로 정확히 설정

5. 라이브러리 종속성 문제

증상: 빌드 또는 런타임 오류

해결:

• Guava 라이브러리 추가: implementation("com.google.guava:guava:31.0.1-jre")
• 중복 종속성 제거
• 라이브러리 호환성 확인

빌드 오류 해결 단계

1. Clean Project 실행
2. Rebuild Project 실행
3. Gradle 캐시 정리
4. NDK 경로 재확인
5. 종속성 충돌 해결

strings.xml 리소스 추가

<resources>
    <string name="game_view_content_description">Game View</string>
</resources>

---

참고 자료

• Uaal 관련 삽질 블로그 (Unity를 안드로이드에서 활용)

공식 리소스

• Unity 공식 웹사이트
• Unity Technologies UAAL Example
• Android NDK 다운로드

관련 프로젝트

• GitHub: rohhyungwoo/ARAD_Public
• Google Play: ARAD

추가 학습 자료

• Learn and Give 블로그
• Unity 공식 문서
• Android Developer 가이드

---

결론

UAAL을 활용한 Unity와 Android의 통합은 복잡한 설정 과정을 거쳐야 하지만, 성공적으로 구현하면 강력한 하이브리드 애플리케이션을 개발할 수 있습니다.
추가로 Unity 앱의 구성에 따라서 Build시에 다른 오류가 발생할 수 있습니다. 저의 경우 최종적으로 앱을 업로드 하려고 할때 Unity에서 개발된 library의 용량 크기가 문제가 되는 경우도 있습니다 

핵심 성공 요소

1. 정확한 API 레벨 설정: Unity와 Android 프로젝트 간의 호환성 확보
2. 세심한 Gradle 설정: 종속성 관리 및 버전 호환성 해결
3. 적절한 매니페스트 설정: 중복 앱 방지 및 프로세스 분리
4. NDK 환경 구성: IL2CPP 빌드를 위한 필수 설정

개발 워크플로우 요약

1. Unity에서 AR/3D 콘텐츠 개발
2. Android 프로젝트로 내보내기
3. Android Studio에서 통합 프로젝트 설정
4. Gradle 및 매니페스트 구성
5. MainActivity에서 Unity 연동 코드 작성
6. 빌드 및 테스트

이 가이드를 따라 단계별로 진행하면서 각 단계에서 발생할 수 있는 문제들을 해결해 나가면, 안정적인 UAAL 통합을 달성할 수 있습니다. 특히 제공된 스크린샷들을 참고하여 설정 화면과 코드 구조를 정확히 따라하는 것이 중요합니다.