docs(ui): describe native menu font resource bindings

2026-10-30 15:48:55 +04:00
1 parent 43269c44c3
commit 637503f32d
@@ -644,14 +644,19 @@ Native interoperability подтверждается только успешны

 Граница shell подтверждена exports `createShell/getIShell`, `IGUIServer`,
 верхнеуровневым UI-pass и файлами `ui/*.cfg`, `DATA/TextRes.cfg`,
-`gamefont.rlb` и `sprites.lib`. RsLi framing библиотек закрыт, но widget tree,
-layout rules, glyph metrics, sprite command semantics, focus/navigation и HUD
-state machine пока не восстановлены до field-level спецификации.
+`gamefont.rlb` и `sprites.lib`. Для полной GOG-сборки подтверждены раздельные
+форматы: `gamefont.rlb` читается общим RsLi reader, но его native consumer этим
+не установлен; для меню подтверждена цепочка `menu_resources.cfg` → NRes
+`font.lib` → native lookup `MENU_FONT` с получением реального font-объекта.
+`menu_resources.cfg` и шесть вариантов `MENU_FONT`/`GAME_FONT` сопоставлены с
+NRes-записями в [разборе shell и шрифтов](ui-shell.md). Остаются неизвестными
+glyph metrics и drawing, выбор dimension на фактическом дисплее `1280x1024`,
+widget tree, layout rules, sprite command semantics, focus/navigation и HUD
+state machine.

-Закрывающий эксперимент: трассировать загрузку `shell_ctrls.cfg`,
-`menu_resources.cfg`, `cursor.cfg`, `game_resources.cfg` и `hq.cfg`, сопоставить
-GUI object factories и снять command/event captures для меню, HUD, briefing и
-диалогов.
+Закрывающий эксперимент: сопоставить оставшиеся детали `shell_ctrls.cfg`,
+`cursor.cfg`, `game_resources.cfg` и `hq.cfg` с GUI object factories и снять
+command/event captures для меню, HUD, briefing и диалогов.

 ## Research, economy and properties

@@ -26,10 +26,56 @@ Win32 messages
 `sprites.lib` и `Palettes.lib`. Конфигурации задают controls/resources/cursor,
 overlays и HQ; `TextRes.cfg` связывает символические ключи с текстом.

