Creando plugins de Android

Introducción

Los complementos de Android son herramientas poderosas para ampliar las capacidades del motor Godot al aprovechar la funcionalidad proporcionada por la plataforma y el ecosistema de Android.

La monetización de juegos móviles es un ejemplo de esto, ya que requiere características y capacidades que no forman parte del conjunto de funciones principales de un motor de juego:

  • Analíticas

  • Compras en aplicación

  • Validacion de recepción

  • Instalando rastreo

  • Agregados

  • Publicidad en video

  • Promoción cruzada

  • Divisas blandas y duras dentro del juego

  • Códigos promocionales

  • Prueba A/B

  • Login (ingreso)

  • Guardado en la nube

  • Tablas de clasificación y puntuaciones

  • Asistencia al usuario y comentarios

  • Posteando en Facebook, Twitter, etc.

  • Notificaciones Push

Plugin de Android

Aunque se introdujo en Godot 3.2, el sistema de complementos para Android recibió una importante actualización de arquitectura a partir de Godot 3.2.2. El nuevo sistema de complementos no es compatible con el anterior, pero ambos sistemas se mantienen funcionales en futuras versiones de la rama 3.2.x. Dado que anteriormente no versionábamos los sistemas de complementos para Android, el nuevo sistema ahora se denomina v1 y es el punto de partida para el ecosistema moderno de Android en Godot.

Nota: En Godot 4.0, el sistema anterior será completamente obsoleto y eliminado.

Como requisito previo, asegúrate de entender cómo configurar un entorno de compilación personalizado para Android.

En su núcleo, un complemento de Godot para Android es una biblioteca de archivos de Android (archivo aar) con las siguientes advertencias:

  • La biblioteca debe tener una dependencia de la biblioteca del motor Godot (godot-lib.<versión>.<estado>.aar). Se proporciona una versión estable para cada lanzamiento de Godot en la página de descargas de Godot.

  • La biblioteca debe incluir una etiqueta <meta-data> específicamente configurada en su archivo de manifiesto.

Compilando un plugin de Android

Requisito previo: Se recomienda encarecidamente utilizar Android Studio como el entorno de desarrollo integrado (IDE) para crear complementos de Android. Las instrucciones a continuación asumen que estás utilizando Android Studio.

  1. Sigue estas instrucciones en <https://developer.android.com/studio/projects/android-library>__ para crear un módulo de biblioteca de Android para tu complemento.

  2. Agrega la biblioteca del motor Godot como una dependencia en el módulo de tu complemento:

  • Descarga la biblioteca del motor Godot (godot-lib.<versión>.<estado>.aar) desde la página de descargas de Godot (por ejemplo: godot-lib.3.4.2.stable.release.aar).

  • Sigue estas instrucciones en para agregar la biblioteca del motor Godot como una dependencia para tu complemento.

  • En el archivo build.gradle del módulo del complemento, reemplaza implementation con compileOnly en la línea de dependencia para la biblioteca del motor Godot.

  1. Crea una nueva clase en el módulo del complemento y asegúrate de que extienda org.godotengine.godot.plugin.GodotPlugin. En tiempo de ejecución, esta clase se utilizará para instanciar un objeto singleton que será utilizado por el motor Godot para cargar, inicializar y ejecutar el complemento.

  2. Actualiza el archivo AndroidManifest.xml del complemento:

  • Abre el archivo del plugin AndroidManifest.xml.

  • Agrega la etiqueta <application></application> is esta perdido.

  • En la etiqueta <application>, agrega una etiqueta <meta-data> configurada de la siguiente manera:

    <meta-data
    android:name="org.godotengine.plugin.v1.[PluginName]"
    android:value="[plugin.init.ClassFullName]" />

    Donde PluginName es el nombre del complemento, y plugin.init.ClassFullName es el nombre completo (paquete + nombre de clase) de la clase que carga el complemento.

  1. Agrega la lógica restante para tu complemento y ejecuta el comando gradlew build para generar el archivo aar del complemento. La compilación probablemente generará tanto archivos aar de debug como de release. Dependiendo de tus necesidades, elige solo una versión (generalmente la de release) para proporcionar a tus usuarios.

    Se recomienda que el nombre del archivo aar siga el siguiente patrón: [PluginName]*.aar, donde PluginName es el nombre del complemento en PascalCase (por ejemplo: GodotPayment.release.aar).

  2. Crea un archivo de configuración para el complemento de Android de Godot para ayudar al sistema a detectar y cargar tu complemento:

  • El archivo de configuración debe tener la extensión gdap (por ejemplo: MyPlugin.gdap).

  • El formato del archivo de configuración es el siguiente:

    [config]

