Création de plugins iOS

Cette page explique ce que les plugins iOS peuvent faire pour vous, comment utiliser un plugin existant et les étapes pour en coder un nouveau.

Les plugins iOS vous permettent d'utiliser des bibliothèques tierces et de prendre en charge des fonctionnalités spécifiques à iOS, comme les achats en application, l'intégration de GameCenter, la prise en charge d'ARKit, etc.

Chargement et utilisation d'un plugin existant

Un plugin iOS nécessite un fichier de configuration .gdip, un fichier binaire qui peut être soit une bibliothèque statique .a soit un fichier .xcframework contenant des bibliothèques statiques .a, et éventuellement d'autres dépendances. Pour l'utiliser, vous devez :

  1. Copiez les fichiers du plugin dans le répertoire res://ios/plugins de votre projet Godot. Vous pouvez également regrouper les fichiers dans un sous-répertoire, comme res://ios/plugins/my_plugin.

  2. L'éditeur Godot détecte et importe automatiquement les fichiers .gdip dans res://ios/plugins et ses sous-répertoires.

  3. Vous pouvez trouver et activer les plugins détectés en allant dans Projet -> Exporter... -> iOS et dans l'onglet Options, faire défiler jusqu'à la section Plugins.

../../../_images/ios_export_preset_plugins_section.png

Lorsqu'un plugin est actif, vous pouvez y accéder en utilisant Engine.get_singleton() :

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

Création d'un plugin iOS

À la base, un plugin Godot iOS est une bibliothèque iOS (fichier d'archive .a ou .xcframework contenant des bibliothèques statiques) avec les exigences suivantes :

  • La bibliothèque doit avoir une dépendance sur les en-têtes du moteur Godot.

  • La bibliothèque doit être accompagnée d'un fichier de configuration .gdip.

Un plugin iOS peut avoir la même fonctionnalité qu'un module Godot mais offre plus de flexibilité et ne nécessite pas de recompiler le moteur.

Voici les étapes pour démarrer le développement d'un plugin. Nous vous recommandons d'utiliser Xcode comme environnement de développement.

Voir aussi

Les Godot iOS Plugins plugins Godot iOS.

Le modèle de plugin Godot iOS vous donne tout le "boilerplate" dont vous avez besoin pour démarrer votre plugin iOS.

Pour compiler un plugin iOS :

  1. Créez une bibliothèque statique Objective-C pour votre plugin dans Xcode.

  2. Ajoutez les fichiers header du moteur Godot comme une dépendance pour votre bibliothèque de plugins dans HEADER_SEARCH_PATHS. Vous pouvez trouver ce paramètre dans l'onglet Paramètres de compilation :

    • Téléchargez la source du moteur Godot depuis la page Godot GitHub.

    • Exécutez SCons pour générer les fichier header. Vous pouvez apprendre le processus en lisant Compiler pour iOS. Vous n'avez pas besoin d'attendre la fin de la compilation pour avancer, car les en-têtes sont générés avant que le moteur ne commence à compiler.

    • Vous devez utiliser les mêmes fichiers header pour les plugins iOS et pour le modèle d'exportation iOS.

  3. Dans l'onglet Build Settings, spécifiez les drapeaux de compilation pour votre bibliothèque statique dans OTHER_CFLAGS. Les plus importants sont -fcxx-modules, -fmodules, et -DDEBUG si vous avez besoin du support de débogage. Les autres drapeaux devraient être les mêmes que ceux que vous utilisez pour compiler Godot. Par exemple :

-DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND
  1. Ajoutez la logique requise pour votre plugin et compilez votre bibliothèque pour générer un fichier .a. Vous aurez probablement besoin de compiler les fichiers .a : debug et release. En fonction de vos besoins, choisissez l'un ou l'autre ou les deux. Si vous avez besoin à la fois des fichiers .a debug et release, leur nom doit correspondre au modèle suivant : [PluginName].[TargetType].a. Vous pouvez également compiler la bibliothèque statique avec votre configuration SCons.

  2. Le système de plugins iOS supporte également les fichiers .xcframework. Pour en générer un, vous pouvez utiliser une commande telle que :

xcodebuild -create-xcframework -library [DeviceLibrary].a -library [SimulatorLibrary].a -output [PluginName].xcframework
  1. Créez un fichier de configuration du plugin Godot iOS pour aider le système à détecter et à charger votre plugin :

    • L'extension du fichier de configuration doit être gdip (par exemple : MyPlugin.gdip).

    • Le format du fichier de configuration est le suivant :

      [config]
      name="MyPlugin"
      binary="MyPlugin.a"
      
      initialization="init_my_plugin"
      deinitialization="deinit_my_plugin"
      
      [dependencies]
      linked=[]
      embedded=[]
      system=["Foundation.framework"]
      
      capabilities=["arkit", "metal"]
      
      files=["data.json"]
      
      linker_flags=["-ObjC"]
      
      [plist]
      PlistKeyWithDefaultType="Some Info.plist key you might need"
      StringPlistKey:string="String value"
      IntegerPlistKey:integer=42
      BooleanPlistKey:boolean=true
      RawPlistKey:raw="
      <array>
          <string>UIInterfaceOrientationPortrait</string>
      </array>
      "
      StringPlistKeyToInput:string_input="Type something"
      

      La section config et les champs sont obligatoires et définis comme suit :

      • name : nom du plugin

      • binary : ceci doit être le chemin du fichier de la bibliothèque du plugin (a ou xcframework).

        • Le chemin d'accès au fichier peut être relatif (par exemple : MyPlugin.a, MyPlugin.xcframework), auquel cas il est relatif au répertoire où se trouve le fichier gdip.

        • Le chemin de fichier peut être absolu : res://some_path/MyPlugin.a ou res://some_path/MyPlugin.xcframework.

        • Si vous avez besoin d'une bibliothèque multi-cibles, le nom de fichier doit être MyPlugin.a et les fichiers .a doivent être nommés en MyPlugin.release.a et MyPlugin.debug.a.

        • Si vous utilisez des bibliothèques xcframework à cibles multiples, leur nom de fichier dans la configuration doit être MyPlugin.xcframework. Les fichiers .xcframework doivent être nommés MyPlugin.release.xcframework et MyPlugin.debug.xcframework.

      Les sections dependencies et plist sont facultatives et définies comme suit :

      • Dépendances :

        • lié : contient une liste de frameworks iOS avec lesquels l'application iOS doit être liée.

        • embedded : contient une liste de frameworks ou de bibliothèques iOS qui doivent être liés et intégrés dans l'application iOS résultante.

        • system : contient une liste des frameworks du système iOS qui sont requis pour le plugin.

        • capacités : contient une liste des capacités iOS qui est requise pour le plugin. Une liste des capacités disponibles peut être trouvée sur la page de documentation Apple UIRequiredDeviceCapabilities.

        • fichiers : contient une liste de fichiers qui doivent être copiés lors de l'exportation. Ceci est utile pour les fichiers de données ou les images.

        • linker_flags : contient une liste de drapeaux de liens(linker flags) à ajouter au projet Xcode lors de l'exportation du plugin.

      • plist: should have keys and values that should be present in Info.plist file.

        • Each line should follow pattern: KeyName:KeyType=KeyValue

        • Supported values for KeyType are string, integer, boolean, raw, string_input

        • If no type is used (e.g.: KeyName="KeyValue") string type will be used.

        • If raw type is used value for coresponding key will be stored in Info.plist as is.

        • If string_input type is used you will be able to modify value in Export window.