mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 17:28:58 +00:00
Edit and move ios_plugin.rst
This commit is contained in:
Nathan Lovato
@@ -6,6 +6,7 @@ Platform-specific
|
||||
:name: toc-learn-features-platform
|
||||
|
||||
android/index
|
||||
ios/index
|
||||
services_for_ios
|
||||
platform_html5
|
||||
consoles
|
||||
|
||||
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 70 KiB |
@@ -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 <https://developer.apple.com/develop/>`_ as your development environment.
|
||||
|
||||
.. seealso:: The `Godot iOS plugin template <https://github.com/naithar/godot_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 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 <https://github.com/godotengine/godot>`_.
|
||||
|
||||
- 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 <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.
|
||||
|
||||
- **plist**: should have keys and values that should be present in ``Info.plist`` file following pattern: ``KeyName="key value"``
|
||||
@@ -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 <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.
|
||||
Reference in New Issue
Block a user