Créer des greffons Android¶
Introduction¶
Les plugins Android sont de puissants outils pour étendre les capacités du moteur Godot en exploitant les fonctionnalités fournies par la plateforme et l'écosystème Android.
La monétisation des jeux mobiles en est un exemple, car elle nécessite des fonctionnalités et des capacités qui n'appartiennent pas au cœur d'un moteur de jeu :
Analytique
Achats intégrés
Validation des reçus
Installer le suivi
Publicités
Vidéos publicitaires
Promotion croisée
Monnaies fortes et douces dans le jeu
Codes de promotion
Tests A/B
Connexion
Les sauvegardes dans le cloud
Classements et scores
Soutien aux utilisateurs et retour d'information (User support & feedback)
Poster sur Facebook, Twitter, etc.
Push notifications
plugin Android¶
Bien qu'introduit dans Godot 3.2, le système de plugin Android a bénéficié d'une mise à jour importante de l'architecture à partir de Godot 3.2.2. Le nouveau système de plugin est rétrocompatible avec le précédent, mais les deux systèmes restent fonctionnels dans les futures versions de la branche 3.2.x. Comme précédemment nous ne versionnions pas les systèmes de plugin Android, le nouveau système est maintenant appelé v1
et constitue le point de départ de l'écosystème moderne Android de Godot.
Note : Dans Godot 4.0, le système précédent sera entièrement déprécié et supprimé.
Avant toute chose, assurez-vous de comprendre comment configurer un environnement de construction(build) personnalisé pour Android custom build environment.
Au cœur d'un plugin Godot Android se trouve une bibliothèque d'archives Android (fichier d'archives aar) avec les mises en garde suivantes :
La bibliothèque doit avoir une dépendance à la bibliothèque du moteur Godot (
godot-lib.<version>.<status>.aar
). Une version stable est mise à disposition pour chaque version de Godot sur la page de téléchargement de Godot.La bibliothèque doit inclure une balise
<meta-data>
configurée spécifiquement dans son fichier manifeste.
Compiler un plugin Android¶
Prérequis: Android Studio est fortement recommandé comme IDE à utiliser pour créer des plugins Android. Les instructions ci-dessous supposent que vous utilisez Android Studio.
Suivez ces instructions pour créer un module de bibliothèque Android pour votre plugin.
Ajoutez la bibliothèque du moteur Godot en tant que dépendance à votre module de plugin :
Téléchargez la bibliothèque du moteur Godot (
godot-lib.<version>.<status>.aar
) depuis la page de téléchargement de Godot (par exemple :godot-lib.3.4.2.stable.release.aar
).Suivez ces instructions pour ajouter la bibliothèque du moteur Godot comme dépendance à votre plugin.
Dans le fichier
build.gradle
du module de plugin, remplacezimplementation
parimplementation
pour la ligne de dépendance de la bibliothèque du moteur Godot.
Créez une nouvelle classe dans le module plugin et assurez-vous qu'elle étende
org.godotengine.godot.plugin.GodotPlugin
. Au moment de l'exécution, elle sera utilisée pour instancier un objet singleton qui sera utilisé par le moteur Godot pour charger, initialiser et exécuter le plugin.Mettez à jour le fichier du plugin
AndroidManifest.xml
:
Ouvrez le fichier du plugin
AndroidManifest.xml
.Ajoutez la balise
<application></application>
si elle est manquante.Dans la balise
<application>
, ajoutez une balise<meta-data>
configurée comme suit :<meta-data android:name="org.godotengine.plugin.v1.[PluginName]" android:value="[plugin.init.ClassFullName]" />Où
PluginName
est le nom du plugin, etplugin.init.ClassFullName
est le nom complet (paquet + nom de classe) de la classe de chargement du plugin.
Ajoutez la logique restante pour votre plugin et lancez la commande
gradlew build
pour générer le fichieraar
du plugin. La compilation générera probablement à la fois un fichierdebug
et un fichierrelease
aar
. En fonction de vos besoins, choisissez une seule version (généralement la versionrelease
) que vous fournirez à vos utilisateurs.Il est recommandé que le nom de fichier
aar
corresponde au modèle suivant :[PluginName]*.aar
oùPluginName
est le nom du plugin en PascalCase (par exemple :GodotPayment.release.aar
).Créez un fichier de configuration de plugin Godot Android pour aider le système à détecter et à charger votre plugin :
L'extension du fichier de configuration doit être
gdap
(par exemple :MyPlugin.gdap
).Le format du fichier de configuration est le suivant :
[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 section
config
et les champs sont obligatoires et définis comme suit :
name : nom du plugin.
binary_type : peut être soit
local
ouremote
. Le type affecte le champ binary.binary :
Si binary_type est
local
, alors cela devrait être le chemin d'accès du fichieraar
du plugin.
Le chemin d'accès au fichier peut être relatif (par exemple :
MyPlugin.aar
), auquel cas il est relatif au répertoire ``res://android/plugins`.Le chemin d'accès au fichier peut être absolu :
res://some_path/MyPlugin.aar
.si binary_type est
remote
, alors cela devrait être une déclaration pour un remote gradle binary (par exemple :org.godot.example:my-plugin:0.0.0
).La section et les champs
dependencies
sont facultatifs et définis comme suit :
local : contient une liste de chemins d'accès aux fichiers binaires locaux
.aar
dont dépend le plugin. Comme pour le champbinary
(quand lebinary_type
estlocal
), les chemins des fichiers binaires locaux peuvent être relatifs ou absolus.remote : contient une liste de dépendances gradle binaires distantes pour le plugin.
custom_maven_repos : contient une liste d'URLs spécifiant les dépôts maven personnalisés nécessaires aux dépendances du plugin.
Chargement et utilisation d'un plugin Android¶
Déplacez le fichier de configuration du plugin (par exemple : MyPlugin.gdap
) et, le cas échéant, son binaire local (par exemple : MyPlugin.aar
) et ses dépendances dans le répertoire res://android/plugins
du projet Godot.
L'éditeur Godot analysera automatiquement tous les fichiers .gdap
dans le répertoire res://android/plugins
et affichera une liste des plugins détectés et activables dans la fenêtre des presets d'exportation Android sous la section Plugins.
De votre script :
if Engine.has_singleton("MyPlugin"):
var singleton = Engine.get_singleton("MyPlugin")
print(singleton.myPluginFunction("World"))
Regroupement des ressources GDNatives¶
Un plugin Android peut définir et fournir des ressources C/C++ GDNatives, soit pour fournir et/ou accéder à des fonctionnalités de la logique du jeu. Les ressources GDNatives peuvent être regroupées dans le fichier aar
du plugin, ce qui simplifie le processus de distribution et de déploiement :
Les bibliothèques partagées (
.so
) pour les bibliothèques GDNatives définies seront automatiquement regroupées par le système de constructionaar
.Les fichiers de ressources Godot
*.gdnlib
et*.gdns
doivent être définis manuellement dans le répertoireassets
du plugin. Le chemin recommandé pour ces ressources par rapport au répertoireassets
doit être :godot/plugin/v1/[NomDuPlugin]/
.
Pour les bibliothèques GDNative, l'objet plugin singleton doit surcharger la méthode org.godotengine.godot.plugin.GodotPlugin::getPluginGDNativeLibrariesPaths()
, et renvoyer les chemins vers les fichiers de configuration des bibliothèques GDNative regroupées (*.gdnlib
). Les chemins doivent être relatifs au répertoire assets
. À l'exécution, le plugin fournira ces chemins au noyau Godot qui les utilisera pour charger et initialiser les bibliothèques GDNative.
Implémentations de référence¶
Dépannage¶
Godot crashes lors du chargement¶
Vérifiez les problèmes éventuels dans adb logcat
, puis :
Vérifiez que les méthodes exposées par le plugin utilisent les types Java suivants :
void
,boolean
,int
,float
,java.lang.String
,org.godotengine.godot.Dictionary
,int[]
,byte[]
,float[]
,java.lang.String[]
.Les types de données plus complexes ne sont pas pris en charge pour l'instant.