-`gamefont.rlb` содержит две LZSS-записи (`0x040`), `sprites.lib` — 24 записи
-raw Deflate (`0x100`). `sprites.lib::INTERF8.TEX` использует известный
-`deflate_eof_plus_one` quirk. UI обязан пользоваться общим RsLi reader, а не
-отдельной похожей распаковкой.
+В demo `gamefont.rlb` содержит две LZSS-записи (`0x040`); `sprites.lib`
+содержит 24 записи raw Deflate (`0x100`) и известный `deflate_eof_plus_one`
+quirk для `INTERF8.TEX`. В полной GOG-сборке меню отдельно связывает
+`ui/menu_resources.cfg` с `ui/font.lib`, архивом NRes. Поэтому `gamefont.rlb`
+не задаёт единственный путь шрифта. Оба контейнера уже читаются общими
+[RsLi](../reference/rsli.md)- и [NRes](../reference/nres.md)-readers проекта;
+будущая UI-подсистема должна пользоваться ими, а не добавлять свою распаковку.
+
+В `menu_resources.cfg` ресурс `fonts` указывает `ui\\font.lib` с `libtype=multi`
+и `type=2`; это поля CFG, а не FourCC записей NRes. У девяти записей
+`font.lib` `type_id` равен `0x544E4F46` (`FONT`). Значение подстановки в
+`font-substitute` — строковое имя: этот CFG alias (`MENU_FONT` или `GAME_FONT`)
+связывает роль шрифта с его именем, но сам не является именем записи архива.
+Числовые ссылки находятся отдельно, в объекте `fonts`. В проверенной паре CFG и
+архива эти ссылки совпадают с исходными порядковыми номерами записей NRes
+(`EntryId`), а не с `sort_index`:
+
+| Размер CFG | Строковый alias `font-substitute` | Ссылка `fonts` | `EntryId` и запись NRes |
+| --- | --- | --- | --- |
+| `640x480` | `MENU_FONT` | `8` | `8`, `mf_640.tft` |
+| `640x480` | `GAME_FONT` | `6` | `6`, `gf_640.tft` |
+| `800x600` | `MENU_FONT` | `5` | `5`, `mf_800.tft` |
+| `800x600` | `GAME_FONT` | `3` | `3`, `gf_800.tft` |
+| `1024x768` | `MENU_FONT` | `2` | `2`, `mf_1024.tft` |
+| `1024x768` | `GAME_FONT` | `0` | `0`, `gf_1024.tft` |
+
+Пример из этой CFG: `font-substitute` связывает `MENU_FONT` со строкой
+`MENU_FONT_1024x768`, а объект `fonts` связывает уже это имя с числом `2`.
+Такое сопоставление относится только к этой конфигурации и архиву, а не является
+универсальным правилом native selector. Строка `1024x768` не доказывает выбор
+этого варианта при фактическом экране `1280x1024`.
+
+Проверены оригинальные `menu_resources.cfg` (SHA-256
+`508C3783EAF112023E46BF4617424FBB57C393BCEF328CE1B925549B0069EF97`) и
+`font.lib` (440392 bytes, SHA-256
+`E4AF5D1F0BF0464574DE654DE378766090681F610705CE53539DF9041E045D1C`).
+Шесть сопоставленных payload начинаются с `Tfnt`; это подтверждает сигнатуру
+данных, но не значение последующих полей.
+
+Связка подтверждена и в оригинальном коде. В `iron3d.dll` SHA-256
+`D1DC4EA8535E2069B0A05C9E8BE2724DD438BA44CCA7A83007D8B2E50F9E35FA` shell
+читает `shell_ctrls.cfg` в RVA `0x7410`, а инициализация в `0x78c0` читает и
+регистрирует `menu_resources.cfg` в слоте `0` ResourceManager. `services.dll` SHA-256
+`D3619DEEB4D598B16099E0263E15F9C3213F0FAA7208DC093328CFBA93FDC0EA`, RVA
+`0x92a0`, разбирает `font-substitute`, размерные значения и запись ресурса
+`type=2`. Затем `iron3d.dll` запрашивает `MENU_FONT` в RVA `0x1eb20`, ищет ресурс
+в `0x1ed06` и разыменовывает результат в `0x1ed3e`; прямая x86-трасса на
+последнем участке подтвердила ненулевой объект. Это подтверждает получение
+реального font-объекта, но не конкретной NRes-записи при `1280x1024`, её
+отрисовку или паритет шрифтов.

 Ключ ресурса, legacy path, локализованный текст и исходные bytes — четыре
 разные идентичности. Archive keys остаются ASCII-casefold; `TextRes.cfg`,
@@ -50,9 +96,9 @@ viewport, scale/letterbox policy, mouse-to-layout transform, clipping и
 z-order. Cursor, sprite и hit-test обязаны применять одно преобразование.

 Font contract включает glyph image, advance, bearing/offset, line height и
-fallback glyph. Binary glyph metrics `gamefont.rlb` пока не восстановлены:
-payload читается lossless через RsLi, а семантика устанавливается по consumer
-trace.
+fallback glyph. Содержимое `gamefont.rlb` и `Tfnt` payload записей `.tft`
+сохраняется без потери bytes через общие readers (`RsLi` и `NRes`), но семантика
+метрик и глифов ещё не восстановлена по consumer trace.

 Нормализованное событие проходит modal widget, затем shell command map; лишь
 разрешённая gameplay-команда превращается в World3D manual event. Held state и