Work in progress

The content of this page was not yet updated for Godot 4.6 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

Создание iOS плагина

На этой странице объясняется, что могут сделать для вас плагины iOS, как использовать существующий плагин и как написать новый.

Плагины iOS позволяют использовать сторонние библиотеки и поддерживают специфичные для iOS функции, такие как Встроенные Покупки, интеграция с GameCenter, поддержка ARKit и многое другое.

Загрузка и использование существующего плагина

Для плагина iOS требуется файл конфигурации .gdip — двоичный файл, который может быть либо статической библиотекой .a, либо .xcframework, содержащим статические библиотеки .a и, возможно, другие зависимости. Чтобы использовать плагин, необходимо:

  1. Скопируйте файлы плагина в каталог res://ios/plugins вашего проекта Godot. Вы также можете сгруппировать файлы в подкаталоге, например, res://ios/plugins/my_plugin.

  2. Редактор Godot автоматически обнаруживает и импортирует файлы .gdip внутри res://ios/plugins и его подкаталогов.

  3. Вы можете найти и активировать обнаруженные плагины, перейдя в Project -> Export... -> iOS и на вкладке Options прокрутив до раздела Plugins.

../../../_images/ios_export_preset_plugins_section.png

Когда плагин активен, вы можете получить к нему доступ в своем коде, используя Engine.get_singleton():

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

Примечание

Файлы плагина должны находиться в каталоге res://ios/plugins/ или его подкаталоге, в противном случае редактор Godot не обнаружит их автоматически.

Создание iOS плагина

По своей сути плагин Godot для iOS представляет собой библиотеку iOS (архивный файл .a или .xcframework, содержащий статические библиотеки) со следующими требованиями:

  • Библиотека должна иметь зависимость от заголовочных файлов движка Godot.

  • Библиотека должна поставляться с файлом конфигурации .gdip.

Плагин iOS может иметь ту же функциональность, что и модуль Godot, но обеспечивает большую гибкость и не требует пересборки движка.

Вот шаги, которые нужно выполнить для начала разработки плагина. Мы рекомендуем использовать Xcode в качестве среды разработки.

См. также

Плагины Godot для iOS.

Шаблон плагина Godot для iOS предоставляет вам всю необходимую базу данных для запуска вашего плагина для iOS.

Для сборки iOS плагина:

  1. Создайте статическую библиотеку Objective-C для вашего плагина внутри Xcode.

  2. Добавьте заголовочные файлы движка Godot в качестве зависимости для вашей библиотеки плагинов в HEADER_SEARCH_PATHS. Этот параметр находится на вкладке Build Settings (Параметры сборки):

    • Загрузите исходный код движка Godot со страницы Godot на GitHub.

    • Запустите SCons для генерации заголовочных файлов. Подробнее о процессе можно узнать в документе Компиляция для iOS. Вам не нужно ждать завершения компиляции, чтобы продолжить, так как заголовочные файлы генерируются до начала компиляции.

    • Вам следует использовать одни и те же файлы заголовков для плагинов iOS и для шаблона экспорта iOS.

  3. На вкладке Build Settings укажите флаги компиляции для вашей статической библиотеки в параметре OTHER_CFLAGS. Наиболее важными из них являются -fcxx-modules, -fmodules, и -DDEBUG, если вам нужна поддержка отладки. Остальные флаги должны быть теми же, что и при компиляции Godot. Например:

-DPTRCALL_ENABLED -DDEBUG_ENABLED -DDEBUG_MEMORY_ALLOC -DDISABLE_FORCED_INLINE -DTYPED_METHOD_BIND

  1. Добавьте необходимую логику для вашего плагина и создайте библиотеку для генерации .a файла. Вероятно, вам потребуется создать оба файла debug и release целевые .a файлы. В зависимости от ваших потребностей, выберите один из них или оба. Если вам нужны и отладочный, и релизный .a файлы, их имя должно соответствовать следующему шаблону: [PluginName].[TargetType].a. Вы также можете собрать статическую библиотеку с помощью конфигурации SCons.

  2. Система плагинов iOS также поддерживает файлы .xcframework. Чтобы создать такой файл, можно использовать следующую команду:

xcodebuild -create-xcframework -library [DeviceLibrary].a -library [SimulatorLibrary].a -output [PluginName].xcframework

  1. Создайте файл конфигурации Плагина Godot iOS, чтобы помочь системе обнаружить и загрузить ваш плагин:

    • Расширение файла конфигурации должно быть gdip (например: MyPlugin.gdip).

    • Формат файла конфигурации следующий:

        [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]
    PlistKeyWithDefaultType="Some Info.plist key you might need"
    StringPlistKey:string="String value"
    IntegerPlistKey:integer=42
    BooleanPlistKey:boolean=true
    RawPlistKey:raw="
    <array>
        <string>UIInterfaceOrientationPortrait</string>
    </array>
    "
    StringPlistKeyToInput:string_input="Type something"

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.

        -   Each line should follow pattern: ``KeyName:KeyType=KeyValue``
        -   Supported values for ``KeyType`` are ``string``, ``integer``, ``boolean``, ``raw``, ``string_input``
        -   If no type is used (e.g.: ``KeyName="KeyValue"``) ``string`` type will be used.
        -   If ``raw`` type is used value for corresponding key will be stored in ``Info.plist`` as is.
        -   If ``string_input`` type is used you will be able to modify value in Export window.