godot-docs/tutorials/plugins/ios/ios_plugin.rst

.. _doc_ios_plugin:

Creating iOS plugins
====================

Introduction
------------

iOS plugins are powerful tools to extend the capabilities of the Godot engine
by tapping into the functionality provided by the iOS platform and ecosystem.

In‑App Purchases, GameCenter integration or ARKit are such examples since it requires features
and capabilities that don't belong to the core feature set of a game engine:

-  Analytics
-  In-app purchases
-  Receipt validation
-  Ads
-  A/B testing
-  Login
-  Cloud saves
-  Leaderboards and scores
-  User support & feedback
-  Posting to Facebook, Twitter, etc.
-  Push notifications

iOS plugin
----------

At its core, a Godot iOS plugin is a iOS static library (*a* archive file) 
with the following caveats:

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

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

iOS plugin can have the same functionality as Godot modules, 
but provides more flexibility and doesn't require engine being rebuilt.

Building an iOS plugin
^^^^^^^^^^^^^^^^^^^^^^

**Prerequisite:** `Xcode <https://developer.apple.com/develop/>`_ is strongly recommended as the IDE to use to create iOS plugins.
The instructions below assumes that you're using Xcode.

1.  Create an Objective-C static library for your plugin inside Xcode IDE.

2.  Add the Godot engine header files as a dependency for your plugin library in ``HEADER_SEARCH_PATHS`` at ``Build Settings`` tab:

    -  Download the Godot engine source from the `Godot GitHub page <https://github.com/godotengine/godot>`_.

    -  Generate autogenerated headers by running SCons. Reference can be found at :ref:`Compiling for iOS<doc_compiling_for_ios>`. 
       You don't have to wait for compilation complition as headers are generated before engine starts actual compilation.

    -  Header files that used for plugin should be the same that was used for iOS template compilation.

3.  Specify correct compilation flags for static library in ``OTHER_CFLAGS`` at ``Build Settings`` tab.
    Most important ones are ``-fcxx-modules``, ``-fmodules``, ``-DDEBUG`` if debug is required.
    Other flags should be the same as for Godot compilation (e.g.: ``-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`` file.
    You will probably need to build both ``debug`` and ``release`` targeted ``a`` files.
    Depending on your need, pick only one or both.
    If you need both ``a`` files their name should match following pattern: ``[PluginName].[TargetType].a``.
    Static library can also be build with SCons configuration.

5.  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``).
    
    -   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"]

            [plist]
            PlistKey="Some Info.plist key you might need"
            
        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 ``a`` file.

                -   The filepath can be relative (e.g.: ``MyPlugin.a``) in which case it's relative to the directory where ``gdip`` file is located.
                -   The filepath can be absolute: ``res://some_path/MyPlugin.aar``.
                -   In case you need multitarget library usage, filename should be ``MyPlugin.a`` and ``a`` files should be name as ``MyPlugin.release.a`` and ``MyPlugin.debug.a``.
                
        The ``dependencies`` and ``plist`` sections are optional and defined as follow:

            -   **dependencies**:
        
                -   **linked**: contains a list of iOS frameworks that result iOS application should be linked with.

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

                -   **system**: contains a list of iOS system frameworks that required for plugin.

                -   **capabilities**: contains a list of iOS capabilities that is required for plugin. 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 usefull for data files or images.

            -   **plist**: should have keys and values that should be present in ``Info.plist`` file following pattern: ``KeyName="key value"``
            


Loading and using an iOS plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Move the plugin configuration file (e.g: ``MyPlugin.gdip``) and its local binary (e.g: ``MyPlugin.a``) and dependencies to the Godot project's ``res://ios/plugins`` directory or any directory inside it (e.g: ``res://ios/plugins/my_plugin``).

The Godot editor will automatically parse all ``.gdip`` files inside ``res://ios/plugins`` directory and it's subdirectories and show a list of detected and toggleable plugins in the iOS export presets window under the **Plugins** section.

.. image:: img/ios_export_preset_plugins_section.png


From your script::

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

Reference implementations
^^^^^^^^^^^^^^^^^^^^^^^^^

-   `Godot iOS plugin template <https://github.com/naithar/godot_ios_plugin>`_ 

    -  Contains template/example for iOS plugin as well as SCons configuration and setup Xcode project.