Merge pull request #4737 from Calinou/update-ios-3.2

[3.3] Update iOS plugins documentation

getting_started/workflow/export/exporting_for_ios.rst

@@ -93,8 +93,8 @@ you will be able to continue to edit your Godot project in its current location.
 That's it! You can now edit your project in the Godot editor and build it
 in Xcode when you want to run it on a device.
 
-Services for iOS
-----------------
+Plugins for iOS
+---------------
 
-Special iOS services can be used in Godot. Check out the
-:ref:`doc_services_for_ios` page.
+Special iOS plugins can be used in Godot. Check out the
+:ref:`doc_plugins_for_ios` page.

tutorials/platform/index.rst

@@ -6,6 +6,6 @@ Platform-specific
    :name: toc-learn-features-platform
 
    android_in_app_purchases
-   services_for_ios
+   ios/index
    platform_html5
    consoles

tutorials/platform/ios/index.rst

@@ -0,0 +1,9 @@
+iOS plugins
+===========
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-plugins-ios
+
+   ios_plugin
+   plugins_for_ios

tutorials/platform/ios/ios_plugin.rst

@@ -0,0 +1,119 @@
+.. _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 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 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 library (*.a* archive file or *.xcframework* containing static libraries) 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 Plugins <https://github.com/godotengine/godot-ios-plugins>`_ Godot iOS plugins.
+
+    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`` 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 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"]
+
+            linker_flags=["-ObjC"]
+
+            [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 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 following pattern: ``KeyName="key value"``

tutorials/platform/services_for_ios.rst → tutorials/platform/ios/plugins_for_ios.rst

@@ -1,11 +1,32 @@
-.. _doc_services_for_ios:
+.. _doc_plugins_for_ios:
 
-Services for iOS
-================
+Plugins for iOS
+===============
 
-At the moment, there are two iOS APIs partially implemented, GameCenter
-and Storekit. Both use the same model of asynchronous calls explained
-below.
+At the moment Godot provides StoreKit, GameCenter, iCloud services plugins.
+They are using same model of asynchronous calls explained below.
+
+ARKit and Camera access are also provided as plugins.
+
+Accessing plugin singletons
+---------------------------
+
+To access plugin functionality, you first need to check that the plugin is
+exported and available by calling the `Engine.has_singleton()` function, which
+returns a registered singleton.
+
+Here's an example of how to do this in GDScript:
+
+::
+
+    var in_app_store
+
+    func _ready():
+        if Engine.has_singleton("InAppStore"):
+            in_app_store = Engine.get_singleton("InAppStore")
+
+        else:
+            print("iOS IAP plugin is not exported.")
 
 Asynchronous methods
 --------------------
@@ -28,7 +49,7 @@ the 'pending events' queue. Example:
 ::
 
     func on_purchase_pressed():
-        var result = InAppStore.purchase( { "product_id": "my_product" } )
+        var result = in_app_store.purchase({ "product_id": "my_product" })
         if result == OK:
             animation.play("busy") # show the "waiting for response" animation
         else:
@@ -36,8 +57,8 @@ the 'pending events' queue. Example:
 
     # put this on a 1 second timer or something
     func check_events():
-        while InAppStore.get_pending_event_count() > 0:
-            var event = InAppStore.pop_pending_event()
+        while in_app_store.get_pending_event_count() > 0:
+            var event = in_app_store.pop_pending_event()
             if event.type == "purchase":
                 if event.result == "ok":
                     show_success(event.product_id)
@@ -61,11 +82,10 @@ The pending event interface consists of two methods:
 Store Kit
 ---------
 
-Implemented in ``platform/iphone/in_app_store.mm``.
+Implemented in `Godot iOS InAppStore plugin <https://github.com/godotengine/godot-ios-plugins/blob/master/plugins/inappstore/in_app_store.mm>`_.
 
-The Store Kit API is accessible through the "InAppStore" singleton (will
-always be available from gdscript). It is initialized automatically. It
-has three methods for purchasing:
+The Store Kit API is accessible through the ``InAppStore`` singleton.
+It is initialized automatically.
 
 -  ``Error purchase(Variant p_params);``
 -  ``Error request_product_info(Variant p_params);``
@@ -173,10 +193,10 @@ The response events will be dictionaries with the following fields:
 Game Center
 -----------
 
-Implemented in ``platform/iphone/game_center.mm``.
+Implemented in `Godot iOS GameCenter plugin <https://github.com/godotengine/godot-ios-plugins/blob/master/plugins/gamecenter/game_center.mm>`_.
 
-The Game Center API is available through the "GameCenter" singleton. It
-has 9 methods:
+The Game Center API is available through the ``GameCenter`` singleton. It
+has the following methods:
 
 -  ``Error authenticate();``
 -  ``bool is_authenticated();``
@@ -448,34 +468,3 @@ On close:
       "type": "show_game_center",
       "result": "ok",
     }
-
-Multi-platform games
---------------------
-
-When working on a multi-platform game, you won't always have the
-"GameCenter" singleton available (for example when running on PC or
-Android). Because the gdscript compiler looks up the singletons at
-compile time, you can't just query the singletons to see and use what
-you need inside a conditional block, you need to also define them as
-valid identifiers (local variable or class member). This is an example
-of how to work around this in a class:
-
-::
-
-    var GameCenter = null # define it as a class member
-
-    func post_score(p_score):
-        if GameCenter == null:
-            return
-        GameCenter.post_score( { "value": p_score, "category": "my_leaderboard" } )
-
-    func check_events():
-        while GameCenter.get_pending_event_count() > 0:
-            # do something with events here
-            pass
-
-    func _ready():
-        # check if the singleton exists
-        if Globals.has_singleton("GameCenter"):
-            GameCenter = Globals.get_singleton("GameCenter")
-            # connect your timer here to the "check_events" function