.gui в TA: Kingdoms — деревья виджетов с разделением пробелами

TA: Kingdoms рисовала главное меню, лобби, игровой HUD и диалоговые окна по файлам .gui — своеобразному формату описания виджетов с разделением пробельными символами. Хотя внешне он похож на собственные файлы интерфейса TA (тоже .gui), формат TA:K устроен иначе, и одни файлы нельзя подставить вместо других.

---

Что перед вами#

Файл .gui — это плоская последовательность виджетов. Виджет-заголовок файла объявляет общее число виджетов и глобальные метаданные (фоновое изображение, горячие клавиши); каждый следующий виджет описывает один элемент интерфейса.

Типичный виджет выглядит так:

4 1                                       ← widget type (4 = button), unused flag (always 1)
1                                         ← unused (always 1 except in headers)
2 196 79 95 20 1 0 0 0                    ← bounds: type, X, Y, W, H, flags…
3 0 0 0 0                                 ← colour: type, R, G, B, A
1 0 0                                     ← unused (always 1 0 0)
1 14 hattfont11.gaf                       ← font: type, len, name
12 PlayerColor 2 12                       ← control name + state count
3                                         ← number of gaf frames that follow
1 17 singlemachine.gaf 14 SingleMachine0 0 18    ← disabled frame
1 17 singlemachine.gaf 14 SingleMachine0 1 18    ← pressed frame
1 17 singlemachine.gaf 14 SingleMachine0 2 18    ← released frame
3                                         ← number of strings that follow
2 0 0 2 0 4 Exit 2 0 4 Exit 3             ← state strings (disabled, pressed, up)
1 7 Default
1 12 skirmish.wav                         ← sound played when activated
1 7 Default
2 0 16 Play the Machine                   ← tooltip / mouseover help
0                                         ← number of child widgets

Токены разделяются пробельными символами. Первый токен каждого виджета — идентификатор типа виджета; всё остальное идёт по схеме, своей для каждого типа.

---

Строки с префиксом длины#

Главная хитрость формата: перед каждой строкой стоит её длина в символах — отдельным целочисленным токеном. Поэтому строки могут содержать пробелы, но парсер должен сначала прочитать длину.

1 14 MainScreen.gaf
^ ^^ ^^^^^^^^^^^^^^
│  │  │
│  │  └─ the string itself (14 characters)
│  └─ length
└─ string-flavour prefix (1 = literal string)

Пустая строка записывается как 1 0 0 (префикс, нулевая длина, а пустая полезная нагрузка означает «пустую строку»). Повторяющиеся префиксы 1/0 очень легко разобрать неверно, если просто разбить файл на токены по пробелам и начать считать, — читать нужно последовательно, в порядке виджетов.

---

Типы виджетов#

Встречающиеся идентификаторы типов виджетов:

У каждого типа фиксированная схема токенов после идентификатора типа. Каноническая схема, восстановленная Dark Rain, сохранена в исходных материалах, сопровождающих этот репозиторий.

---

Общий вид виджета#

[TYPE] 1
1
2  [X] [Y] [W] [H] 1 0 0 0
3  [colour: A R G B]
1 0 0
1 [font: length name]
[control-name length] [name] 2 3
[N]
1 [len] [gaf]  [len] [seq] [frame] 9     × N
[N]
2 0 0 2 [string set]                     × N entries inline
1 7 Default
1 [len] [activate.wav]
1 7 Default
2 0 [help length] [help text]
[child-count]

В зависимости от типа виджета меняются величина [N] и устройство набора строк; схемы в исходных материалах описывают каждый тип.

Коды выравнивания#

Внутри набора строк:

У виджета с одним состоянием вы увидите, например, 2 0 6 Player; у кнопки с тремя состояниями — все три состояния подряд, например 2 0 0 2 0 6 Player 2 3 6 Play2r 3.

---

Разбор примера — главное меню#

2 1
2 0 0 640 480 1 1 0 0
3 255 255 255 255
1 0 0
1 0
8 MainMenu 1 2
2
1 15 TitleScreen.tsf 7 JPGTest 0 9
1 15 TitleScreen.tsf 7 JPGTest 1 9
2
2 0 0 2 0 0 2
1 0
1 0
2 0 24 #Enter#Play#Esc#Previous
6

Читаем сверху вниз:

• 2 1 — виджет типа 2 (заголовок), флаг 1.
• 2 0 0 640 480 1 1 0 0 — границы от начала координат, 640×480, плюс четыре токена флагов.
• 3 255 255 255 255 — запись цвета: непрозрачный белый.
• 8 MainMenu 1 2 — имя элемента управления «MainMenu» (8 символов) и 1 2 в конце.
• Две записи TitleScreen.tsf JPGTest — фоновое изображение (две одинаковые ссылки — движку нужны обе).
• 2 0 24 #Enter#Play#Esc#Previous — привязки клавиш: Enter срабатывает на элементе с именем «Play», Esc — на «Previous».
• 6 — форма содержит 6 дочерних виджетов, которые идут сразу за ней.

Фоны TSF и GAF#

Виджет-заголовок поддерживает два источника фона:

• .tsf — текстовая форма полноцветной анимации TA:K, которую загрузчик интерфейса читает напрямую. Для статичного меню это тонкая обёртка вокруг JPG (пример с TitleScreen.tsf оборачивает TitleScreen.jpg), но тот же формат описывает и полноценные многокадровые анимации. Двоичное и текстовое устройство — в TAF / TSF; kbot разбирает обе формы и пересобирает их round-trip.
• .gaf — стандартная анимация TA: Kingdoms. Заголовок ссылается на последовательность внутри GAF, и движок проигрывает её как фон.

В любом случае формат требует указать запись изображения дважды подряд; на самом деле отрисовывается только вторая копия. Это известная особенность.

---

Подводные камни#

• Пробельные символы значимы только как разделители токенов. В файлах из комплекта Cavedog встречаются и пробелы, и табуляции; любую серию пробельных символов считайте одним разделителем.
• Число потомков должно быть точным. Виджет-рамка (тип 9), который заканчивается на 4, забирает следующие четыре виджета верхнего уровня себе в потомки. Ошибитесь в числе — и остаток формы развалится.
• Виджеты списков и полос прокрутки в файлах из комплекта игры — по сути пустые шаблоны: движок заполняет их во время выполнения из состояния скрипта. Заполнять их статически нет смысла.
• Для загрузки большинства изменённых файлов .gui в TA:K нужен ключ командной строки -disablecavedogverification. Без него движок отвергает любой файл, хеш которого не совпадает со встроенным списком.
• Одни файлы падают в распакованном виде, другие — в упакованном. Сам формат стабилен, но загрузчик движка ведёт себя по-разному для слоёв виртуальной файловой системы и для прямого доступа к каталогу. При моддинге проверяйте оба варианта.

---

См. также#

• TAF / TSF — полноцветная анимация и её текстовая форма .tsf, на которую заголовки .gui ссылаются для фонов меню.
• GAF — на анимации .taf с палитрой ссылаются повсюду в файлах .gui.
• PCX — соглашение о носителях палитр, которое TA:K использует для .taf с палитрой.
• Заметки о трудностях форматов TA:K в исходных материалах этого репозитория — практические подводные камни при переносе ресурсов TA в TA:K.
• Глоссарий.