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...

Godot Android 플러그인

소개

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

예를 들어 Godot 4에서 Android 플러그인은 공급업체별 코드나 바이너리로 인해 핵심 코드베이스를 방해하지 않고 여러 Android 기반 XR 플랫폼을 지원하는 데 사용됩니다.

Android

버전 1(v1) Android 플러그인 시스템은 Godot 3에 도입되었으며 Godot 4.0 및 4.1과 호환됩니다. 이 버전을 통해 개발자는 Java, Kotlin 및 기본 기능으로 Godot 엔진을 강화할 수 있었습니다.

Godot 4.2부터 v1 아키텍처를 기반으로 구축된 Android 플러그인은 더 이상 사용되지 않습니다. 대신 Godot 4.2는 Android 플러그인을 위한 새로운 버전 2(v2) 아키텍처를 도입합니다.

텍스처

참고

Godot Android 플러그인은 :ref:`Gradle 빌드 시스템 <doc_android_gradle_build>`을 활용합니다.

이전 v1 아키텍처를 기반으로 하는 Android 플러그인은 `Android 아카이브 라이브러리 <https://developer.android.com/studio/projects/android-library#aar-contents>`_에서 계속 파생됩니다.

기본적으로 Godot Android 플러그인 v2는 :ref:`Godot Android library <doc_android_library>`에 종속된 Android 라이브러리와 사용자 정의 Android 라이브러리 매니페스트입니다.

이 아키텍처를 사용하면 Android 플러그인이 다음을 통해 엔진의 기능을 확장할 수 있습니다.

Android SDK Platform 29
플랫폼 이름.
애니메이션 트리
네이티브 라이브러리(JNI를 통해)
능동적 개발 고려사항

각 플러그인에는 :ref:`Godot Android 라이브러리 <doc_android_library>`에서 제공하는 `GodotPlugin <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L80>`_ 클래스에서 확장되는 초기화 클래스가 있습니다.

GodotPlugin 클래스는 실행 중인 Godot 인스턴스에 액세스하고 수명 주기에 연결하는 API를 제공합니다. Godot 엔진에 의해 런타임에 로드됩니다.

v2 패키징 형식

v1 Android 플러그인에는 Godot 편집기가 이를 감지하고 로드하는 데 사용되는 사용자 정의 gdap 구성 파일이 필요합니다. 그러나 이 접근 방식에는 몇 가지 단점이 있었는데, 가장 큰 이유는 유연성이 부족하고 `기존 Godot EditorExportPlugin 형식, 전달 및 설치 흐름 <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/installing_plugins.html>`_에서 벗어났다는 것입니다.

이 문제는 기존 Godot EditorExportPlugin 패키징 형식을 선호하여 gdap 패키징 및 구성 메커니즘을 더 이상 사용하지 않음으로써 v2 Android 플러그인에서 해결되었습니다. EditorExportPlugin API는 Android 플러그인을 적절하게 지원하도록 확장되었습니다.

간단한 플러그인 만들기

Github 프로젝트 템플릿은 **Godot 4.2+용 Godot Android 플러그인을 빌드하기 위한 빠른 시작**으로 https://github.com/m4gr3d/Godot-Android-Plugin-Template에 **제공**됩니다. `템플릿 README <https://github.com/m4gr3d/Godot-Android-Plugin-Template#readme>`_을 따라 자신만의 Godot Android 플러그인 프로젝트를 설정할 수 있습니다.

더 깊은 이해를 돕기 위해 프로젝트 템플릿을 만드는 데 사용되는 단계를 자세히 설명합니다.

실행한 뒤 설명 을 참고해 SDK 설정을 마치세요.
모듈의 gradle `빌드 파일 <https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/main/plugin/build.gradle.kts#L42>`_을 업데이트하여 Godot Android 라이브러리를 종속성으로 추가하세요.
dependencies { implementation("org.godotengine:godot:4.2.0.stable") }

Godot Android 라이브러리는 `MavenCentral <https://central.sonatype.com/artifact/org.godotengine/godot>`_에서 호스팅되며 각 릴리스마다 업데이트됩니다.

만들기 GodotAndroidPlugin, GodotPlugin 확장 플러그인용 초기화 클래스입니다.
- 플러그인이 GDScript에서 호출할 Kotlin 또는 Java 메서드를 노출하는 경우 @UsedByGodot 주석을 달아야 합니다. GDScript에서 호출되는 이름은 메서드 이름과 정확히 일치해야 합니다. ``snake_case``를 ``camelCase``로 강제 변환하는 **없음**이 없습니다. 예를 들어, GDScript에서:
  if Engine.has_singleton("MyPlugin"): var singleton = Engine.get_singleton("MyPlugin") print(singleton.myPluginFunction("World"))
