Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

애셋 라이브러리

Android 플랫폼용 Godot 엔진은 `Android 라이브러리 <https://developer.android.com/studio/projects/android-library>`_으로 사용되도록 설계되었습니다. 이 아키텍처는 Android 플랫폼에서 몇 가지 주요 기능을 활성화합니다.

• Godot 편집기 내에 Gradle 빌드 시스템을 통합하는 기능은 라이브러리 및 도구와 같은 Android 생태계의 더 많은 구성 요소를 활용할 수 있는 기능을 제공합니다.

• 엔진을 이식 가능하고 내장 가능하게 만드는 능력:

  • Android 및 모바일 XR 장치에 Godot 편집기의 포트를 활성화하는 열쇠

  • 기존 코드베이스 내에서 Godot 기능의 통합 및 재사용을 허용하는 핵심

아래에서는 이 아키텍처를 통해 구현되는 몇 가지 사용 사례와 시나리오에 대해 설명합니다.

Godot Android 라이브러리 사용하기

Godot Android 라이브러리는 AAR 아카이브 파일로 패키지되어 `문서 <https://javadoc.io/doc/org.godotengine/godot/latest/index.html>`_와 함께 `MavenCentral <https://central.sonatype.com/artifact/org.godotengine/godot>`_에서 호스팅됩니다.

이는 다음과 같은 포괄적인 사용 사례에 대해 Android 플랫폼의 Godot API 및 기능에 대한 액세스를 제공합니다.

Godot Android 플러그인

Android 플러그인은 Android 플랫폼과 생태계에서 제공하는 기능을 활용하여 Godot 엔진의 기능을 확장하는 강력한 도구입니다.

Android 플러그인은 플러그인이 엔진의 라이프사이클에 통합하고 Godot API에 액세스하는 데 사용하는 Godot Android 라이브러리에 종속된 Android 라이브러리로, 필요에 따라 엔진 동작을 업데이트/수정할 수 있는 GDExtension 지원과 같은 강력한 기능을 부여합니다.

자세한 정보는 Godot Android 플러그인을 참조하세요.

기존 Android 프로젝트에 Godot 삽입하기

Godot 엔진은 기존 Android 애플리케이션이나 라이브러리에 내장될 수 있으므로 개발자는 성숙하고 전투 테스트를 거친 코드와 라이브러리를 특정 작업에 더 적합하게 활용할 수 있습니다.

호스팅 구성요소는 Godot의 Android API를 통해 엔진 수명주기를 구동하는 역할을 담당합니다. 이러한 API는 호스트와 내장된 Godot 인스턴스 간의 양방향 통신을 제공하여 원하는 경험을 더 효과적으로 제어하는 데에도 사용할 수 있습니다.

Godot 엔진을 Android 보기로 포함하고 이를 사용하여 3D glTF 모델을 렌더링하는 샘플 Android 앱을 사용하여 이것이 어떻게 수행되는지 보여줍니다.

GLTF Viewer 샘플 앱은 `Android RecyclerView 구성 요소 <https://developer.android.com/develop/ui/views/layout/recyclerview>`_를 사용하여 `Kenney's Food Kit pack <https://kenney.nl/assets/food-kit>`_으로 채워진 glTF 항목 목록을 생성합니다. 목록의 항목을 선택하면 앱의 논리가 내장된 Godot 엔진과 상호 작용하여 선택한 glTF 항목을 3D 모델로 렌더링합니다.

샘플 앱 소스 코드는 `GitHub에서 <https://github.com/m4gr3d/Godot-Android-Samples/tree/master/apps/gltf_viewer>`_에서 찾을 수 있습니다. `읽어보기 <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/README.md>`_의 지침에 따라 빌드하고 설치하세요.

아래에서는 GLTF 뷰어 앱을 만드는 데 사용된 단계를 분석합니다.

경고

현재는 프로세스당 하나의 Godot 엔진 인스턴스만 지원됩니다. `android:process 속성 <https://developer.android.com/guide/topics/manifest/activity-element#proc>`_을 사용하여 Android 활동이 실행되는 프로세스를 구성할 수 있습니다.

경고

자동 크기 조정/방향 구성 이벤트는 지원되지 않으며 충돌이 발생할 수 있습니다. 해당 이벤트를 비활성화할 수 있습니다.

• `android:screenOrientation 속성 <https://developer.android.com/guide/topics/manifest/activity-element#screen>`_을 사용하여 특정 방향으로 잠급니다.

• 활동이 `android:configChanges 속성 <https://developer.android.com/guide/topics/manifest/activity-element#config>`_을 사용하여 이러한 구성 이벤트를 처리할 것이라고 선언합니다.

Android SDK 다운로드하기

참고

Android 샘플 앱은 `Android Studio <https://developer.android.com/studio>`_을 사용하고 `Gradle <https://developer.android.com/build>`_을 빌드 시스템으로 사용하여 생성되었습니다.

