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.
Sigue estas instrucciones en <https://developer.android.com/studio/projects/android-library>__ para crear un módulo de biblioteca de Android para tu complemento.
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, reemplazaimplementation
concompileOnly
en la línea de dependencia para la biblioteca del motor Godot.
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.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, yplugin.init.ClassFullName
es el nombre completo (paquete + nombre de clase) de la clase que carga el complemento.
Agrega la lógica restante para tu complemento y ejecuta el comando
gradlew build
para generar el archivoaar
del complemento. La compilación probablemente generará tanto archivosaar
dedebug
como derelease
. Dependiendo de tus necesidades, elige solo una versión (generalmente la derelease
) para proporcionar a tus usuarios.Se recomienda que el nombre del archivo
aar
siga el siguiente patrón:[PluginName]*.aar
, dondePluginName
es el nombre del complemento en PascalCase (por ejemplo:GodotPayment.release.aar
).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
oremoto
. El tipo afecta al campo binary.binario:
Si binary_type es
local
, entonces este debe ser la ruta del archivoaar
del plugin.
La ruta del archivo puede ser relativa (por ejemplo:
MyPlugin.aar
), en cuyo caso es relativa al directoriores://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 campobinary
(cuando elbinary_type
eslocal
), 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.
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 archivoaar
.Los archivos de recursos
*.gdnlib
y*.gdns
de Godot deben definirse manualmente en el directorioassets
del plugin. La ruta recomendada para estos recursos, relativa al directorioassets
, 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.