Плагины iOS: конфигурация и доступ из C#

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

Установка

Разместите конфигурацию и библиотеки в asset://ios/plugins, например asset://ios/plugins/my_plugin/MyPlugin.gdip рядом с MyPlugin.xcframework. Текущий экспортёр рекурсивно ищет в этом каталоге файлы .gdip. Сохраняйте это расширение: после переименования файл не обнаружится.

Загрузчик требует непустые name, binary, initialization и deinitialization, а также существующий путь к поддерживаемому бинарному файлу. Для корректного плагина создаётся параметр экспорта plugins/<name>, изначально false. Включите нужный плагин в пресете iOS. Обнаружение плагина не означает загрузку его кода в настольный редактор.

Задавайте уникальное конфигурационное name каждому плагину. Проверьте полученный проект Xcode, соберите для нужной цели, затем проверьте инициализацию и одну реальную операцию на устройстве. Одна включённая галочка этих результатов не подтверждает.

Минимальная конфигурация

Сохраните пример как MyPlugin.gdip. Это описание примерного пакета: до экспорта добавьте настоящую совместимую библиотеку с соответствующими нативными функциями входа.

[config]
name="MyPlugin"
binary="MyPlugin.xcframework"
initialization="init_my_plugin"
deinitialization="deinit_my_plugin"

[dependencies]
linked=[]
embedded=[]
system=["Foundation.framework"]
capabilities=[]
files=[]
linker_flags=[]
spm_packages=[]

[plist]
PluginLabel:string="MyPlugin"

Относительные пути binary и локальных зависимостей вычисляются от каталога конфигурации. Для файлов проекта также подходят пути asset://. Основная библиотека .a должна быть существующим файлом, .xcframework — существующим каталогом. Эта проверка обнаружения не проверяет архитектуру объектного кода, экспортированные символы или содержимое XCFramework.

Если указанный общий бинарный файл существует, он используется для обеих целей. Иначе загрузчик принимает оба каталога MyPlugin.debug.xcframework и MyPlugin.release.xcframework, выбирая по debug/release-экспорту; для .a действует та же схема имён. При переходе на отдельные варианты удалите устаревший общий бинарный файл, иначе он будет иметь приоритет. Одного варианта недостаточно для проверки пары.

Нативная реализация и зависимости

Экспортёр создаёт объявления и вызовы вида extern void init_my_plugin(); и extern void deinit_my_plugin();. Нативная реализация должна предоставить соответствующие функции и сама выполнять инициализацию, очистку и регистрацию API. Конфигурация не создаёт singleton и не определяет методы. Используйте заголовки и сгенерированные файлы той же сборки движка и шаблона; не останавливайте сборку в произвольный момент в расчёте, что все заголовки уже готовы.

Собирайте устройство и симулятор с соответствующими SDK, затем упаковывайте нужные варианты в XCFramework. Не объединяйте код iOS-устройства и iOS-Simulator в один бинарный файл только потому, что оба используют arm64. Следуйте инструкции Apple по XCFramework и руководству по сборке iOS. Универсального списка флагов компилятора для совместимости любой библиотеки поставщика нет.

При экспорте SPM-пакеты объединяются по URL с добавлением имён продуктов; текущая реализация не сообщает о конфликтующих версиях одного URL. Согласуйте версии между включёнными плагинами и проверьте сгенерированный проект. Содержимое raw копируется как задано, а строки этот загрузчик вставляет в XML без общего экранирования: проверяйте итоговый plist, особенно значения со специальными символами XML. string_input создаёт редактируемое значение экспорта, а не хранилище секретов.

Вызов зарегистрированного singleton из C#

Если нативная реализация предоставляет Engine singleton, используйте его зарегистрированное имя: оно может отличаться от конфигурационного name. Этот помощник проверяет наличие singleton и метода перед вызовом без аргументов:

using Reckfell;

public static class NativePluginBridge
{
    public static bool TryCall(StringName singletonName, StringName method, out Variant result)
    {
        result = default;
        if (!Engine.HasSingleton(singletonName))
            return false;

        var plugin = Engine.GetSingleton(singletonName);
        if (plugin is null || !plugin.HasMethod(method))
            return false;

        result = plugin.Call(method);
        return true;
    }
}

Возвращаемый bool означает, что проверки имени и метода прошли и вызов выполнен; он не проверяет успешность операции и содержимое результата. Проверяйте результат по документированному контракту плагина и освобождайте принадлежащий вам возвращённый Variant после использования. Обёртка singleton заимствована: не вызывайте для неё Free или Dispose. Методу с параметрами нужен соответствующий набор аргументов; этот помощник намеренно обрабатывает только вызовы без аргументов.

Если singleton отсутствует в настольном редакторе, показывайте недоступность функции вместо вызова. Этот помощник не добавляет нативный код iOS и не делает публикацию C# доступной на неподдерживаемой цели.

Диагностика по этапам

Конфигурация и помощник C# выполнены в установленном Runtime Windows: общий разбор ConfigFile, вызовы встроенного Engine и случаи отсутствующего singleton/метода. Это не проверка загрузчика Apple-плагинов, нативной линковки, Xcode, экспорта C# на iOS, подписи, запуска симулятора/устройства или сервиса поставщика. Эти условия остаются непроверенными.