Android 생태계는 Android 앱을 만들기 위한 여러 도구, IDE, 빌드 시스템을 제공하므로 익숙한 것을 자유롭게 사용하고 이에 따라 아래 단계를 업데이트하세요(이 문서에 대한 기여도 환영합니다!).

• Android 애플리케이션 프로젝트를 설정합니다. 새로운 빈 프로젝트일 수도 있고 기존 프로젝트일 수도 있습니다.

• Godot 안드로이드 라이브러리에 대한 Maven 의존성 추가

  • gradle``를 사용하는 경우 앱 Gradle 빌드 파일의 ``dependency 섹션에 다음을 추가합니다. ``<version>``를 Godot Android 라이브러리의 최신 버전으로 업데이트하세요:

  implementation("org.godotengine:godot:<version>")
  

• gradle``를 사용하는 경우 앱 Gradle 빌드 파일의 ``android > defaultConfig 섹션 아래에 다음 aaptOptions 구성을 포함합니다. 그렇게 하면 ``gradle``가 앱 바이너리를 빌드할 때 Godot의 숨겨진 디렉터리를 포함할 수 있습니다.

  • 빌드 시스템이 숨겨진 디렉터리 포함을 지원하지 않는 경우, 프로젝트 설정에서 :ref:`Application > Config > Use Hidden Project Data Directory<class_ProjectSettings_property_application/config/use_hidden_project_data_directory>`를 선택 취소하여 숨겨진 디렉터리를 사용하지 않도록 Godot 프로젝트를 구성할 수 있습니다.

