Файл .reckfellextension: загрузка библиотек
Обязательные ключи, точный выбор библиотеки по тегам и диагностика загрузки.
Файл .reckfellextension описывает загрузку нативной библиотеки. Он не компилирует C++ и не заменяет саму DLL/so/dylib. Положите описание и подходящие бинарники в проект, сохраняя структуру относительных путей.
Минимальное описание для Windows x64
Ниже описание исполняемого примера из руководства по нативной сборке. DLL должна находиться рядом с этим файлом и экспортировать точный символ reckfell_docs_init.
[configuration]
entry_symbol = "reckfell_docs_init"
compatibility_minimum = "1.0.0"
reloadable = false
[libraries]
windows.x86_64 = "./native_probe.windows.x86_64.dll"В текущем продукте обязательны entry_symbol и compatibility_minimum. Для Reckfell 1.0.0 используйте "1.0.0"; нижняя граница меньше 1.0.0 отклоняется. Наличие подходящей версии не доказывает совместимость ABI: заголовок, привязки, архитектура и реальные функции тоже должны совпадать.
Секция configuration
| Ключ | Что задаёт |
|---|---|
| entry_symbol | Имя экспортированной функции инициализации; оно должно совпадать с символом библиотеки |
| compatibility_minimum | Обязательная нижняя граница версии продукта |
| compatibility_maximum | Необязательная верхняя граница; полная запись MAJOR.MINOR.PATCH однозначнее сокращённой |
| reloadable | Разрешение перезагрузки в редакторской сборке; по умолчанию false. Нужна поддержка всей реализации, а не только флаг |
| include_tags | PackedStringArray разрешающих комбинаций тегов; достаточно совпадения одной комбинации, внутри комбинации нужны все теги |
| exclude_tags | PackedStringArray исключающих комбинаций; совпадение любой из них пропускает расширение |
| autodetect_library_prefix | Запасной поиск библиотеки по префиксу, если явная карта libraries не выбрана |
| android_aar_plugin | Признак упаковки библиотек через Android AAR-плагин при Android-экспорте; это не способ загрузить DLL другой платформы |
Не используйте reloadable как гарантию безопасной замены библиотеки с живыми объектами. Для первого расширения оставьте false и начните с обычной загрузки/выгрузки.
Как выбирается библиотека
Ключ в [libraries] — комбинация тегов через точку. Все её теги должны совпасть с признаками запуска: например, windows.x86_64 или windows.debug.x86_64.
Текущий загрузчик выбирает совпавшую запись с наибольшим числом тегов. Если совпало несколько записей с одинаковым числом тегов, сохраняется первая. Поэтому утверждение «всегда выбирается первая подходящая строка» неверно: более специфичная запись побеждает даже ниже общей.
Относительный путь отсчитывается от файла .reckfellextension, а не от текущей папки процесса. Можно указать логический asset:// путь. Один бинарник не покрывает автоматически другие ОС, архитектуры, режимы сборки и точность real_t: под каждый поддерживаемый вариант подготовьте соответствующую библиотеку и карту тегов.
Теги выбирают файл, но не преобразуют его ABI. При ошибке сначала проверьте OS.HasFeature для нужных признаков и Engine.GetArchitectureName, затем существование выбранного файла и его зависимостей.
Зависимости и иконки
В [dependencies] значения — Dictionary вида путь_библиотеки → каталог_назначения. Секция помогает экспорту разместить дополнительные библиотеки; она не устанавливает системные пакеты и не исправляет зависимости DLL. Для зависимостей выбирается первая совпавшая комбинация тегов: здесь порядок отличается от libraries. Делайте группы взаимоисключающими или ставьте более конкретные выше общих.
В [icons] ключ — точное имя зарегистрированного класса, значение — путь к иконке. Относительные пути также считаются от описания. Иконка меняет представление класса в редакторе и не регистрирует сам класс.
Диагностика по этапам
| Сообщение/симптом | Что проверить |
|---|---|
| Нет configuration/entry_symbol | Секция и точное имя ключа |
| Нет compatibility_minimum или версия отклонена | Полная версия продукта и ограничения описания |
| No ReckfellExtension library found | Теги запуска и соответствующую запись libraries |
| Библиотека найдена, но не открывается | Архитектура, путь, системные зависимости и права ОС |
| Entry point not found | Экспорт символа и отсутствие изменения имени C++ компилятором |
| Initialization returned an error | Результат функции инициализации и журнал расширения |
| Работает в редакторе, не работает у игрока | Наличие нужной библиотеки/зависимостей и тегов в реальном экспорте |
Проверяйте результат ReckfellExtensionManager.LoadExtension и журнал, затем наличие зарегистрированного класса/метода. Само чтение INI не доказывает загрузку DLL. Windows x64 пример проверен отдельной загрузкой; выбор остальных платформ, hot reload с живыми объектами и экспорт требуют своих проверок.