Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Создание 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"

Раздел config и поля обязательны и определяются следующим образом:

  • name: имя плагина

  • binary: должен быть путём к файлу библиотеки плагина (a или xcframework).

    • Путь к файлу может быть относительным (например, MyPlugin.a, MyPlugin.xcframework), в этом случае он относительный к каталогу, где находится файл gdip.

    • Путь к файлу может быть абсолютным: res://some_path/MyPlugin.a или res://some_path/MyPlugin.xcframework.

    • Если вам нужно использовать библиотеку для нескольких целей, имя файла должно быть MyPlugin.a, а файлы .a должны называться MyPlugin.release.a и MyPlugin.debug.a.

    • Если вы используете многоцелевые библиотеки xcframework, их имя файла в конфигурации должно быть MyPlugin.xcframework. Файлы .xcframework должны называться MyPlugin.release.xcframework и MyPlugin.debug.xcframework.

Разделы dependencies и plist являются необязательными и определяются следующим образом:

  • dependencies:

    • linked: содержит список iOS-фреймворков, с которыми должно быть слинковано iOS-приложение.

    • embedded: содержит список iOS-фреймворков или библиотек, которые должны быть как слинкованы, так и встроены в результирующее iOS-приложение.

    • system: содержит список системных iOS-фреймворков, необходимых для плагина.

    • capabilities: содержит список возможностей iOS, необходимых для плагина. Список доступных возможностей можно найти на странице документации Apple UIRequiredDeviceCapabilities.

    • files: содержит список файлов, которые следует скопировать при экспорте. Это полезно для файлов данных или изображений.

    • linker_flags: содержит список флагов компоновщика для добавления в проект Xcode при экспорте плагина.

  • plist: должен содержать ключи и значения, которые должны присутствовать в файле Info.plist.

    • Каждая строка должна соответствовать шаблону: KeyName:KeyType=KeyValue

    • Поддерживаемые значения для KeyType: string, integer, boolean, raw, string_input

    • Если тип не указан (например, KeyName="KeyValue"), будет использован тип string.

    • Если используется тип raw, значение соответствующего ключа будет сохранено в Info.plist как есть.

    • Если используется тип string_input, вы сможете изменять значение в окне экспорта.