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.

1. Suivez ces instructions pour créer un module de bibliothèque Android pour votre plugin.

2. 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, remplacez implementation par implementation pour la ligne de dépendance de la bibliothèque du moteur Godot.

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

4. 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, et plugin.init.ClassFullName est le nom complet (paquet + nom de classe) de la classe de chargement du plugin.

5. Ajoutez la logique restante pour votre plugin et lancez la commande gradlew build pour générer le fichier aar du plugin. La compilation générera probablement à la fois un fichier debug et un fichier release aar. En fonction de vos besoins, choisissez une seule version (généralement la version release) 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).

6. 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 ou remote. Le type affecte le champ binary.

  • binary :

    • Si binary_type est local, alors cela devrait être le chemin d'accès du fichier aar 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 champ binary (quand le binary_type est local), 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 construction aar.

• Les fichiers de ressources Godot *.gdnlib et *.gdns doivent être définis manuellement dans le répertoire assets du plugin. Le chemin recommandé pour ces ressources par rapport au répertoire assets 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

• Godot Oculus Mobile plugin - Bundled gdnative resources

• Godot Google Play Billing plugin

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.