android {

  defaultConfig {
      // The default ignore pattern for the 'assets' directory includes hidden files and
      // directories which are used by Godot projects, so we override it with the following.
      aaptOptions {
          ignoreAssetsPattern "!.svn:!.git:!.gitignore:!.ds_store:!*.scc:<dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"
      }
    ...

• 만들기 / Godot 엔진 인스턴스를 호스팅할 애플리케이션의 활동을 업데이트합니다. 샘플 앱의 경우 `MainActivity <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/MainActivity.kt>`_입니다.

  • 호스트 활동은 `GodotHost 인터페이스 <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotHost.java>`_를 구현해야 합니다.

  • 샘플 앱은 `Fragments <https://developer.android.com/guide/fragments>`_을 사용하여 UI를 구성하므로 Godot Android 라이브러리에서 제공하는 조각 구성 요소인 `GodotFragment <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotFragment.java>`_를 사용하여 Godot 엔진 인스턴스를 자동으로 호스팅하고 관리합니다.

  private var godotFragment: GodotFragment? = null
  
  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
  
      setContentView(R.layout.activity_main)
  
      val currentGodotFragment = supportFragmentManager.findFragmentById(R.id.godot_fragment_container)
      if (currentGodotFragment is GodotFragment) {
          godotFragment = currentGodotFragment
      } else {
          godotFragment = GodotFragment()
          supportFragmentManager.beginTransaction()
              .replace(R.id.godot_fragment_container, godotFragment!!)
              .commitNowAllowingStateLoss()
      }
  
      ...
  

참고

Godot Android 라이브러리는 Godot 엔진 인스턴스를 자동으로 호스팅하고 관리하도록 확장할 수 있는 활동 구성 요소인 `GodotActivity <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotActivity.kt>`_도 제공합니다.

또는 애플리케이션에서 Godot 인스턴스를 직접 생성하고 이를 직접 호스팅 및 관리할 수 있습니다.

• GodotHost#getHostPlugins(...) <https://github.com/m4gr3d/Godot-Android-Samples/blob/0e3440f357f8be5b4c63a4fe75766793199a99d0/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/MainActivity.kt#L55>`_을 사용하여 샘플 앱은 :ref:`시그널 <doc_signals>`을 보내는 데 사용되는 `런타임 GodotPlugin 인스턴스 <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/AppPlugin.kt>`_를 생성합니다. ``gdscript` 논리

  • 런타임 GodotPlugin``는 ``gdscript 논리에서 JVM 메소드에 액세스하는 데 사용될 수도 있습니다. 자세한 내용은 :ref:`Godot Android 플러그인 <doc_android_plugin>`을 참조하세요.

• 애플리케이션에서 사용할 추가 로직을 추가하세요.

  • 샘플 앱의 경우 여기에는 glTF 항목 목록을 빌드하고 표시하는 데 사용되는 조각인 `ItemsSelectionFragment 조각 <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/ItemsSelectionFragment.kt>`_(및 관련 클래스) 추가가 포함됩니다.

• AndroidManifest.xml 파일을 열고 필요한 경우 `android:screenOrientation 속성 <https://developer.android.com/guide/topics/manifest/activity-element#screen>`_을 사용하여 방향을 구성합니다.

  • 필요한 경우 `android:configChanges 속성 <https://developer.android.com/guide/topics/manifest/activity-element#config>`_을 사용하여 자동 크기 조정/방향 구성 변경을 비활성화합니다.

<activity android:name=".MainActivity"
    android:screenOrientation="fullUser"
    android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"
    android:exported="true">

    ...
</activity>

프로젝트 준비하기

참고

안드로이드에서 Godot의 프로젝트 파일은 생성된 apk 바이너리의 assets 디렉터리로 내보내집니다.

우리는 Android 앱의 assets 디렉토리에 Godot 프로젝트를 생성하여 해당 아키텍처를 활용하여 Android 앱과 Godot 프로젝트를 함께 바인딩합니다.

별도의 디렉터리에 Godot 프로젝트를 생성하고 이를 PCK 또는 ZIP 파일 <https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html#pck-versus-zip-pack-file-formats>`_으로 Android 앱의 ``assets` 디렉터리로 내보낼 수도 있습니다. 이 접근 방식을 사용하려면 GodotHost#getCommandLine() <https://github.com/godotengine/godot/blob/6916349697a4339216469e9bf5899b983d78db07/platform/android/java/lib/src/org/godotengine/godot/GodotHost.java#L45>`_을 사용하여 호스팅된 Godot 엔진 인스턴스에 `--main-pack <pck_or_zip_filepath_relative_to_assets_dir>`` 인수를 전달해야 합니다.

예시:

@Override
public List<String> getCommandLine(){
    List<String> results = new ArrayList<>();
    results.addAll(super.getCommandLine());
    results.add("--main-pack");
    results.add("res://foo.pck");
    return results;
}

아래 지침과 샘플 앱은 Android 앱의 assets 디렉터리에 Godot 프로젝트를 생성하는 첫 번째 접근 방식을 따릅니다.

• 위의 **참고**에서 언급한 대로 Godot 편집기를 열고 Android 애플리케이션 프로젝트의 assets 디렉터리에 Godot 프로젝트를 직접 생성합니다(하위 폴더 없음).

  • 샘플 앱의 `Godot 프로젝트 <https://github.com/m4gr3d/Godot-Android-Samples/tree/master/apps/gltf_viewer/src/main/assets>`_를 참고하세요.

• 빌드 커스터마이징하기

  • Godot 프로젝트의 방향 설정이 Android 앱 매니페스트의 설정과 일치하는지 확인하세요.

  • Android의 경우 `textures/vram_compression/import_etc2_astc <https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-rendering-textures-vram-compression-import-etc2-astc>`_이 `true`로 설정되어 있는지 확인하세요.

• 필요에 따라 Godot 프로젝트 스크립트 논리를 업데이트하세요.

  • 샘플 앱의 경우 스크립트 로직 <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/assets/main.gd>`_은 런타임 ``GodotPlugin` 인스턴스를 쿼리하고 이를 사용하여 앱 로직에 의해 실행된 시그널에 등록합니다.

  • 앱 로직은 목록에서 항목이 선택될 때마다 시그널를 실행합니다. 시그널에는 gdscript 논리에서 모델을 렌더링하는 데 사용되는 glTF 모델의 파일 경로가 포함되어 있습니다.

  extends Node3D
  
  # Reference to the gltf model that's currently being shown.
  var current_gltf_node: Node3D = null
  
  func _ready():
    # Default asset to load when the app starts
    _load_gltf("res://gltfs/food_kit/turkey.glb")
  
    var appPlugin = Engine.get_singleton("AppPlugin")
    if appPlugin:
      print("App plugin is available")
  
      # Signal fired from the app logic to update the gltf model being shown
      appPlugin.connect("show_gltf", _load_gltf)
    else:
      print("App plugin is not available")
  
  
  # Load the gltf model specified by the given path
  func _load_gltf(gltf_path: String):
    if current_gltf_node != null:
      remove_child(current_gltf_node)
  
    current_gltf_node = load(gltf_path).instantiate()
  
    add_child(current_gltf_node)
  

Android SDK 다운로드하기

Godot 프로젝트 구성을 완료한 후 Android 앱을 빌드하고 실행하세요. 올바르게 설정되면 호스트 활동은 시작 시 내장된 Godot 엔진을 초기화합니다. Godot 엔진은 로드할 프로젝트 파일에 대해 assets 디렉터리를 확인하고(``main pack``를 찾도록 구성되지 않은 경우) 프로젝트 실행을 진행합니다.

앱이 기기에서 실행되는 동안 `Android logcat <https://developer.android.com/studio/debug/logcat>`_을 확인하여 오류나 충돌을 조사할 수 있습니다.

참고로 GLTF 뷰어 샘플 앱에 대한 `빌드 및 설치 지침 <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/README.md>`_을 확인하세요.