name="MyPlugin"
binary_type="local"
binary="MyPlugin.aar"

[dependencies]

local=["local_dep1.aar", "local_dep2.aar"]
remote=["example.plugin.android:remote-dep1:0.0.1", "example.plugin.android:remote-dep2:0.0.1"]
custom_maven_repos=["http://repo.mycompany.com/maven2"]

    La sección config y los campos son obligatorios y se definen de la siguiente manera:

    • nombre: nombre del plugin.

    • binary_type: puede ser local o remoto. El tipo afecta al campo binary.

    • binario:

      • Si binary_type es local, entonces este debe ser la ruta del archivo aar del plugin.

        • La ruta del archivo puede ser relativa (por ejemplo: MyPlugin.aar), en cuyo caso es relativa al directorio res://android/plugins.

        • La ruta del archivo puede ser absoluta: res://some_path/MyPlugin.aar.

      • Si binary_type es remote, entonces esto debería ser una declaración para una dependencia de gradle remota (por ejemplo: org.godot.example:mi-complemento:0.0.0).

    La sección dependencies y los campos son opcionales y se definen de la siguiente manera:

    • local: contiene una lista de rutas de archivo a los archivos binarios .aar locales en los que el plugin depende. De manera similar al campo binary (cuando el binary_type es local), las rutas de los archivos binarios locales pueden ser relativas o absolutas.

    • remote: contiene una lista de dependencias de gradle binarias remotas para el plugin.

    • custom_maven_repos: contiene una lista de URLs que especifican los repositorios maven personalizados requeridos para las dependencias del plugin.

Cargando y usando un plugin de Android

Mueve el archivo de configuración del plugin (por ejemplo: MyPlugin.gdap) y, si hay alguno, su archivo binario local (por ejemplo: MyPlugin.aar) y dependencias al directorio res://android/plugins del proyecto de Godot.

El editor de Godot analizará automáticamente todos los archivos .gdap en el directorio res://android/plugins y mostrará una lista de plugins detectados y conmutables en la ventana de configuración de exportación de Android, en la sección Plugins.

../../../_images/android_export_preset_plugins_section.png

Desde tu script:

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

Integrando recursos GDNative

Un plugin de Android puede definir y proporcionar recursos de GDNative en C/C++, ya sea para proporcionar funcionalidad y/o acceder a la lógica del juego. Los recursos de GDNative se pueden empaquetar dentro del archivo aar del complemento, lo que simplifica el proceso de distribución e implementación:

  • Las bibliotecas compartidas (.so) para las bibliotecas GDNative definidas se empaquetarán automáticamente mediante el sistema de compilación del archivo aar.

  • Los archivos de recursos *.gdnlib y *.gdns de Godot deben definirse manualmente en el directorio assets del plugin. La ruta recomendada para estos recursos, relativa al directorio assets, debería ser: godot/plugin/v1/[NombreDelComplemento]/.

Para las bibliotecas GDNative, el objeto singleton del plugin debe anular el método org.godotengine.godot.plugin.GodotPlugin::getPluginGDNativeLibrariesPaths() y devolver las rutas a los archivos de configuración de las bibliotecas GDNative empaquetadas (*.gdnlib). Las rutas deben ser relativas al directorio assets. En tiempo de ejecución, el plugin proporcionará estas rutas al núcleo de Godot, que las utilizará para cargar e inicializar las bibliotecas GDNative empaquetadas.

Implementaciones de referenca

Solución De Problemas

Godot falla al cargar

Revisa adb logcat en busca de posibles problemas y luego:

  • Verifica que los métodos expuestos por el complemento utilicen los siguientes tipos de datos en Java: void, boolean, int, float, java.lang.String, org.godotengine.godot.Dictionary, int[], byte[], float[], java.lang.String[].

  • Tipos más complejos de estructuras de datos todavía no están soportados.