Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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.

When a plugin is active, you can access it in your code using Engine.get_singleton():

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

Note

The plugin's files have to be in the res://ios/plugins/ directory or a subdirectory, otherwise the Godot editor will not automatically detect them.

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

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

   • The configuration file format is as follow:

   [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"
   

The config section and fields are required and defined as follow:

• name: name of the 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.

  • In case you need multitarget library usage, the filename should be MyPlugin.a and .a files should be named as MyPlugin.release.a and MyPlugin.debug.a.

  • In case you use multitarget xcframework libraries, their filename in the configuration should be MyPlugin.xcframework. The .xcframework files should be named as MyPlugin.release.xcframework and MyPlugin.debug.xcframework.

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

• dependencies:

  • linked: contains a list of iOS frameworks that the iOS application should be linked with.

  • embedded: contains a list of iOS frameworks or libraries that should be both linked and embedded into the resulting iOS application.

  • system: contains a list of iOS system frameworks that are required for plugin.

  • capabilities: contains a list of iOS capabilities that is required for plugin. A list of available capabilities can be found at Apple UIRequiredDeviceCapabilities documentation page.

  • files: contains a list of files that should be copied on export. This is useful for data files or images.

  • linker_flags: contains a list of linker flags to add to the Xcode project when exporting the 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 corresponding 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.