- 플러그인이 `시그널 <https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html>`_를 사용하는 경우 init 클래스는 `GodotPlugin::getPluginSignals() <https://github.com/godotengine/godot/blob/fa3428ff25bc577d2a3433090478a6d615567056/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L302>`_을 재정의하여 사용되는 시그널 세트를 반환해야 합니다. 시그널를 내보내려면 플러그인에서 `GodotPlugin::emitSignal(...) 메서드 <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L317>`_을 사용할 수 있습니다.
다음 메타데이터로 플러그인 AndroidManifest.xml `file <https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/main/plugin/src/main/AndroidManifest.xml>`_을 업데이트합니다.
<meta-data android:name="org.godotengine.plugin.v2.[PluginName]" android:value="[plugin.init.ClassFullName]" />

어디에:

``PluginName``는 플러그인 이름입니다.

plugin.init.ClassFullName``는 플러그인 초기화 클래스의 전체 구성 요소 이름(패키지 + 클래스 이름)입니다(예: ``org.godotengine.plugin.android.template.GodotAndroidPlugin).

만들기 EditorExportPlugin 구성 <https://github.com/m4gr3d/Godot-Android-Plugin-Template/tree/main/plugin/export_scripts_template>`_을 사용하여 플러그인을 패키징합니다. 구성을 생성하는 데 사용되는 단계는 `Packaging a v2 Android plugin 섹션에서 볼 수 있습니다.

GDExtension 기능을 갖춘 v2 Android 플러그인 빌드

v1 Android 플러그인의 GDNative 지원과 유사하게 v2 Android 플러그인은 GDExtension 기능을 통합하는 기능을 지원합니다.

Github 프로젝트 템플릿은 Godot 4.2+용 GDExtension Android 플러그인을 빌드하기 위한 빠른 시작으로 https://github.com/m4gr3d/GDExtension-Android-Plugin-Template에 제공됩니다. `템플릿의 README <https://github.com/m4gr3d/GDExtension-Android-Plugin-Template#readme>`_을 따라 자신만의 Godot Android 플러그인 프로젝트를 설정할 수 있습니다.

플러그인에 대해서

v1 Android 플러그인을 v2로 마이그레이션하려는 경우 다음 단계를 따르세요.

플러그인의 매니페스트 파일을 업데이트합니다.
- org.godotengine.plugin.v1 접두사를 ``org.godotengine.plugin.v2``로 변경합니다.
Godot Android 라이브러리 빌드 종속성을 업데이트합니다:
- 원하는 경우 Godot 다운로드 페이지 <https://godotengine.org/download>`_에서 ``godot-lib.<version>.<status>.aar` 바이너리를 계속 사용할 수 있습니다. 최신 안정 버전으로 업데이트되었는지 확인하세요.
- 또는 MavenCentral이 제공하는 종속성으로 전환할 수 있습니다.

dependencies {
    implementation("org.godotengine:godot:4.2.0.stable")
}

Godot Android 라이브러리 종속성을 업데이트한 후 플러그인을 동기화하거나 빌드하고 컴파일 오류를 해결하세요.
- GodotPlugin::getGodot()``에서 제공하는 ``Godot 인스턴스는 더 이상 android.content.Context 참조에 액세스할 수 없습니다. 대신 ``GodotPlugin::getActivity()``를 사용하세요.
gdap 구성 파일을 삭제하고 Packaging a v2 Android plugin 섹션의 지침에 따라 플러그인 구성을 설정합니다.

간단한 플러그인 만들기

언급한 바와 같이, v2 Android 플러그인은 이제 EditorExportPlugin 플러그인으로 Godot 편집기에 제공되므로 `동일한 패키징 단계 <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#creating-a-plugin>`_를 많이 공유합니다.

플러그인 디렉터리 내에 플러그인 출력 바이너리를 추가합니다(예: addons/<plugin_name>/).
플러그인 디렉터리(예: addons/<plugin_name>/) 내에서 내보내기 기능을 위해 `tool 스크립트 <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#the-script-file>`_를 추가하세요.
- 생성된 스크립트는 @tool 스크립트여야 합니다. 그렇지 않으면 제대로 작동하지 않습니다.
- 내보내기 도구 스크립트는 Android 플러그인을 구성하고 Godot 편집기의 내보내기 프로세스 내에 연결하는 데 사용됩니다. 다음과 같아야 합니다.

@tool
extends EditorPlugin

# A class member to hold the editor export plugin during its lifecycle.
var export_plugin : AndroidExportPlugin

func _enter_tree():
    # Initialization of the plugin goes here.
    export_plugin = AndroidExportPlugin.new()
    add_export_plugin(export_plugin)


func _exit_tree():
    # Clean-up of the plugin goes here.
    remove_export_plugin(export_plugin)
    export_plugin = null


