Creating iOS plugins

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.

Loading and using an existing plugin

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())

Creating an iOS plugin

À 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 :

    • Download the Godot engine source from the Godot GitHub page.

    • 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 paramètres de compilation, spécifiez les options (flags) de compilation pour votre bibliothèque statique dans OTHER_CFLAGS. Les plus importantes sont -fcxx-modules, -fmodules, et -DDEBUG si vous avez besoin du support de débogage. Les autres options doivent être les mêmes que celles que vous utilisez pour compiler Godot. Par exemple, -DPTRCALL_ENABLED -DDEBUG_ENABLED, -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND.

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

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

  6. Create a Godot iOS Plugin configuration file to help the system detect and load your plugin:

    • The configuration file extension must be gdip (e.g.: 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]
      PlistKey="Some Info.plist key you might need"
      

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

      • name : nom du plugin

      • binary: this should be the filepath of the plugin library (a or xcframework) file.

        • The filepath can be relative (e.g.: MyPlugin.a, MyPlugin.xcframework) in which case it's relative to the directory where the gdip file is located.

        • The filepath can be absolute: res://some_path/MyPlugin.a or 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.

      The dependencies and plist sections are optional and defined as follow:

      • 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: contains a list of iOS system frameworks that are required for 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: contains a list of linker flags to add to the Xcode project when exporting the plugin.

      • plist : doit avoir des clés et des valeurs qui doivent être présentes dans le fichier Info.plist suivant le modèle : KeyName="clé valeur"