English · Deutsch

glb2grn

Библиотека, которая превращает бинарный glTF (.glb) в модели Sacred Gold формата Granny 1.2 (.grn) прямо в памяти. Она нужна модам, которые приносят в игру свои модели, и тем, кто работает над загрузчиком.

Вы передаёте байты GLB и получаете байты GRN: меши, скелет, веса скиннинга, материалы и текстуры. Файлов библиотека не читает и не пишет, так что мод сам решает, откуда взять модель и куда положить результат. Это обратное направление к grn2glb, и модель может пройти путь туда и обратно.

Как хранить каждую текстуру, решаете вы. По умолчанию библиотека сжимает встроенные картинки в VTex — формат, который Sacred использует внутри моделей. Можно сохранить сырые пиксели или вовсе не класть их в модель, а назвать файл текстуры, который загрузит игра. Так устроено большинство моделей Sacred.

glb2grn.dll — 64-битная DLL с простым C ABI. Java 22 и новее вызывает её через FFM (Panama) без JNI. CRT собран статически, поэтому игроку не нужен VC++ Redistributable.

Как начать

1. Соберите glb2grn.dll и jar, как описано в разделе «Сборка». Готовых релизов пока нет.

2. Подключите jar к моду:

   dependencies {
       implementation("dev.ancaria.glb2grn:glb2grn:0.0.0-dev")
   }

3. Сконвертируйте модель. Встроенные картинки станут текстурами VTex:

   byte[] grn = Glb2Grn.convert(glbBytes);

4. Чтобы игра загрузила текстуру из файла, выберите это для слота:

   byte[] grn = Glb2Grn.convert(glbBytes, slot ->
           TextureChoice.external("textures/" + slot.name() + ".tga"));

Если библиотека не справилась, вы получите Glb2GrnException с причиной. Полный контракт описан в include/glb2grn.h.

Java

Привязке dev.ancaria.glb2grn:glb2grn нужна Java 22 или новее. Jar несёт glb2grn.dll, при первом вызове распаковывает её во временную папку и связывает функции через FFM. Объявлять функции самому не нужно. Чтобы DLL не попадала во временную папку, задайте системное свойство glb2grn.extractDir со своей папкой до первого вызова.

Glb2Grn.convert спрашивает ваши TextureChoices о каждом слоте текстуры. Верните null — и слот останется таким, каким открылся. Для пошаговой работы откройте GlbModel: textureSlots(), setTextureFormat(...), setTextureFileName(...), exportGrn() и затем close(). Разные модели конвертируются в разных потоках одновременно.

Формат	Код	Что хранит GRN
FORMAT_VTEX_OPAQUE	4	Пиксели VTex без альфы. По умолчанию для непрозрачной картинки
FORMAT_VTEX_ALPHA	5	Пиксели VTex с альфой. По умолчанию, если у пикселя альфа ниже 250
FORMAT_RAW_RGBA	1	Сырые пиксели RGBA, по 4 байта
FORMAT_RAW_RGBX	0	Сырые пиксели, альфа не учитывается
FORMAT_EXTERNAL	7	Без пикселей, только имя файла, который загрузит игра

Картинка, которую GLB называет файлом, например hero.tga, открывается внешним слотом с этим именем. Встроенному формату нужны пиксели, поэтому такой слот его не примет.

Даже успешно сконвертированная модель могла содержать ошибки, и библиотека о них сообщает. GlbModel.warnings() перечисляет, что она пропустила или заменила, по строке на случай: картинку, которая не декодировалась, примитив не из треугольников, треугольник с индексом вне диапазона, анимацию без ключевых кадров. TextureSlot.hasError() и error() объясняют, почему картинка слота не декодировалась. Glb2Grn.convert(glb, choices, warnings) после экспорта передаёт каждое предупреждение вашему Consumer<String>.

Упакованную DLL можно заменить своей сборкой. Укажите полный путь к своей glb2grn.dll в системном свойстве glb2grn.library или в переменной окружения GLB2GRN_LIBRARY. Свойство важнее. Тогда привязка загрузит этот файл и ничего не распакует. Если названного файла нет, первый вызов завершится ошибкой, а не возьмёт упакованную DLL. Ваша сборка должна сохранить C ABI из include/glb2grn.h: при первом вызове привязка сверяет glb2grn_api_version().

C ABI