class AndroidExportPlugin extends EditorExportPlugin:
    # Plugin's name.
    var _plugin_name = "<plugin_name>"

    # Specifies which platform is supported by the plugin.
    func _supports_platform(platform):
        if platform is EditorExportPlatformAndroid:
            return true
        return false

    # Return the paths of the plugin's AAR binaries relative to the 'addons' directory.
    func _get_android_libraries(platform, debug):
        if debug:
            return PackedStringArray(["<paths_to_debug_android_plugin_aar_binaries>"])
        else:
            return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])

    # Return the plugin's name.
    func _get_name():
        return _plugin_name


- Here are the set of `EditorExportPlugin APIs <https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html>`_ most relevant to use in this tool script:

    - `_supports_platform <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-supports-platform>`_: returns ``true`` if the plugin supports the given platform. For Android plugins, this must return ``true`` when ``platform`` is `EditorExportPlatformAndroid <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html>`_
    - `_get_android_libraries <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-libraries>`_: retrieve the local paths of the Android libraries binaries (AAR files) provided by the plugin
    - `_get_android_dependencies <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies>`_: retrieve the set of Android maven dependencies (e.g: `org.godot.example:my-plugin:0.0.0`) provided by the plugin
    - `_get_android_dependencies_maven_repos <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies-maven-repos>`_: retrieve the urls of the maven repos for the android dependencies provided by ``_get_android_dependencies``
    - `_get_android_manifest_activity_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-activity-element-contents>`_: update the contents of the `<activity>` element in the generated Android manifest
    - `_get_android_manifest_application_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-application-element-contents>`_: update the contents of the `<application>` element in the generated Android manifest
    - `_get_android_manifest_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-element-contents>`_: update the contents of the `<manifest>` element in the generated Android manifest

    The ``_get_android_manifest_*`` methods allow the plugin to automatically provide changes
    to the app's manifest which are preserved when the Godot Editor is updated, resolving a long standing issue with v1 Android plugins.

만들기 및 plugin.cfg. 이는 플러그인에 대한 메타데이터가 포함된 INI 파일입니다.

[plugin]

name="<plugin_name>"
description="<plugin_description>"
author="<plugin_author>"
version="<plugin_version>"
script="<relative_path_to_the_export_tool_script>"

참고로 여기는 Godot Android 플러그인 프로젝트 템플릿의 폴더 구조 <https://github.com/m4gr3d/Godot-Android-Plugin-Template/tree/main/plugin/export_scripts_template>`_입니다. 빌드 시 ``export_scripts_template` 디렉터리의 내용과 생성된 플러그인 바이너리가 addons/<plugin_name> 디렉터리에 복사됩니다.

export_scripts_template/
|
+--export_plugin.gd         # export plugin tool script
|
+--plugin.cfg               # plugin INI file

GDExtension 기능으로 v2 Android 플러그인 패키징

GDExtension의 경우 `Packaging a v2 Android plugin`_와 동일한 단계를 따르고 ``plugin.cfg``와 동일한 위치에 `GDExtension 구성 파일 <https://docs.godotengine.org/en/stable/tutorials/scripting/cpp/gdextension_cpp_example.html#using-the-gdextension-module>`_을 추가합니다.

참고로 여기는 GDExtension Android 플러그인 프로젝트 템플릿의 폴더 구조 <https://github.com/m4gr3d/GDExtension-Android-Plugin-Template/tree/main/plugin/export_scripts_template>`_입니다. 빌드 시 ``export_scripts_template` 디렉터리의 내용과 생성된 플러그인 바이너리가 addons/<plugin_name> 디렉터리에 복사됩니다.

export_scripts_template/
|
+--export_plugin.gd         # export plugin tool script
|
+--plugin.cfg               # plugin INI file
|
+--plugin.gdextension       # GDExtension config file

plugin.gdextension 구성 파일은 다음과 같습니다.

[configuration]

entry_symbol = "plugin_library_init"
compatibility_minimum = "4.2"
android_aar_plugin = true

[libraries]

android.debug.arm64 = "res://addons/GDExtensionAndroidPluginTemplate/bin/debug/arm64-v8a/libGDExtensionAndroidPluginTemplate.so"
android.release.arm64 = "res://addons/GDExtensionAndroidPluginTemplate/bin/release/arm64-v8a/libGDExtensionAndroidPluginTemplate.so"
...

주목할 점은 이 GDExtension 모듈을 지정하는 android_aar_plugin 필드가 v2 Android 플러그인의 일부로 제공된다는 것입니다. 내보내기 프로세스 중에 이는 GDExtension 기본 공유 라이브러리가 Android 플러그인 AAR 바이너리에 의해 내보내졌음을 Godot 편집기에 표시합니다.

GDExtension Android 플러그인의 경우 플러그인 초기화 클래스는 GodotPlugin::getPluginGDExtensionLibrariesPaths() <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L277>`_를 재정의하고 번들 GDExtension 라이브러리 구성 파일(``*.gdextension`)에 대한 경로를 반환해야 합니다.

