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

Інтеграція з API Android

Платформа Android має численні API, а також багату екосистему сторонніх бібліотек із широким та різноманітним функціоналом, таким як push-сповіщення, аналітика, автентифікація, реклама тощо...

Це не має сенсу в самому ядрі Godot, тому Godot вже давно надав Android plugin system. Android plugin system дозволяє розробникам створювати плагіни Godot для Android за допомогою коду Java або Kotlin, який надає інтерфейс для доступу та використання API Android або сторонніх бібліотек у проектах Godot з GDScript, C# або GDExtension.

class MyAndroidSingleton(godot: Godot?) : GodotPlugin(godot) {
        @UsedByGodot
        fun doSomething(value: String) {
                // ...
        }
}

Однак написання плагіна для Android вимагає знання коду Java або Kotlin, якого більшість розробників Godot не мають. Таким чином, існує багато API Android та сторонніх бібліотек, які не мають плагіна Godot, з яким розробники могли б взаємодіяти. Фактично, це одна з головних причин, яку розробники називають для неможливості перейти на Godot з інших ігрових рушіїв.

Щоб вирішити цю проблему, ми додали у Godot 4.4 кілька інструментів, які спрощують процес доступу розробників до API Android та сторонніх бібліотек.

JavaClassWrapper (Godot Сінглтон)

JavaClassWrapper — це Godot singleton, який дозволяє створювати екземпляри класів Java / Kotlin та викликати для них методи, використовуючи лише GDScript, C# або GDExtension.

var LocalDateTime = JavaClassWrapper.wrap("java.time.LocalDateTime")
var DateTimeFormatter = JavaClassWrapper.wrap("java.time.format.DateTimeFormatter")

var datetime = LocalDateTime.now()
var formatter = DateTimeFormatter.ofPattern("dd-MM-yyyy HH:mm:ss")

print(datetime.format(formatter))

У наведеному вище фрагменті коду JavaClassWrapper використовується з GDScript для доступу до класів Java LocalDateTime та DateTimeFormatter. За допомогою JavaClassWrapper ми можемо викликати методи класів Java безпосередньо з GDScript, ніби це методи GDScript.

Плагін AndroidRuntime

JavaClassWrapper — це чудово, але для виконання багатьох завдань на Android потрібен доступ до різних об'єктів життєвого циклу/середовища виконання Android. Плагін AndroidRuntime — це вбудований плагін Godot для Android, який дозволяє це робити.

Поєднання плагіна JavaClassWrapper та AndroidRuntime дозволяє розробникам отримувати доступ до API Android та використовувати їх, не відмовляючись від GDScript або не використовуючи жодних інструментів, окрім самого Godot. Це величезний крок для впровадження Godot для розробки під Android:

  • Якщо вам потрібно зробити щось просте або використовувати лише невелику частину сторонньої бібліотеки, вам не потрібно створювати плагін

  • Це дозволяє розробникам швидко інтегрувати функціональність Android

  • Це дозволяє розробникам створювати доповнення Godot, використовуючи лише GDScript та JavaClassWrapper (Java чи Kotlin не потрібні)

Примітка

Для експорту за допомогою gradle, Godot автоматично додасть файли .jar або .aar, які він знайде в каталозі проекту addons. Тож, щоб використовувати сторонню бібліотеку, ви можете просто перемістити її файл .jar або .aar в каталог addons та викликати її метод безпосередньо з GDScript за допомогою JavaClassWrapper.

Приклад: Показати спливаюче вікно Android

# Retrieve the AndroidRuntime singleton.
var android_runtime = Engine.get_singleton("AndroidRuntime")
if android_runtime:
    # Retrieve the Android Activity instance.
    var activity = android_runtime.getActivity()

    # Create a Godot Callable to wrap the toast display logic.
    var toast_callable = func():
        # Use JavaClassWrapper to retrieve the android.widget.Toast class, then make and show a toast using the class APIs.
        var ToastClass = JavaClassWrapper.wrap("android.widget.Toast")
        ToastClass.makeText(activity, "This is a test", ToastClass.LENGTH_LONG).show()

    # Wrap the Callable in a Java Runnable and run it on the Android UI thread to show the toast.
    activity.runOnUiThread(android_runtime.createRunnableFromGodotCallable(toast_callable))

Приклад: Вібрація пристрою

# Retrieve the AndroidRuntime singleton.
var android_runtime = Engine.get_singleton("AndroidRuntime")
if android_runtime:
    # Retrieve the Android Vibrator system service and check if the device supports it.
    var vibrator_service = android_runtime.getApplicationContext().getSystemService("vibrator")
    if vibrator_service and vibrator_service.hasVibrator():
        # Configure and run a VibrationEffect.
        var VibrationEffect = JavaClassWrapper.wrap("android.os.VibrationEffect")
        var effect = VibrationEffect.createOneShot(500, VibrationEffect.DEFAULT_AMPLITUDE)
        vibrator_service.vibrate(effect)

Приклад: Доступ до внутрішніх класів

До внутрішніх класів Java можна отримати доступ за допомогою знака $:

# Accessing 'VERSION' class, which is an inner class from the 'android.os.Build' class.
var version = JavaClassWrapper.wrap("android.os.Build$VERSION")
var sdk_int = version.SDK_INT
if sdk_int == 30:
    # Do something specific on android 11 devices.
else:
    # All other devices

Приклад: Виклик конструктора

Конструктор викликається шляхом виклику методу з тим самим ім'ям, що й у класу.

Цей приклад створює намір надіслати текстове повідомлення:

# Retrieve the AndroidRuntime singleton.
var android_runtime = Engine.get_singleton("AndroidRuntime")
if android_runtime:
    var Intent = JavaClassWrapper.wrap("android.content.Intent")
    var activity = android_runtime.getActivity()
    var intent = Intent.Intent() # Call the constructor.
    intent.setAction(Intent.ACTION_SEND)
    intent.putExtra(Intent.EXTRA_TEXT, "This is a test message.")
    intent.setType("text/plain")
    activity.startActivity(intent)