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

An iOS plugin requires a `.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. Copy the plugin's files to your Pandemonium project's `res://ios/plugins` directory. You can also group files in a sub-directory, like `res://ios/plugins/my_plugin`.

2. The Pandemonium editor automatically detects and imports `.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.

![](img/ios_export_preset_plugins_section.png)

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

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

Creating an iOS plugin
----------------------

At its core, a Pandemonium iOS plugin is an iOS library (*.a* archive file or *.xcframework* containing static libraries) with the following requirements:

- The library must have a dependency on the Pandemonium engine headers.

- The library must come with a `.gdip` configuration file.

An iOS plugin can have the same functionality as a Pandemonium module but provides more flexibility and doesn't require to rebuild the engine.

Here are the steps to get a plugin's development started. We recommend using `Xcode ( https://developer.apple.com/develop/ )` as your development environment.

See also:
 The `Pandemonium iOS Plugins ( https://github.com/Relintai/pandemonium_engine-ios-plugins )` Pandemonium iOS plugins.

    The `Pandemonium iOS plugin template ( https://github.com/naithar/pandemonium_ios_plugin )` 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. Add the Pandemonium engine header files as a dependency for your plugin library in `HEADER_SEARCH_PATHS`. You can find the setting inside the `Build Settings` tab:

    - Download the Pandemonium engine source from the `Pandemonium GitHub page ( https://github.com/Relintai/pandemonium_engine )`.

    - Run SCons to generate headers. You can learn the process by reading `doc_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.

3. In the `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 Pandemonium. For instance:

```
    -DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND
```

4. Add the required logic for your plugin and build your library to generate a `.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.

5. The iOS plugin system also supports `.xcframework` files. To generate one, you can use a command such as:

```
    xcodebuild -create-xcframework -library [DeviceLibrary].a -library [SimulatorLibrary].a -output [PluginName].xcframework
```

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

    -   The configuration file extension must be `gdip` (e.g.: `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 ( https://developer.apple.com/documentation/bundleresources/information_property_list/uirequireddevicecapabilities )`.

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