경로는 Android 라이브러리의 assets 디렉터리에 상대적이어야 합니다. 런타임에 플러그인은 번들 GDExtension 라이브러리를 로드하고 초기화하는 데 사용하는 Godot 엔진에 이러한 경로를 제공합니다.

간단한 플러그인 만들기

참고

Godot 4.2 이상이 필요합니다
v2 Android 플러그인을 사용하려면 `Gradle 빌드 프로세스 <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html#class-editorexportplatformandroid-property-gradle-build-use-gradle-build>`_를 사용해야 합니다.
제공된 github 프로젝트 템플릿에는 빠른 테스트를 위한 데모 Godot 프로젝트가 포함되어 있습니다.

플러그인의 출력 디렉토리(addons/<plugin_name>)를 대상 Godot 프로젝트 디렉토리에 복사하세요.
Godot 편집기에서 프로젝트를 엽니다; 에디터가 플러그인을 감지해야 합니다
Project -> Project Settings... -> ``Plugins``로 이동하여 플러그인이 활성화되어 있는지 확인하세요.
Project -> ``Install Android Build Template...``를 클릭하여 Godot Android 빌드 템플릿을 설치하세요.
Project -> ``Export...``로 이동합니다.
Export 창에서 ``Android export preset``를 생성합니다.
``Android export preset``에서 ``Gradle Build``로 스크롤하고 ``Use Gradle Build``를 ``true``로 설정합니다.
플러그인 기능에 액세스하려면 필요에 따라 프로젝트의 스크립트를 업데이트하세요. 예를 들면:

if Engine.has_singleton("MyPlugin"):
        var singleton = Engine.get_singleton("MyPlugin")
        print(singleton.myPluginFunction("World"))

연결 Android 장치를 컴퓨터에 연결하고 해당 장치에서 프로젝트를 실행합니다.

간단한 플러그인 만들기

Android 라이브러리이기도 하기 때문에 Godot v2 Android 플러그인은 EditorExportPlugin 패키징에서 제거되어 Android 앱에서 Godot Android 라이브러리 <doc_android_library>`와 함께 라이브러리로 사용할 수 있는 원시 ``AAR` 바이너리로 제공될 수 있습니다.

이 사용 사례를 대상으로 하는 경우 AAR 바이너리를 포함하는 방법에 대한 추가 지침을 포함해야 합니다(예: Android 앱 매니페스트에 대한 맞춤 추가).

구현

가이드라인

노출된 Java/Kotlin API에 대한 액세스 단순화

Godot 편집기에서 노출된 Java/Kotlin API에 더 쉽게 접근할 수 있도록 하려면 플러그인 사용자가 인터페이스할 수 있는 하나(또는 여러 개의) gdscript 래퍼 클래스를 제공하는 것이 좋습니다.

예를 들면:

class_name PluginInterface extends Object

## Interface used to access the functionality provided by this plugin.

var _plugin_name = "GDExtensionAndroidPluginTemplate"
var _plugin_singleton

func _init():
    if Engine.has_singleton(_plugin_name):
        _plugin_singleton = Engine.get_singleton(_plugin_name)
    else:
        printerr("Initialization error: unable to access the java logic")

## Print a 'Hello World' message to the logcat.
func helloWorld():
    if _plugin_singleton:
        _plugin_singleton.helloWorld()
    else:
        printerr("Initialization error")

Godot 편집기에서 GDExtension 기능 사용 지원

Godot 편집기에서 GDExtension 기능을 사용할 계획이라면, GDExtension의 기본 바이너리를 Android뿐만 아니라 개발자/사용자가 Godot 편집기를 실행하려는 OS용으로 컴파일하는 것이 좋습니다. 그렇게 하지 않으면 개발자/사용자가 Godot 편집기 내에서 플러그인에 액세스하는 코드를 작성하지 못할 수 있습니다.

여기에는 API가 편집기에 게시되도록 호스트 OS용 더미 플러그인을 생성하는 작업이 포함될 수 있습니다. 이를 수행하는 방법에 대한 참조를 위해 godot-cpp-template github 템플릿을 사용할 수 있습니다.

지원되는 형식

모든 데이터 유형이 지원됩니다. 일반적인 유형은 Godot에 해당하는 유형에 매핑되지만(예: ``String[]``는 ``PackedStringArray()``에 매핑됨), 다른 유형의 경우 `JavaClassWrapper <https://docs.godotengine.org/en/stable/tutorials/platform/android/javaclasswrapper_and_androidruntimeplugin.html#javaclasswrapper-godot-singleton>`_을 사용하여 액세스할 수 있습니다.

로드 시 Godot가 충돌함

`adb logcat <https://developer.android.com/tools/logcat>`_에서 가능한 문제를 확인하세요.