diff --git a/tutorials/platform/index.rst b/tutorials/platform/index.rst index 3fbeb7161..b57ad1a97 100644 --- a/tutorials/platform/index.rst +++ b/tutorials/platform/index.rst @@ -6,6 +6,7 @@ Platform-specific :name: toc-learn-features-platform android/index + ios/index services_for_ios platform_html5 consoles diff --git a/tutorials/plugins/ios/img/ios_export_preset_plugins_section.png b/tutorials/platform/ios/img/ios_export_preset_plugins_section.png similarity index 100% rename from tutorials/plugins/ios/img/ios_export_preset_plugins_section.png rename to tutorials/platform/ios/img/ios_export_preset_plugins_section.png diff --git a/tutorials/plugins/ios/index.rst b/tutorials/platform/ios/index.rst similarity index 100% rename from tutorials/plugins/ios/index.rst rename to tutorials/platform/ios/index.rst diff --git a/tutorials/platform/ios/ios_plugin.rst b/tutorials/platform/ios/ios_plugin.rst new file mode 100644 index 000000000..67b53dc97 --- /dev/null +++ b/tutorials/platform/ios/ios_plugin.rst @@ -0,0 +1,110 @@ +.. _doc_ios_plugin: + +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 ``.a`` binary file, and possibly other dependencies. To use it, you need to: + +1. Copy the plugin's files to your Godot project's ``res://ios/plugins`` directory. You can also group files in a sub-directory, like ``res://ios/plugins/my_plugin``. + +2. The Godot 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. + +.. image:: 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 Godot iOS plugin is an iOS static library (*.a* archive file) with the following requirements: + +- The library must have a dependency on the Godot engine headers. + +- The library must come with a ``.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. + +Here are the steps to get a plugin's development started. We recommend using `Xcode `_ as your development environment. + +.. seealso:: The `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. Add the Godot 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 Godot engine source from the `Godot GitHub page `_. + + - Run SCons to generate headers. You can learn the process by reading :ref:`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 Godot. 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`` 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``. You can also build the static library with your 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 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. + + - **plist**: should have keys and values that should be present in ``Info.plist`` file following pattern: ``KeyName="key value"`` diff --git a/tutorials/plugins/ios/ios_plugin.rst b/tutorials/plugins/ios/ios_plugin.rst deleted file mode 100644 index 1374f99a7..000000000 --- a/tutorials/plugins/ios/ios_plugin.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. _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 `_ 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 `_. - - - Generate autogenerated headers by running SCons. Reference can be found at :ref:`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 `_. - - - **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 `_ - - - Contains template/example for iOS plugin as well as SCons configuration and setup Xcode project.