English · Deutsch

grn2glb

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

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

Большинство текстур Sacred хранит не в модели, а отдельными файлами. Для таких слотов библиотека называет имя файла, а пиксели RGBA присылаете вы. Встроенные текстуры, сырые и сжатые VTex, она декодирует сама.

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

Как начать

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

2. Положите DLL рядом с модом и свяжите нужные функции:

   Linker linker = Linker.nativeLinker();
   SymbolLookup lib = SymbolLookup.libraryLookup(dllPath, Arena.global());
   MethodHandle open = linker.downcallHandle(lib.find("grn2glb_open").orElseThrow(),
           FunctionDescriptor.of(ADDRESS, ADDRESS, JAVA_LONG));
   MethodHandle export = linker.downcallHandle(lib.find("grn2glb_export_glb").orElseThrow(),
           FunctionDescriptor.of(JAVA_INT, ADDRESS, ADDRESS, ADDRESS));
   // grn2glb_texture_count, grn2glb_texture_file_name, grn2glb_set_texture_rgba,
   // grn2glb_free, grn2glb_close и grn2glb_last_error связываются так же.

3. Откройте модель, дайте пиксели внешним текстурам и заберите GLB:

   try (Arena arena = Arena.ofConfined()) {
       MemorySegment grn = arena.allocateFrom(JAVA_BYTE, grnBytes);
       MemorySegment model = (MemorySegment) open.invokeExact(grn, (long) grnBytes.length);
       // Для каждого слота, где grn2glb_texture_has_pixels вернула 0:
       // grn2glb_texture_file_name назовёт файл, grn2glb_set_texture_rgba примет пиксели.
       MemorySegment outData = arena.allocate(ADDRESS);
       MemorySegment outSize = arena.allocate(JAVA_LONG);
       int rc = (int) export.invokeExact(model, outData, outSize);
       MemorySegment glb = outData.get(ADDRESS, 0).reinterpret(outSize.get(JAVA_LONG, 0));
       byte[] glbBytes = glb.toArray(JAVA_BYTE);
       free.invokeExact(outData.get(ADDRESS, 0));
       close.invokeExact(model);
   }

Если open вернула NULL или код меньше нуля, grn2glb_last_error() объяснит причину. Полный контракт описан в include/grn2glb.h.

C ABI

Функция	Что делает
grn2glb_api_version()	Версия ABI. Сравните её с GRN2GLB_API_VERSION до других вызовов
grn2glb_open(data, size)	Разбирает модель из байтов и возвращает её дескриптор
grn2glb_texture_count(model)	Число слотов текстур
grn2glb_texture_name(model, slot)	Имя слота, как оно записано в GRN
grn2glb_texture_file_name(model, slot)	Имя файла текстуры, как оно записано в GRN
grn2glb_texture_format(model, slot)	Код формата: 7 — внешний файл, 4 и 5 — VTex, 0, 1 и 6 — сырые пиксели
grn2glb_texture_size(model, slot, &w, &h)	Размер текстуры в пикселях
grn2glb_texture_has_pixels(model, slot)	1, если пиксели уже есть, и 0, если их ждут от вас
grn2glb_set_texture_rgba(model, slot, rgba, w, h)	Принимает пиксели RGBA для слота
grn2glb_export_glb(model, &data, &size)	Собирает GLB в буфер
grn2glb_free(buffer)	Освобождает буфер библиотеки
grn2glb_close(model)	Закрывает модель
grn2glb_last_error()	Текст последней ошибки в текущем потоке

Имена приходят байт в байт, как их хранит GRN. В Sacred это ASCII, остальное читайте как windows-1252. Слот без пикселей попадает в GLB серым квадратом 2×2.

Что внутри моделей Sacred

Тест test_game проходит по всем 1571 моделям из PAK\models.pak и считает слоты текстур:

Формат	Код	Слотов
Внешний файл	7	1922
VTex без альфы	4	104
VTex с альфой	5	41
Сырой RGBA	1	9
Сырой RGBX	0	6

Скелет с весами есть у 1009 моделей. Сжатия DXT ни одна модель не использует, поэтому его декодер я убрал.

Ограничения

• Анимации парсер читает, но привязать к модели движение из отдельного GRN пока нельзя. Из 1571 модели анимацию в GLB получает только одна.
• Скин, суставы и веса попадают в GLB, и валидатор Khronos их принимает. Как меш деформируется в позе, ещё никто не проверял.
• Обратного направления, из GLB в GRN, здесь нет.

Сборка

Нужны 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\grn2glb.dll. Тесты test_core и test_abi игры не требуют. test_game берёт модели из игры по пути в GRN2GLB_GAME, а без игры сообщает о пропуске.

Релизы

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

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

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

Лицензия

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

Собранная grn2glb.dll содержит этот код, поэтому целиком распространяется под LGPL-2.1-or-later. Мод загружает DLL динамически через FFM (Panama), и LGPL это разрешает: сам мод может иметь любую лицензию. nlohmann/json и stb_image_write идут под своими лицензиями.