Функция	Что делает
glb2grn_api_version()	Версия ABI. Сверьте её с GLB2GRN_API_VERSION до любых других вызовов
glb2grn_open(data, size)	Читает GLB из байтов и возвращает дескриптор
glb2grn_texture_count(model)	Число слотов текстур
glb2grn_texture_name(model, slot)	Имя слота из картинки GLB
glb2grn_texture_file_name(model, slot)	Имя файла, которое GRN сохранит для слота
glb2grn_texture_format(model, slot)	Код формата, который запишет экспорт
glb2grn_texture_size(model, slot, &w, &h)	Размер картинки в пикселях, 0 без пикселей
glb2grn_texture_has_pixels(model, slot)	1, если картинка декодировалась, 0, если пикселей нет
glb2grn_texture_error(model, slot)	Почему картинка слота не декодировалась, "", если всё в порядке
glb2grn_set_texture_format(model, slot, format)	Выбирает, как экспорт сохранит слот
glb2grn_set_texture_file_name(model, slot, name)	Задаёт имя файла, которое сохранит GRN
glb2grn_export_grn(model, &data, &size)	Собирает GRN в буфер
glb2grn_warning_count(model)	Число предупреждений при открытии
glb2grn_warnings(model)	Те же предупреждения текстом, по одному в строке
glb2grn_free(buffer)	Освобождает буфер библиотеки
glb2grn_close(model)	Закрывает модель
glb2grn_last_error()	Текст последней ошибки в вызывающем потоке

Данные GLB должны лежать внутри: в чанке BIN или в data URI. Буфер, который ссылается на отдельный файл, вызывает ошибку, потому что библиотека не читает файлы. Имена проходят так, как их хранит GLB; Sacred использует ASCII.

Путь через модели игры

Тест test_game берёт все 1571 модели из PAK\models.pak, превращает каждую в GLB через grn2glb и конвертирует обратно через glb2grn. Каждая модель возвращается, и оба парсера её читают. Все 1571 сохраняют треугольники и слоты текстур. Семь теряют меши без треугольников: grn2glb не кладёт их в GLB.

Ограничения

• Ни одну сконвертированную модель ещё не загружали в игре. Тесты доказывают, что GRN читается обратно с тем же содержимым, но не то, что Sacred покажет её правильно.
• Анимации сохраняют имена, но не ключевые кадры.
• Скелетом становится только первый скин GLB. Как меш деформируется в позе, ещё никто не проверял.
• Сжатие Draco и meshopt и другие расширения, которые меняют смысл данных, приводят к ошибке.

Сборка

Нужны MSVC x64 и CMake 3.22 или новее. Из Developer Command Prompt:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

DLL появится в build\bin\glb2grn.dll. Тестам test_core и test_abi игра не нужна. test_game читает модели игры по пути из GLB2GRN_GAME и нуждается в grn2glb, склонированном рядом с этим репозиторием. Без одного из них тест отмечает себя пропущенным.

Gradle собирает Java-привязку из папки jvm, когда DLL уже есть. Он упаковывает DLL в jar, запускает тесты и публикует jar в локальный репозиторий Maven:

cd jvm
./gradlew build publishToMavenLocal

Без glb2grn.dll сборка остановится и назовёт путь, где искала.

Релизы

Я выпускаю релиз кнопкой Release в Actions с номером версии. Ни один файл не хранит версию: она живёт только в теге v<версия>. Workflow собирает DLL, запускает тесты, загружает dev.ancaria.glb2grn:glb2grn в Maven Central и ждёт, пока Central начнёт его отдавать. Затем прикрепляет к релизу на GitHub glb2grn.dll, glb2grn.jar, glb2grn.h и тексты обеих лицензий.

CI собирает и тестирует каждый push в master и каждый pull request и ничего не публикует. Порядок релизов между репозиториями описан в корневом CONTRIBUTING.

Благодарности

Спасибо karolak6612 за время, которое ушло на глубокое изучение формата Granny GRN вместе с ИИ-агентом. Эта библиотека — урезанный форк open-grn-converter, и его история коммитов сохранена здесь.

Спасибо разработчикам FFmpeg. Кодек VTex читает и пишет битовый поток Bink, который описывает их декодер, а его таблицы взяты из libavcodec/binkdata.h.

Лицензия

Исходный код распространяется под MIT, см. LICENSE. Права принадлежат karolak6612 и мне. Исключение — кодек VTex в src/codecs/vtex_*. Он основан на декодере Bink из FFmpeg (libavcodec/bink.c и binkdata.h) и распространяется под LGPL-2.1-or-later. Полный текст лицензии лежит в LICENSES/LGPL-2.1.txt.

Собранная glb2grn.dll содержит этот код, поэтому целиком распространяется под LGPL-2.1-or-later. Мод загружает DLL динамически через FFM (Panama), и LGPL это разрешает: сам мод может иметь любую лицензию. Jar несёт LICENSE, LGPL-2.1.txt и NOTICE.txt в META-INF/glb2grn, и jar, который его упаковывает, сохраняет их. В NOTICE.txt написано, как заменить DLL, — подробно это описано в разделе «Java». cgltf, nlohmann/json и stb идут под своими лицензиями.