.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

Токени розділено пробільними символами. Перший токен кожного віджета — ID типу віджета; усе подальше підпорядковане схемі, своїй для кожного типу.

---

Рядки з префіксом довжини#

Найважливіший прийом цього формату: перед кожним рядком стоїть його довжина в символах як окремий цілочисловий токен. Це означає, що рядки можуть містити пробіли — але парсер мусить спершу прочитати довжину.

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

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

---

Типи віджетів#

Виявлені ID типів віджетів:

Кожен тип має фіксовану схему токенів після ID типу. Канонічну схему, відновлену реверс-інжинірингом 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; для кнопки з 3 станами — усі три стани поспіль, наприклад 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), але той самий формат описує й повноцінні багатокадрові анімації. Двійкову й текстову структуру, які kbot розбирає й проводить через round-trip, див. на сторінці TAF / TSF.
• .gaf — стандартна анімація TA: Kingdoms. Заголовок посилається на послідовність усередині GAF; рушій відтворює її як фон.

В обох випадках формат вимагає, щоб запис зображення був указаний двічі поспіль; насправді рендериться лише друга копія. Це відома особливість.

---

Підводні камені#

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

---

Див. також#

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