diff --git a/getting_started/workflow/export/exporting_for_ios.rst b/getting_started/workflow/export/exporting_for_ios.rst index db4ca3901..9b5f1fce5 100644 --- a/getting_started/workflow/export/exporting_for_ios.rst +++ b/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. diff --git a/tutorials/platform/index.rst b/tutorials/platform/index.rst index b1f9dbfec..a1af40de5 100644 --- a/tutorials/platform/index.rst +++ b/tutorials/platform/index.rst @@ -7,6 +7,5 @@ Platform-specific android_in_app_purchases ios/index - services_for_ios platform_html5 consoles diff --git a/tutorials/platform/ios/index.rst b/tutorials/platform/ios/index.rst index 413bd4a01..d8776a95a 100644 --- a/tutorials/platform/ios/index.rst +++ b/tutorials/platform/ios/index.rst @@ -6,3 +6,4 @@ iOS plugins :name: toc-tutorials-plugins-ios ios_plugin + plugins_for_ios diff --git a/tutorials/platform/ios/ios_plugin.rst b/tutorials/platform/ios/ios_plugin.rst index 67b53dc97..298a594af 100644 --- a/tutorials/platform/ios/ios_plugin.rst +++ b/tutorials/platform/ios/ios_plugin.rst @@ -10,7 +10,7 @@ iOS plugins allow you to use third-party libraries and support iOS-specific feat 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: +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``. @@ -29,7 +29,7 @@ When a plugin is active, you can access it in your using ``Engine.get_singleton( Creating an iOS plugin ---------------------- -At its core, a Godot iOS plugin is an iOS static library (*.a* archive file) with the following requirements: +At its core, a Godot iOS plugin is an iOS library (*.a* archive file or *.xcframework* that contains static libraries) with the following requirements: - The library must have a dependency on the Godot engine headers. @@ -39,7 +39,9 @@ An iOS plugin can have the same functionality as a Godot module but provides mor 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. +.. seealso:: The `Godot iOS Plugins `_ Godot iOS plugins. + + The `Godot iOS plugin template `_ gives you all the boilerplate you need to get your iOS plugin started. To build an iOS plugin: @@ -56,9 +58,11 @@ To build an iOS plugin: 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. +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: +5. iOS plugin system also support ``.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``). @@ -80,6 +84,8 @@ To build an iOS plugin: files=["data.json"] + linker_flags=["-ObjC"] + [plist] PlistKey="Some Info.plist key you might need" @@ -87,11 +93,12 @@ To build an iOS plugin: - **name**: name of the plugin - - **binary**: this should be the filepath of the plugin ``a`` file. + - **binary**: this should be the filepath of the plugin library (``a`` or ``xcframework``) 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 filepath can be relative (e.g.: ``MyPlugin.a``, ``MyPlugin.xcframework``) in which case it's relative to the directory where ``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, filename should be ``MyPlugin.a`` and ``a`` files should be named as ``MyPlugin.release.a`` and ``MyPlugin.debug.a``. + - In case of using multitarget ``xcframework`` libraries filename in configuration should be ``MyPlugin.xcframework`` and ``xcframework`` files should be named as ``MyPlugin.release.xcframework`` and ``MyPlugin.debug.xcframework``. The ``dependencies`` and ``plist`` sections are optional and defined as follow: @@ -107,4 +114,6 @@ To build an iOS plugin: - **files**: contains a list of files that should be copied on export. This is useful for data files or images. + - **linker_flags**: containts a list of linker flags that should be added to the Xcode project if plugin is exported. + - **plist**: should have keys and values that should be present in ``Info.plist`` file following pattern: ``KeyName="key value"`` diff --git a/tutorials/platform/services_for_ios.rst b/tutorials/platform/ios/plugins_for_ios.rst similarity index 86% rename from tutorials/platform/services_for_ios.rst rename to tutorials/platform/ios/plugins_for_ios.rst index 5fce59cc9..e1e99283b 100644 --- a/tutorials/platform/services_for_ios.rst +++ b/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 it's first required to use check if plugin +is exported and available with `Engine.has_singleton` function. After +that calling a `Engine.get_singleton` will return a singleton. This +is an example of how this can be done: + +:: + + var in_app_store + + func _ready(): + if Engine.has_singleton("InAppStore"): + in_app_store = Engine.get_singleton("InAppStore") + + # Plugin setup + 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 `_. -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 `_. -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,6 +468,7 @@ On close: "type": "show_game_center", "result": "ok", } +<<<<<<< HEAD:tutorials/platform/services_for_ios.rst Multi-platform games -------------------- @@ -479,3 +500,5 @@ of how to work around this in a class: if Globals.has_singleton("GameCenter"): GameCenter = Globals.get_singleton("GameCenter") # connect your timer here to the "check_events" function +======= +>>>>>>> efc0a860 (Update iOS plugins documentation):tutorials/platform/ios/plugins_for_ios.rst