Creating iOS plugins

This page explains what iOS plugins can do for you, how to use an existing plugin, and the steps to code a new one. iOS plugins allow you to use third-party libraries and support iOS-specific features like In-App Purchases, GameCenter integration, ARKit support, and more.

Loading and using an existing plugin

.gdip configuration file, a binary file which can be either .a static library or .xcframework containing .a static libraries, and possibly other dependencies. To use it, you need to:

  1. res://ios/plugins directory. You can also group files in a sub-directory, like res://ios/plugins/my_plugin.
  2. .gdip files inside res://ios/plugins and its subdirectories.
  3. You can find and activate detected plugins by going to Project -> Export… -> iOS and in the Options tab, scrolling to the Plugins section. Engine.get_singleton():
    1. if Engine.has_singleton("MyPlugin"):    var singleton = Engine.get_singleton("MyPlugin")    print(singleton.foo())

    Creating an iOS plugin

    .a archive file or .xcframework containing static libraries) with the following requirements:
  • The library must have a dependency on the Godot engine headers.
  • .gdip configuration file. An iOS plugin can have the same functionality as a Godot module but provides more flexibility and doesn’t require to rebuild the engine. Xcode as your development environment. See also Godot iOS Plugins Godot iOS plugins. Godot iOS plugin template gives you all the boilerplate you need to get your iOS plugin started. To build an iOS plugin:
  1. Create an Objective-C static library for your plugin inside Xcode.
  2. HEADER_SEARCH_PATHS. You can find the setting inside the Build Settings tab:
    • Godot GitHub page.
  • Compiling for iOS. You don’t have to wait for compilation to complete to move forward as headers are generated before the engine starts to compile.
  • You should use the same header files for iOS plugins and for the iOS export template.
  1. Build Settings tab, specify the compilation flags for your static library in OTHER_CFLAGS. The most important ones are -fcxx-modules, -fmodules, and -DDEBUG if you need debug support. Other flags should be the same you use to compile Godot. For instance:
    1. -DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND
  2. .a file. You will probably need to build both debug and release target .a files. Depending on your needs, pick either or both. If you need both debug and release .a files, their name should match following pattern: [PluginName].[TargetType].a. You can also build the static library with your SCons configuration.
  3. .xcframework files. To generate one, you can use a command such as:
    1. xcodebuild -create-xcframework -library [DeviceLibrary].a -library [SimulatorLibrary].a -output [PluginName].xcframework
  4. Create a Godot iOS Plugin configuration file to help the system detect and load your plugin:
    • gdip (e.g.: MyPlugin.gdip).
  • The configuration file format is as follow:
  1. [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=42BooleanPlistKey:boolean=trueRawPlistKey:raw="<array>    <string>UIInterfaceOrientationPortrait</string></array>"StringPlistKeyToInput:string_input="Type something"

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.
  • MyPlugin.a, MyPlugin.xcframework) in which case it’s relative to the directory where the gdip file is located.
  • res://some_path/MyPlugin.a or res://some_path/MyPlugin.xcframework.
  • MyPlugin.a and .a files should be named as MyPlugin.release.a and MyPlugin.debug.a.
  • 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.

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.

  • KeyName:KeyType=KeyValue

  • KeyType are string, integer, boolean, raw, string_input
  • KeyName="KeyValue") string type will be used.
  • raw type is used value for coresponding key will be stored in Info.plist as is.
  • string_input type is used you will be able to modify value in Export window.